43d9464ef9a55235b16021bbc315eb9d5a8e69b8
[babeltrace.git] / 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 */
This page took 0.03396 seconds and 3 git commands to generate.