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