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) __BT_NOEXCEPT;
  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                 __BT_NOEXCEPT;
 114
 115 /*! @} */
 116
 117 /*!
 118 @name User data
 119 @{
 120 */
 121
 122 /*!
 123 @brief
 124     Sets the user data of the \bt_msg_iter \bt_p{self_message_iterator}
 125     to \bt_p{data}.
 126
 127 @param[in] self_message_iterator
 128     Message iterator instance.
 129 @param[in] user_data
 130     New user data of \bt_p{self_message_iterator}.
 131
 132 @bt_pre_not_null{self_message_iterator}
 133
 134 @sa bt_self_message_iterator_get_data() &mdash;
 135     Returns the user data of a message iterator.
 136 */
 137 extern void bt_self_message_iterator_set_data(
 138                 bt_self_message_iterator *self_message_iterator,
 139                 void *user_data) __BT_NOEXCEPT;
 140
 141 /*!
 142 @brief
 143     Returns the user data of the \bt_msg_iter
 144     \bt_p{self_message_iterator}.
 145
 146 @param[in] self_message_iterator
 147     Message iterator instance.
 148
 149 @returns
 150     User data of \bt_p{self_message_iterator}.
 151
 152 @bt_pre_not_null{self_message_iterator}
 153
 154 @sa bt_self_message_iterator_set_data() &mdash;
 155     Sets the user data of a message iterator.
 156 */
 157 extern
 158 void *bt_self_message_iterator_get_data(
 159                 const bt_self_message_iterator *self_message_iterator)
 160                 __BT_NOEXCEPT;
 161
 162 /*! @} */
 163
 164 /*!
 165 @name Interruption query
 166 @{
 167 */
 168
 169 /*!
 170 @brief
 171     Returns whether or not the \bt_msg_iter \bt_p{self_message_iterator}
 172     is interrupted, that is, whether or not any of its \bt_p_intr
 173     is set.
 174
 175 @param[in] self_message_iterator
 176     Message iterator instance.
 177
 178 @returns
 179     #BT_TRUE if \bt_p{self_message_iterator} is interrupted (any of its
 180     interrupters is set).
 181
 182 @bt_pre_not_null{self_message_iterator}
 183
 184 @sa bt_graph_borrow_default_interrupter() &mdash;
 185     Borrows a trace processing graph's default interrupter.
 186 @sa bt_graph_add_interrupter() &mdash;
 187     Adds an interrupter to a graph.
 188 */
 189 extern bt_bool bt_self_message_iterator_is_interrupted(
 190                 const bt_self_message_iterator *self_message_iterator)
 191                 __BT_NOEXCEPT;
 192
 193 /*! @} */
 194
 195 /*!
 196 @name Configuration
 197 @{
 198 */
 199
 200 /*!
 201 @brief
 202     Sets whether or not the \bt_msg_iter of which the configuration
 203     is \bt_p{configuration} can seek forward.
 204
 205 A message iterator can seek forward if all the \bt_p_msg of its
 206 message sequence have some \bt_cs.
 207
 208 @attention
 209     You can only call this function during the execution of a
 210     message iterator's
 211     \ref api-msg-iter-cls-meth-init "initialization method".
 212
 213 @param[in] configuration
 214     Configuration of the message iterator of which to set whether or
 215     not it can seek forward.
 216 @param[in] can_seek_forward
 217     #BT_TRUE to make the message iterator of which the configuration is
 218     \bt_p{configuration} forward-seekable.
 219
 220 @bt_pre_not_null{configuration}
 221
 222 @sa bt_message_iterator_can_seek_forward() &mdash;
 223     Returns whether or not a message iterator can seek forward.
 224 */
 225 extern void bt_self_message_iterator_configuration_set_can_seek_forward(
 226                 bt_self_message_iterator_configuration *configuration,
 227                 bt_bool can_seek_forward) __BT_NOEXCEPT;
 228
 229 /*! @} */
 230
 231 /*! @} */
 232
 233 #ifdef __cplusplus
 234 }
 235 #endif
 236
 237 #endif /* BABELTRACE2_GRAPH_SELF_MESSAGE_ITERATOR_H */