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

   1 /*
   2  * SPDX-License-Identifier: MIT
   3  *
   4  * Copyright (C) 2010-2019 EfficiOS Inc. and Linux Foundation
   5  */
   6
   7 #ifndef BABELTRACE2_GRAPH_SELF_MESSAGE_ITERATOR_H
   8 #define BABELTRACE2_GRAPH_SELF_MESSAGE_ITERATOR_H
   9
  10 /* IWYU pragma: private, include <babeltrace2/babeltrace.h> */
  11
  12 #ifndef __BT_IN_BABELTRACE_H
  13 # error "Please include <babeltrace2/babeltrace.h> instead."
  14 #endif
  15
  16 #include <babeltrace2/types.h>
  17
  18 #ifdef __cplusplus
  19 extern "C" {
  20 #endif
  21
  22 /*!
  23 @defgroup api-self-msg-iter Self message iterator
  24 @ingroup api-msg-iter-cls
  25
  26 @brief
  27     Private view of a \bt_msg_iter for methods.
  28
  29 The #bt_self_message_iterator type is a private view of a \bt_msg_iter
  30 from within a \bt_msg_iter_cls method.
  31
  32 Borrow the \bt_comp which provides a message iterator with
  33 bt_self_message_iterator_borrow_component().
  34
  35 Borrow the \bt_oport on which a message iterator operates with
  36 bt_self_message_iterator_borrow_port().
  37
  38 Set and get user data attached to a message iterator with
  39 bt_self_message_iterator_set_data() and
  40 bt_self_message_iterator_get_data().
  41
  42 Check whether or not a message iterator is interrupted with
  43 bt_self_message_iterator_is_interrupted().
  44
  45 Set whether or not a message iterator can seek forward with
  46 bt_self_message_iterator_configuration_set_can_seek_forward().
  47 */
  48
  49 /*! @{ */
  50
  51 /*!
  52 @name Types
  53 @{
  54
  55 @typedef struct bt_self_message_iterator bt_self_message_iterator;
  56
  57 @brief
  58     Self \bt_msg_iter.
  59
  60 @typedef struct bt_self_message_iterator_configuration bt_self_message_iterator_configuration;
  61
  62 @brief
  63     Self \bt_msg_iter configuration.
  64
  65 @}
  66 */
  67
  68 /*!
  69 @name Component access
  70 @{
  71 */
  72
  73 /*!
  74 @brief
  75     Borrows the \bt_comp which provides the \bt_msg_iter
  76     \bt_p{self_message_iterator}.
  77
  78 @param[in] self_message_iterator
  79     Message iterator instance.
  80
  81 @returns
  82     Component which provides \bt_p{self_message_iterator}.
  83
  84 @bt_pre_not_null{self_message_iterator}
  85 */
  86 extern bt_self_component *
  87 bt_self_message_iterator_borrow_component(
  88                 bt_self_message_iterator *self_message_iterator);
  89
  90 /*! @} */
  91
  92 /*!
  93 @name Output port access
  94 @{
  95 */
  96
  97 /*!
  98 @brief
  99     Borrows the \bt_oport on which the \bt_msg_iter
 100     \bt_p{self_message_iterator} operates.
 101
 102 @param[in] self_message_iterator
 103     Message iterator instance.
 104
 105 @returns
 106     Output port on which \bt_p{self_message_iterator} operates.
 107
 108 @bt_pre_not_null{self_message_iterator}
 109 */
 110 extern bt_self_component_port_output *
 111 bt_self_message_iterator_borrow_port(
 112                 bt_self_message_iterator *self_message_iterator);
 113
 114 /*! @} */
 115
 116 /*!
 117 @name User data
 118 @{
 119 */
 120
 121 /*!
 122 @brief
 123     Sets the user data of the \bt_msg_iter \bt_p{self_message_iterator}
 124     to \bt_p{data}.
 125
 126 @param[in] self_message_iterator
 127     Message iterator instance.
 128 @param[in] user_data
 129     New user data of \bt_p{self_message_iterator}.
 130
 131 @bt_pre_not_null{self_message_iterator}
 132
 133 @sa bt_self_message_iterator_get_data() &mdash;
 134     Returns the user data of a message iterator.
 135 */
 136 extern void bt_self_message_iterator_set_data(
 137                 bt_self_message_iterator *self_message_iterator,
 138                 void *user_data);
 139
 140 /*!
 141 @brief
 142     Returns the user data of the \bt_msg_iter
 143     \bt_p{self_message_iterator}.
 144
 145 @param[in] self_message_iterator
 146     Message iterator instance.
 147
 148 @returns
 149     User data of \bt_p{self_message_iterator}.
 150
 151 @bt_pre_not_null{self_message_iterator}
 152
 153 @sa bt_self_message_iterator_set_data() &mdash;
 154     Sets the user data of a message iterator.
 155 */
 156 extern
 157 void *bt_self_message_iterator_get_data(
 158                 const bt_self_message_iterator *self_message_iterator);
 159
 160 /*! @} */
 161
 162 /*!
 163 @name Interruption query
 164 @{
 165 */
 166
 167 /*!
 168 @brief
 169     Returns whether or not the \bt_msg_iter \bt_p{self_message_iterator}
 170     is interrupted, that is, whether or not any of its \bt_p_intr
 171     is set.
 172
 173 @param[in] self_message_iterator
 174     Message iterator instance.
 175
 176 @returns
 177     #BT_TRUE if \bt_p{self_message_iterator} is interrupted (any of its
 178     interrupters is set).
 179
 180 @bt_pre_not_null{self_message_iterator}
 181
 182 @sa bt_graph_borrow_default_interrupter() &mdash;
 183     Borrows a trace processing graph's default interrupter.
 184 @sa bt_graph_add_interrupter() &mdash;
 185     Adds an interrupter to a graph.
 186 */
 187 extern bt_bool bt_self_message_iterator_is_interrupted(
 188                 const bt_self_message_iterator *self_message_iterator);
 189
 190 /*! @} */
 191
 192 /*!
 193 @name Configuration
 194 @{
 195 */
 196
 197 /*!
 198 @brief
 199     Sets whether or not the \bt_msg_iter of which the configuration
 200     is \bt_p{configuration} can seek forward.
 201
 202 A message iterator can seek forward if all the \bt_p_msg of its
 203 message sequence have some \bt_cs.
 204
 205 @attention
 206     You can only call this function during the execution of a
 207     message iterator's
 208     \ref api-msg-iter-cls-meth-init "initialization method".
 209
 210 @param[in] configuration
 211     Configuration of the message iterator of which to set whether or
 212     not it can seek forward.
 213 @param[in] can_seek_forward
 214     #BT_TRUE to make the message iterator of which the configuration is
 215     \bt_p{configuration} forward-seekable.
 216
 217 @bt_pre_not_null{configuration}
 218
 219 @sa bt_message_iterator_can_seek_forward() &mdash;
 220     Returns whether or not a message iterator can seek forward.
 221 */
 222 extern void bt_self_message_iterator_configuration_set_can_seek_forward(
 223                 bt_self_message_iterator_configuration *configuration,
 224                 bt_bool can_seek_forward);
 225
 226 /*! @} */
 227
 228 /*! @} */
 229
 230 #ifdef __cplusplus
 231 }
 232 #endif
 233
 234 #endif /* BABELTRACE2_GRAPH_SELF_MESSAGE_ITERATOR_H */