include/babeltrace2/graph/self-message-iterator.h

   1 #ifndef BABELTRACE2_GRAPH_SELF_MESSAGE_ITERATOR_H
   2 #define BABELTRACE2_GRAPH_SELF_MESSAGE_ITERATOR_H
   3
   4 /*
   5  * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
   6  *
   7  * Permission is hereby granted, free of charge, to any person obtaining a copy
   8  * of this software and associated documentation files (the "Software"), to deal
   9  * in the Software without restriction, including without limitation the rights
  10  * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
  11  * copies of the Software, and to permit persons to whom the Software is
  12  * furnished to do so, subject to the following conditions:
  13  *
  14  * The above copyright notice and this permission notice shall be included in
  15  * all copies or substantial portions of the Software.
  16  *
  17  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  18  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  19  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  20  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  21  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  22  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  23  * SOFTWARE.
  24  */
  25
  26 #ifndef __BT_IN_BABELTRACE_H
  27 # error "Please include <babeltrace2/babeltrace.h> instead."
  28 #endif
  29
  30 #include <babeltrace2/types.h>
  31
  32 #ifdef __cplusplus
  33 extern "C" {
  34 #endif
  35
  36 /*!
  37 @defgroup api-self-msg-iter Self message iterator
  38 @ingroup api-msg-iter-cls
  39
  40 @brief
  41     Private view of a \bt_msg_iter for methods.
  42
  43 The #bt_self_message_iterator type is a private view of a \bt_msg_iter
  44 from within a \bt_msg_iter_cls method.
  45
  46 Borrow the \bt_comp which provides a message iterator with
  47 bt_self_message_iterator_borrow_component().
  48
  49 Borrow the \bt_oport on which a message iterator operates with
  50 bt_self_message_iterator_borrow_port().
  51
  52 Set and get user data attached to a message iterator with
  53 bt_self_message_iterator_set_data() and
  54 bt_self_message_iterator_get_data().
  55
  56 Check whether or not a message iterator is interrupted with
  57 bt_self_message_iterator_is_interrupted().
  58
  59 Set whether or not a message iterator can seek forward with
  60 bt_self_message_iterator_configuration_set_can_seek_forward().
  61 */
  62
  63 /*! @{ */
  64
  65 /*!
  66 @name Types
  67 @{
  68
  69 @typedef struct bt_self_message_iterator bt_self_message_iterator;
  70
  71 @brief
  72     Self \bt_msg_iter.
  73
  74 @typedef struct bt_self_message_iterator_configuration bt_self_message_iterator_configuration;
  75
  76 @brief
  77     Self \bt_msg_iter configuration.
  78
  79 @}
  80 */
  81
  82 /*!
  83 @name Component access
  84 @{
  85 */
  86
  87 /*!
  88 @brief
  89     Borrows the \bt_comp which provides the \bt_msg_iter
  90     \bt_p{self_message_iterator}.
  91
  92 @param[in] self_message_iterator
  93     Message iterator instance.
  94
  95 @returns
  96     Component which provides \bt_p{self_message_iterator}.
  97
  98 @bt_pre_not_null{self_message_iterator}
  99 */
 100 extern bt_self_component *
 101 bt_self_message_iterator_borrow_component(
 102                 bt_self_message_iterator *self_message_iterator);
 103
 104 /*! @} */
 105
 106 /*!
 107 @name Output port access
 108 @{
 109 */
 110
 111 /*!
 112 @brief
 113     Borrows the \bt_oport on which the \bt_msg_iter
 114     \bt_p{self_message_iterator} operates.
 115
 116 @param[in] self_message_iterator
 117     Message iterator instance.
 118
 119 @returns
 120     Output port on which \bt_p{self_message_iterator} operates.
 121
 122 @bt_pre_not_null{self_message_iterator}
 123 */
 124 extern bt_self_component_port_output *
 125 bt_self_message_iterator_borrow_port(
 126                 bt_self_message_iterator *self_message_iterator);
 127
 128 /*! @} */
 129
 130 /*!
 131 @name User data
 132 @{
 133 */
 134
 135 /*!
 136 @brief
 137     Sets the user data of the \bt_msg_iter \bt_p{self_message_iterator}
 138     to \bt_p{data}.
 139
 140 @param[in] self_message_iterator
 141     Message iterator instance.
 142 @param[in] user_data
 143     New user data of \bt_p{self_message_iterator}.
 144
 145 @bt_pre_not_null{self_message_iterator}
 146
 147 @sa bt_self_message_iterator_get_data() &mdash;
 148     Returns the user data of a message iterator.
 149 */
 150 extern void bt_self_message_iterator_set_data(
 151                 bt_self_message_iterator *self_message_iterator,
 152                 void *user_data);
 153
 154 /*!
 155 @brief
 156     Returns the user data of the \bt_msg_iter
 157     \bt_p{self_message_iterator}.
 158
 159 @param[in] self_message_iterator
 160     Message iterator instance.
 161
 162 @returns
 163     User data of \bt_p{self_message_iterator}.
 164
 165 @bt_pre_not_null{self_message_iterator}
 166
 167 @sa bt_self_message_iterator_set_data() &mdash;
 168     Sets the user data of a message iterator.
 169 */
 170 extern
 171 void *bt_self_message_iterator_get_data(
 172                 const bt_self_message_iterator *self_message_iterator);
 173
 174 /*! @} */
 175
 176 /*!
 177 @name Interruption query
 178 @{
 179 */
 180
 181 /*!
 182 @brief
 183     Returns whether or not the \bt_msg_iter \bt_p{self_message_iterator}
 184     is interrupted, that is, whether or not any of its \bt_p_intr
 185     is set.
 186
 187 @param[in] self_message_iterator
 188     Message iterator instance.
 189
 190 @returns
 191     #BT_TRUE if \bt_p{self_message_iterator} is interrupted (any of its
 192     interrupters is set).
 193
 194 @bt_pre_not_null{self_message_iterator}
 195
 196 @sa bt_graph_borrow_default_interrupter() &mdash;
 197     Borrows a trace processing graph's default interrupter.
 198 @sa bt_graph_add_interrupter() &mdash;
 199     Adds an interrupter to a graph.
 200 */
 201 extern bt_bool bt_self_message_iterator_is_interrupted(
 202                 const bt_self_message_iterator *self_message_iterator);
 203
 204 /*! @} */
 205
 206 /*!
 207 @name Configuration
 208 @{
 209 */
 210
 211 /*!
 212 @brief
 213     Sets whether or not the \bt_msg_iter of which the configuration
 214     is \bt_p{configuration} can seek forward.
 215
 216 A message iterator can seek forward if all the \bt_p_msg of its
 217 message sequence have some \bt_cs.
 218
 219 @attention
 220     You can only call this function during the execution of a
 221     message iterator's
 222     \ref api-msg-iter-cls-meth-init "initialization method".
 223
 224 @param[in] configuration
 225     Configuration of the message iterator of which to set whether or
 226     not it can seek forward.
 227 @param[in] can_seek_forward
 228     #BT_TRUE to make the message iterator of which the configuration is
 229     \bt_p{configuration} forward-seekable.
 230
 231 @bt_pre_not_null{configuration}
 232
 233 @sa bt_message_iterator_can_seek_forward() &mdash;
 234     Returns whether or not a message iterator can seek forward.
 235 */
 236 extern void bt_self_message_iterator_configuration_set_can_seek_forward(
 237                 bt_self_message_iterator_configuration *configuration,
 238                 bt_bool can_seek_forward);
 239
 240 /*! @} */
 241
 242 /*! @} */
 243
 244 #ifdef __cplusplus
 245 }
 246 #endif
 247
 248 #endif /* BABELTRACE2_GRAPH_SELF_MESSAGE_ITERATOR_H */