Commit | Line | Data |
---|---|---|
d24d5663 | 1 | /* |
0235b0db | 2 | * SPDX-License-Identifier: MIT |
d24d5663 | 3 | * |
0235b0db | 4 | * Copyright (C) 2010-2019 EfficiOS Inc. and Linux Foundation |
d24d5663 PP |
5 | */ |
6 | ||
0235b0db MJ |
7 | #ifndef BABELTRACE2_GRAPH_MESSAGE_ITERATOR_H |
8 | #define BABELTRACE2_GRAPH_MESSAGE_ITERATOR_H | |
9 | ||
f38da6ca SM |
10 | /* IWYU pragma: private, include <babeltrace2/babeltrace.h> */ |
11 | ||
4fa90f32 PP |
12 | #ifndef __BT_IN_BABELTRACE_H |
13 | # error "Please include <babeltrace2/babeltrace.h> instead." | |
14 | #endif | |
d24d5663 PP |
15 | |
16 | #ifdef __cplusplus | |
17 | extern "C" { | |
18 | #endif | |
19 | ||
43c59509 PP |
20 | /*! |
21 | @defgroup api-msg-iter Message iterator | |
22 | @ingroup api-comp-cls-dev | |
23 | ||
24 | @brief | |
25 | Iterator of a \bt_msg sequence. | |
26 | ||
27 | A <strong><em>message iterator</em></strong> iterates a sequence of | |
28 | \bt_p_msg. | |
29 | ||
30 | A message iterator is the \bt_name mechanism for the \bt_p_comp of a | |
31 | trace processing \bt_graph to exchange information. This information | |
32 | takes the form of a sequence of individual messages which contain | |
33 | trace data (\bt_p_ev, for example). | |
34 | ||
35 | A message iterator is a \bt_msg_iter_cls instance. Because a message | |
36 | iterator class is part of a \bt_src_comp_cls or \bt_flt_comp_cls, a | |
37 | message iterator is part of a \bt_src_comp or \bt_flt_comp. Borrow | |
38 | a message iterator's component with | |
39 | bt_message_iterator_borrow_component(). | |
40 | ||
41 | A message iterator is a \ref api-fund-shared-object "shared object": get | |
42 | a new reference with bt_component_get_ref() and put an existing | |
43 | reference with bt_component_put_ref(). | |
44 | ||
45 | The type of a message iterator is #bt_message_iterator. | |
46 | ||
47 | There are two contexts from which you can create a message iterator: | |
48 | ||
49 | <dl> | |
50 | <dt>From another message iterator</dt> | |
51 | <dd> | |
52 | This is the case for a \bt_flt_comp's message iterator. | |
53 | ||
54 | Use bt_message_iterator_create_from_message_iterator(). | |
55 | ||
56 | You can call this function from any message iterator | |
57 | \ref api-msg-iter-cls-methods "method" except the | |
58 | \ref api-msg-iter-cls-meth-fini "finalization method". | |
59 | </dd> | |
60 | ||
61 | <dt>From a \bt_sink_comp</dt> | |
62 | <dd> | |
63 | Use bt_message_iterator_create_from_sink_component(). | |
64 | ||
65 | You can call this function from a sink component | |
66 | \ref api-comp-cls-dev-methods "method" once the trace processing | |
67 | graph which contains the component is | |
68 | \ref api-graph-lc "configured", that is: | |
69 | ||
70 | - \ref api-comp-cls-dev-meth-graph-configured "Graph is configured" | |
71 | method (typical). | |
72 | ||
73 | - \ref api-comp-cls-dev-meth-consume "Consume" method. | |
74 | </dd> | |
75 | </dl> | |
76 | ||
77 | When you call one of the creation functions above, you pass an \bt_iport | |
78 | on which to create the message iterator. | |
79 | ||
80 | You can create more than one message iterator on a given | |
81 | <em>\ref api-port-prop-is-connected "connected"</em> input port. The | |
82 | \bt_p_conn between \bt_p_port in a trace processing \bt_graph establish | |
83 | which \bt_p_comp and message iterators can create message iterators of | |
84 | other \bt_p_comp. Then: | |
85 | ||
86 | - Any \bt_sink_comp is free to create one or more message iterators | |
87 | on any of its connected input ports. | |
88 | ||
89 | - Any message iterator is free to create one or more message iterators | |
90 | on any of its component's connected input ports. | |
91 | ||
92 | The following illustration shows a very simple use case where the | |
93 | \ref api-comp-cls-dev-meth-consume "consuming method" of a sink | |
94 | component uses a single \bt_flt_comp's message iterator which itself | |
95 | uses a single \bt_src_comp's message iterator: | |
96 | ||
97 | @image html msg-iter.png | |
98 | ||
99 | Many message iterator relations are possible, for example: | |
100 | ||
101 | @image html msg-iter-complex.png | |
102 | ||
103 | <h1>\anchor api-msg-iter-ops Operations</h1> | |
104 | ||
105 | Once you have created a message iterator, there are three possible | |
106 | operations: | |
107 | ||
108 | <dl> | |
109 | <dt> | |
110 | \anchor api-msg-iter-op-next | |
111 | Get the message iterator's next messages | |
112 | </dt> | |
113 | <dd> | |
114 | This operation returns a batch of the message iterator's next | |
115 | \bt_p_msg considering its current state. | |
116 | ||
117 | This operation returns a batch of messages instead of a single | |
118 | message for performance reasons. | |
119 | ||
120 | This operation is said to \em advance the message iterator. | |
121 | ||
122 | Get the next messages of a message iterator with | |
123 | bt_message_iterator_next(). | |
124 | </dd> | |
125 | ||
126 | <dt> | |
127 | \anchor api-msg-iter-op-seek-beg | |
128 | Make the message iterator seek its beginning | |
129 | </dt> | |
130 | <dd> | |
131 | This operation resets the message iterator's position to the | |
132 | beginning of its \ref api-msg-seq "message sequence". | |
133 | ||
134 | If the operation is successful, then the next call to | |
135 | bt_message_iterator_next() returns the first \bt_p_msg of the | |
136 | message iterator's sequence. | |
137 | ||
138 | If bt_message_iterator_seek_ns_from_origin() returns something | |
139 | else than #BT_MESSAGE_ITERATOR_SEEK_BEGINNING_STATUS_OK, you | |
140 | \em cannot call bt_message_iterator_next() afterwards. In that case, | |
141 | you can only call bt_message_iterator_seek_beginning() again or | |
142 | bt_message_iterator_seek_ns_from_origin(). | |
143 | ||
144 | Before you call bt_message_iterator_seek_beginning() to make | |
145 | the message iterator seek its beginning, check if it can currently | |
146 | do it with bt_message_iterator_can_seek_beginning(). | |
147 | </dd> | |
148 | ||
149 | <dt> | |
150 | \anchor api-msg-iter-op-seek-ns | |
118ae153 | 151 | Make the message iterator seek a message occurring at or after a |
43c59509 PP |
152 | given time (in nanoseconds) from its clock class origin |
153 | </dt> | |
154 | <dd> | |
155 | This operation changes the position of the message iterator within | |
156 | its \ref api-msg-seq "sequence" so that the next call to | |
157 | bt_message_iterator_next() returns \bt_p_msg which occur at or after | |
158 | a given time (in nanoseconds) from its | |
159 | \ref api-tir-clock-cls-origin "clock class origin". | |
160 | ||
161 | When you call bt_message_iterator_seek_ns_from_origin() to perform | |
162 | the operation, your pass the specific time to seek as the | |
163 | \bt_p{ns_from_origin} parameter. You don't pass any | |
164 | \bt_clock_cls: the function operates at the nanosecond from some | |
165 | origin level and it is left to the message iterator's implementation | |
166 | to seek a message having at least this time. | |
167 | ||
168 | If the requested time point is \em after the message iterator's | |
169 | sequence's last message, then the next call to | |
170 | bt_message_iterator_next() returns | |
171 | #BT_MESSAGE_ITERATOR_NEXT_STATUS_END. | |
172 | ||
173 | If bt_message_iterator_seek_ns_from_origin() returns something | |
174 | else than #BT_MESSAGE_ITERATOR_SEEK_NS_FROM_ORIGIN_STATUS_OK, you | |
175 | \em cannot call bt_message_iterator_next() afterwards. In that case, | |
176 | you can only call bt_message_iterator_seek_ns_from_origin() again | |
177 | or bt_message_iterator_seek_beginning(). | |
178 | ||
179 | Before you call bt_message_iterator_seek_ns_from_origin() to make | |
180 | the message iterator seek a specific point in time, check if it can | |
181 | currently do it with bt_message_iterator_can_seek_ns_from_origin(). | |
182 | </dd> | |
183 | </dl> | |
184 | */ | |
185 | ||
186 | /*! @{ */ | |
187 | ||
188 | /*! | |
189 | @name Type | |
190 | @{ | |
191 | ||
192 | @typedef struct bt_message_iterator bt_message_iterator; | |
193 | ||
194 | @brief | |
195 | Message iterator. | |
196 | ||
197 | @} | |
198 | */ | |
199 | ||
200 | /*! | |
201 | @name Creation | |
202 | @{ | |
203 | */ | |
204 | ||
205 | /*! | |
206 | @brief | |
207 | Status code for bt_message_iterator_create_from_message_iterator(). | |
208 | */ | |
209 | typedef enum bt_message_iterator_create_from_message_iterator_status { | |
210 | /*! | |
211 | @brief | |
212 | Success. | |
213 | */ | |
214 | BT_MESSAGE_ITERATOR_CREATE_FROM_MESSAGE_ITERATOR_STATUS_OK = __BT_FUNC_STATUS_OK, | |
215 | ||
216 | /*! | |
217 | @brief | |
218 | Out of memory. | |
219 | */ | |
220 | BT_MESSAGE_ITERATOR_CREATE_FROM_MESSAGE_ITERATOR_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR, | |
221 | ||
222 | /*! | |
223 | @brief | |
224 | Other error. | |
225 | */ | |
226 | BT_MESSAGE_ITERATOR_CREATE_FROM_MESSAGE_ITERATOR_STATUS_ERROR = __BT_FUNC_STATUS_ERROR, | |
227 | } bt_message_iterator_create_from_message_iterator_status; | |
228 | ||
229 | /*! | |
230 | @brief | |
231 | Creates a message iterator on the \bt_iport \bt_p{port} from | |
232 | another message iterator \bt_p{self_message_iterator}, and sets | |
233 | \bt_p{*message_iterator} to the resulting message iterator. | |
234 | ||
235 | On success, the message iterator's position is at the beginning | |
236 | of its \ref api-msg-seq "message sequence". | |
237 | ||
238 | @param[in] self_message_iterator | |
239 | Other message iterator from which to create the message iterator. | |
240 | @param[in] port | |
241 | Input port on which to create the message iterator. | |
242 | @param[out] message_iterator | |
243 | <strong>On success</strong>, \bt_p{*message_iterator} is a new | |
244 | message iterator reference. | |
245 | ||
246 | @retval #BT_MESSAGE_ITERATOR_CREATE_FROM_MESSAGE_ITERATOR_STATUS_OK | |
247 | Success. | |
248 | @retval #BT_MESSAGE_ITERATOR_CREATE_FROM_MESSAGE_ITERATOR_STATUS_MEMORY_ERROR | |
249 | Out of memory. | |
250 | @retval #BT_MESSAGE_ITERATOR_CREATE_FROM_MESSAGE_ITERATOR_STATUS_ERROR | |
251 | Other error, for example, the created message iterator's | |
252 | \ref api-msg-iter-cls-meth-init "initialization method" failed. | |
253 | ||
254 | @bt_pre_not_null{self_message_iterator} | |
255 | @bt_pre_not_null{port} | |
256 | @pre | |
257 | <code>bt_port_is_connected(port)</code> returns #BT_TRUE. | |
258 | @bt_pre_not_null{message_iterator} | |
259 | ||
260 | @sa bt_message_iterator_create_from_sink_component() — | |
261 | Creates a message iterator from a \bt_sink_comp. | |
262 | */ | |
263 | extern bt_message_iterator_create_from_message_iterator_status | |
264 | bt_message_iterator_create_from_message_iterator( | |
265 | bt_self_message_iterator *self_message_iterator, | |
266 | bt_self_component_port_input *port, | |
4c81a2b7 | 267 | bt_message_iterator **message_iterator) __BT_NOEXCEPT; |
43c59509 PP |
268 | |
269 | /*! | |
270 | @brief | |
271 | Status code for bt_message_iterator_create_from_sink_component(). | |
272 | */ | |
273 | typedef enum bt_message_iterator_create_from_sink_component_status { | |
274 | /*! | |
275 | @brief | |
276 | Success. | |
277 | */ | |
278 | BT_MESSAGE_ITERATOR_CREATE_FROM_SINK_COMPONENT_STATUS_OK = __BT_FUNC_STATUS_OK, | |
279 | ||
280 | /*! | |
281 | @brief | |
282 | Out of memory. | |
283 | */ | |
284 | BT_MESSAGE_ITERATOR_CREATE_FROM_SINK_COMPONENT_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR, | |
285 | ||
286 | /*! | |
287 | @brief | |
288 | Other error. | |
289 | */ | |
290 | BT_MESSAGE_ITERATOR_CREATE_FROM_SINK_COMPONENT_STATUS_ERROR = __BT_FUNC_STATUS_ERROR, | |
291 | } bt_message_iterator_create_from_sink_component_status; | |
292 | ||
293 | /*! | |
294 | @brief | |
295 | Creates a message iterator on the \bt_iport \bt_p{port} from the | |
296 | \bt_sink_comp \bt_p{self_component_sink}, and sets | |
297 | \bt_p{*message_iterator} to the resulting message iterator. | |
298 | ||
299 | On success, the message iterator's position is at the beginning | |
300 | of its \ref api-msg-seq "message sequence". | |
301 | ||
302 | @param[in] self_component_sink | |
303 | Sink component from which to create the message iterator. | |
304 | @param[in] port | |
305 | Input port on which to create the message iterator. | |
306 | @param[out] message_iterator | |
307 | <strong>On success</strong>, \bt_p{*message_iterator} is a new | |
308 | message iterator reference. | |
309 | ||
310 | @retval #BT_MESSAGE_ITERATOR_CREATE_FROM_MESSAGE_ITERATOR_STATUS_OK | |
311 | Success. | |
312 | @retval #BT_MESSAGE_ITERATOR_CREATE_FROM_MESSAGE_ITERATOR_STATUS_MEMORY_ERROR | |
313 | Out of memory. | |
314 | @retval #BT_MESSAGE_ITERATOR_CREATE_FROM_MESSAGE_ITERATOR_STATUS_ERROR | |
315 | Other error, for example, the created message iterator's | |
316 | \ref api-msg-iter-cls-meth-init "initialization method" failed. | |
317 | ||
318 | @bt_pre_not_null{self_component_sink} | |
319 | @bt_pre_not_null{port} | |
320 | @pre | |
321 | <code>bt_port_is_connected(port)</code> returns #BT_TRUE. | |
322 | @bt_pre_not_null{message_iterator} | |
323 | ||
324 | @sa bt_message_iterator_create_from_message_iterator() — | |
325 | Creates a message iterator from another message iterator. | |
326 | */ | |
327 | extern bt_message_iterator_create_from_sink_component_status | |
328 | bt_message_iterator_create_from_sink_component( | |
329 | bt_self_component_sink *self_component_sink, | |
330 | bt_self_component_port_input *port, | |
4c81a2b7 | 331 | bt_message_iterator **message_iterator) __BT_NOEXCEPT; |
43c59509 PP |
332 | |
333 | /*! @} */ | |
334 | ||
335 | /*! | |
336 | @name Component access | |
337 | @{ | |
338 | */ | |
339 | ||
340 | /*! | |
341 | @brief | |
342 | Borrows the \bt_comp which provides the \bt_msg_iter | |
343 | \bt_p{message_iterator}. | |
344 | ||
345 | @param[in] message_iterator | |
346 | Message iterator from which to borrow the component which provides | |
347 | it. | |
348 | ||
349 | @returns | |
350 | Component which provides \bt_p{message_iterator}. | |
351 | ||
352 | @bt_pre_not_null{message_iterator} | |
353 | */ | |
354 | extern bt_component * | |
355 | bt_message_iterator_borrow_component( | |
4c81a2b7 | 356 | bt_message_iterator *message_iterator) __BT_NOEXCEPT; |
43c59509 PP |
357 | |
358 | /*! @} */ | |
359 | ||
360 | /*! | |
361 | @name "Next" operation (get next messages) | |
362 | @{ | |
363 | */ | |
364 | ||
365 | /*! | |
366 | @brief | |
367 | Status code for bt_message_iterator_next(). | |
368 | */ | |
d24d5663 | 369 | typedef enum bt_message_iterator_next_status { |
43c59509 PP |
370 | /*! |
371 | @brief | |
372 | Success. | |
373 | */ | |
d24d5663 | 374 | BT_MESSAGE_ITERATOR_NEXT_STATUS_OK = __BT_FUNC_STATUS_OK, |
43c59509 PP |
375 | |
376 | /*! | |
377 | @brief | |
378 | End of iteration. | |
379 | */ | |
d24d5663 | 380 | BT_MESSAGE_ITERATOR_NEXT_STATUS_END = __BT_FUNC_STATUS_END, |
43c59509 PP |
381 | |
382 | /*! | |
383 | @brief | |
384 | Try again. | |
385 | */ | |
d24d5663 | 386 | BT_MESSAGE_ITERATOR_NEXT_STATUS_AGAIN = __BT_FUNC_STATUS_AGAIN, |
43c59509 PP |
387 | |
388 | /*! | |
389 | @brief | |
390 | Out of memory. | |
391 | */ | |
d24d5663 | 392 | BT_MESSAGE_ITERATOR_NEXT_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR, |
43c59509 PP |
393 | |
394 | /*! | |
395 | @brief | |
396 | Other error. | |
397 | */ | |
398 | BT_MESSAGE_ITERATOR_NEXT_STATUS_ERROR = __BT_FUNC_STATUS_ERROR, | |
d24d5663 PP |
399 | } bt_message_iterator_next_status; |
400 | ||
43c59509 PP |
401 | /*! |
402 | @brief | |
403 | Returns the next \bt_p_msg of the message iterator | |
404 | \bt_p{message_iterator} into the \bt_p{*messages} array of size | |
405 | \bt_p{*count}, effectively advancing \bt_p{message_iterator}. | |
d24d5663 | 406 | |
43c59509 PP |
407 | See \ref api-msg-iter-op-next "this operation's documentation". |
408 | ||
409 | On success, the message iterator's position is advanced by \bt_p{*count} | |
410 | messages. | |
411 | ||
412 | @param[in] message_iterator | |
413 | Message iterator from which to get the next messages. | |
414 | @param[out] messages | |
415 | @parblock | |
416 | <strong>On success</strong>, \bt_p{*messages} is an array containing | |
417 | the next messages of \bt_p{message_iterator} as its first elements. | |
418 | ||
419 | \bt_p{*count} is the number of messages in \bt_p{*messages}. | |
d24d5663 | 420 | |
43c59509 PP |
421 | The library allocates and manages this array, but until you |
422 | perform another \ref api-msg-iter-ops "operation" on | |
423 | \bt_p{message_iterator}, you are free to modify it. For example, | |
424 | you can set its elements to \c NULL if your use case needs it. | |
425 | ||
426 | You own the references of the messages this array contains. In | |
427 | other words, you must put them with bt_message_put_ref() or move | |
428 | them to another message array (from a | |
429 | \link api-msg-iter-cls-meth-next "next" method\endlink) | |
430 | before you perform another operation on \bt_p{message_iterator} or | |
431 | before \bt_p{message_iterator} is destroyed. | |
432 | @endparblock | |
433 | @param[out] count | |
434 | <strong>On success</strong>, \bt_p{*count} is the number of messages | |
435 | in \bt_p{*messages}. | |
436 | ||
437 | @retval #BT_MESSAGE_ITERATOR_NEXT_STATUS_OK | |
438 | Success. | |
439 | @retval #BT_MESSAGE_ITERATOR_NEXT_STATUS_END | |
440 | End of iteration. | |
441 | @retval #BT_MESSAGE_ITERATOR_NEXT_STATUS_AGAIN | |
442 | Try again. | |
443 | @retval #BT_MESSAGE_ITERATOR_NEXT_STATUS_MEMORY_ERROR | |
444 | Out of memory. | |
445 | @retval #BT_MESSAGE_ITERATOR_NEXT_STATUS_ERROR | |
446 | Other error. | |
447 | ||
448 | @bt_pre_not_null{message_iterator} | |
449 | @bt_pre_not_null{messages} | |
450 | @bt_pre_not_null{count} | |
451 | ||
452 | @post | |
453 | <strong>On success</strong>, \bt_p{*count} ≥ 1. | |
454 | */ | |
455 | extern bt_message_iterator_next_status | |
456 | bt_message_iterator_next(bt_message_iterator *message_iterator, | |
4c81a2b7 PP |
457 | bt_message_array_const *messages, uint64_t *count) |
458 | __BT_NOEXCEPT; | |
43c59509 PP |
459 | |
460 | /*! @} */ | |
461 | ||
462 | /*! | |
463 | @name Seeking | |
464 | @{ | |
465 | */ | |
466 | ||
467 | /*! | |
468 | @brief | |
469 | Status code for bt_message_iterator_can_seek_beginning(). | |
470 | */ | |
f2fb1b32 | 471 | typedef enum bt_message_iterator_can_seek_beginning_status { |
43c59509 PP |
472 | /*! |
473 | @brief | |
474 | Success. | |
475 | */ | |
f2fb1b32 | 476 | BT_MESSAGE_ITERATOR_CAN_SEEK_BEGINNING_STATUS_OK = __BT_FUNC_STATUS_OK, |
43c59509 PP |
477 | |
478 | /*! | |
479 | @brief | |
480 | Try again. | |
481 | */ | |
f2fb1b32 | 482 | BT_MESSAGE_ITERATOR_CAN_SEEK_BEGINNING_STATUS_AGAIN = __BT_FUNC_STATUS_AGAIN, |
43c59509 PP |
483 | |
484 | /*! | |
485 | @brief | |
486 | Out of memory. | |
487 | */ | |
f2fb1b32 | 488 | BT_MESSAGE_ITERATOR_CAN_SEEK_BEGINNING_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR, |
43c59509 PP |
489 | |
490 | /*! | |
491 | @brief | |
492 | Other error. | |
493 | */ | |
494 | BT_MESSAGE_ITERATOR_CAN_SEEK_BEGINNING_STATUS_ERROR = __BT_FUNC_STATUS_ERROR, | |
f2fb1b32 SM |
495 | } bt_message_iterator_can_seek_beginning_status; |
496 | ||
43c59509 PP |
497 | /*! |
498 | @brief | |
499 | Returns whether or not the message iterator \bt_p{message_iterator} | |
500 | can currently seek its beginning (first \bt_msg). | |
501 | ||
502 | See the \link api-msg-iter-op-seek-beg "seek beginning" | |
503 | operation\endlink. | |
504 | ||
505 | Make sure to call this function, without performing any other | |
506 | \ref api-msg-iter-ops "operation" on \bt_p{message_iterator}, before you | |
507 | call bt_message_iterator_seek_beginning(). | |
508 | ||
509 | @param[in] message_iterator | |
510 | Message iterator from which to to get whether or not it can seek | |
511 | its beginning. | |
512 | @param[out] can_seek_beginning | |
513 | <strong>On success</strong>, \bt_p{*can_seek_beginning} is #BT_TRUE | |
514 | if \bt_p{message_iterator} can seek its beginning. | |
515 | ||
516 | @retval #BT_MESSAGE_ITERATOR_CAN_SEEK_BEGINNING_STATUS_OK | |
517 | Success. | |
518 | @retval #BT_MESSAGE_ITERATOR_CAN_SEEK_BEGINNING_STATUS_AGAIN | |
519 | Try again. | |
520 | @retval #BT_MESSAGE_ITERATOR_CAN_SEEK_BEGINNING_STATUS_MEMORY_ERROR | |
521 | Out of memory. | |
522 | @retval #BT_MESSAGE_ITERATOR_CAN_SEEK_BEGINNING_STATUS_ERROR | |
523 | Other error. | |
524 | ||
525 | @bt_pre_not_null{message_iterator} | |
526 | @bt_pre_not_null{can_seek_beginning} | |
527 | ||
528 | @sa bt_message_iterator_seek_beginning() — | |
529 | Makes a message iterator seek its beginning. | |
530 | */ | |
531 | extern bt_message_iterator_can_seek_beginning_status | |
532 | bt_message_iterator_can_seek_beginning( | |
533 | bt_message_iterator *message_iterator, | |
4c81a2b7 | 534 | bt_bool *can_seek_beginning) __BT_NOEXCEPT; |
43c59509 PP |
535 | |
536 | /*! | |
537 | @brief | |
538 | Status code for bt_message_iterator_seek_beginning(). | |
539 | */ | |
540 | typedef enum bt_message_iterator_seek_beginning_status { | |
541 | /*! | |
542 | @brief | |
543 | Success. | |
544 | */ | |
545 | BT_MESSAGE_ITERATOR_SEEK_BEGINNING_STATUS_OK = __BT_FUNC_STATUS_OK, | |
546 | ||
547 | /*! | |
548 | @brief | |
549 | Try again. | |
550 | */ | |
551 | BT_MESSAGE_ITERATOR_SEEK_BEGINNING_STATUS_AGAIN = __BT_FUNC_STATUS_AGAIN, | |
552 | ||
553 | /*! | |
554 | @brief | |
555 | Out of memory. | |
556 | */ | |
557 | BT_MESSAGE_ITERATOR_SEEK_BEGINNING_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR, | |
558 | ||
559 | /*! | |
560 | @brief | |
561 | Other error. | |
562 | */ | |
563 | BT_MESSAGE_ITERATOR_SEEK_BEGINNING_STATUS_ERROR = __BT_FUNC_STATUS_ERROR, | |
564 | } bt_message_iterator_seek_beginning_status; | |
565 | ||
566 | /*! | |
567 | @brief | |
568 | Makes the message iterator \bt_p{message_iterator} seek its | |
569 | beginning (first \bt_msg). | |
570 | ||
571 | See \ref api-msg-iter-op-seek-beg "this operation's documentation". | |
572 | ||
573 | Make sure to call bt_message_iterator_can_seek_beginning(), | |
574 | without performing any other \ref api-msg-iter-ops "operation" on | |
575 | \bt_p{message_iterator}, before you call this function. | |
576 | ||
577 | @param[in] message_iterator | |
578 | Message iterator to seek to its beginning. | |
579 | ||
580 | @retval #BT_MESSAGE_ITERATOR_SEEK_BEGINNING_STATUS_OK | |
581 | Success. | |
582 | @retval #BT_MESSAGE_ITERATOR_SEEK_BEGINNING_STATUS_AGAIN | |
583 | Try again. | |
584 | @retval #BT_MESSAGE_ITERATOR_SEEK_BEGINNING_STATUS_MEMORY_ERROR | |
585 | Out of memory. | |
586 | @retval #BT_MESSAGE_ITERATOR_SEEK_BEGINNING_STATUS_ERROR | |
587 | Other error. | |
588 | ||
589 | @bt_pre_not_null{message_iterator} | |
590 | @pre | |
591 | <code>bt_message_iterator_can_seek_beginning(message_iterator)</code> | |
592 | returns #BT_TRUE. | |
593 | ||
594 | @sa bt_message_iterator_can_seek_beginning() — | |
595 | Returns whether or not a message iterator can currently seek its | |
596 | beginning. | |
597 | */ | |
598 | extern bt_message_iterator_seek_beginning_status | |
599 | bt_message_iterator_seek_beginning( | |
4c81a2b7 | 600 | bt_message_iterator *message_iterator) __BT_NOEXCEPT; |
43c59509 PP |
601 | |
602 | /*! | |
603 | @brief | |
604 | Status code for bt_message_iterator_can_seek_ns_from_origin(). | |
605 | */ | |
f2fb1b32 | 606 | typedef enum bt_message_iterator_can_seek_ns_from_origin_status { |
43c59509 PP |
607 | /*! |
608 | @brief | |
609 | Success. | |
610 | */ | |
f2fb1b32 | 611 | BT_MESSAGE_ITERATOR_CAN_SEEK_NS_FROM_ORIGIN_STATUS_OK = __BT_FUNC_STATUS_OK, |
43c59509 PP |
612 | |
613 | /*! | |
614 | @brief | |
615 | Try again. | |
616 | */ | |
f2fb1b32 | 617 | BT_MESSAGE_ITERATOR_CAN_SEEK_NS_FROM_ORIGIN_STATUS_AGAIN = __BT_FUNC_STATUS_AGAIN, |
43c59509 PP |
618 | |
619 | /*! | |
620 | @brief | |
621 | Out of memory. | |
622 | */ | |
f2fb1b32 | 623 | BT_MESSAGE_ITERATOR_CAN_SEEK_NS_FROM_ORIGIN_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR, |
43c59509 PP |
624 | |
625 | /*! | |
626 | @brief | |
627 | Other error. | |
628 | */ | |
629 | BT_MESSAGE_ITERATOR_CAN_SEEK_NS_FROM_ORIGIN_STATUS_ERROR = __BT_FUNC_STATUS_ERROR, | |
f2fb1b32 SM |
630 | } bt_message_iterator_can_seek_ns_from_origin_status; |
631 | ||
43c59509 PP |
632 | /*! |
633 | @brief | |
634 | Returns whether or not the message iterator \bt_p{message_iterator} | |
118ae153 | 635 | can currently seek a \bt_msg occurring at or after |
43c59509 PP |
636 | \bt_p{ns_from_origin} nanoseconds from its |
637 | \ref api-tir-clock-cls-origin "clock class origin". | |
9a2c8b8e | 638 | |
43c59509 PP |
639 | See the \link api-msg-iter-op-seek-ns "seek ns from origin" |
640 | operation\endlink. | |
9a2c8b8e | 641 | |
43c59509 PP |
642 | Make sure to call this function, without performing any other |
643 | \ref api-msg-iter-ops "operation" on \bt_p{message_iterator}, before you | |
644 | call bt_message_iterator_seek_ns_from_origin(). | |
9a2c8b8e | 645 | |
43c59509 PP |
646 | @param[in] message_iterator |
647 | Message iterator from which to to get whether or not it can seek | |
648 | its beginning. | |
649 | @param[in] ns_from_origin | |
650 | Requested time point to seek. | |
651 | @param[out] can_seek_ns_from_origin | |
652 | <strong>On success</strong>, \bt_p{*can_seek_ns_from_origin} is | |
118ae153 | 653 | #BT_TRUE if \bt_p{message_iterator} can seek a message occurring at |
43c59509 PP |
654 | or after \bt_p{ns_from_origin} nanoseconds from its clock class |
655 | origin. | |
9a2c8b8e | 656 | |
43c59509 PP |
657 | @retval #BT_MESSAGE_ITERATOR_CAN_SEEK_NS_FROM_ORIGIN_STATUS_OK |
658 | Success. | |
659 | @retval #BT_MESSAGE_ITERATOR_CAN_SEEK_NS_FROM_ORIGIN_STATUS_AGAIN | |
660 | Try again. | |
661 | @retval #BT_MESSAGE_ITERATOR_CAN_SEEK_NS_FROM_ORIGIN_STATUS_MEMORY_ERROR | |
662 | Out of memory. | |
663 | @retval #BT_MESSAGE_ITERATOR_CAN_SEEK_NS_FROM_ORIGIN_STATUS_ERROR | |
664 | Other error. | |
9a2c8b8e | 665 | |
43c59509 PP |
666 | @bt_pre_not_null{message_iterator} |
667 | @bt_pre_not_null{can_seek_ns_from_origin} | |
9a2c8b8e | 668 | |
43c59509 | 669 | @sa bt_message_iterator_seek_ns_from_origin() — |
118ae153 | 670 | Makes a message iterator seek a message occurring at or after |
43c59509 PP |
671 | a given time from its clock class origin. |
672 | */ | |
9a2c8b8e PP |
673 | |
674 | extern bt_message_iterator_can_seek_ns_from_origin_status | |
675 | bt_message_iterator_can_seek_ns_from_origin( | |
43c59509 | 676 | bt_message_iterator *message_iterator, |
4c81a2b7 PP |
677 | int64_t ns_from_origin, bt_bool *can_seek_ns_from_origin) |
678 | __BT_NOEXCEPT; | |
9a2c8b8e | 679 | |
43c59509 PP |
680 | /*! |
681 | @brief | |
682 | Status code for bt_message_iterator_seek_ns_from_origin(). | |
683 | */ | |
684 | typedef enum bt_message_iterator_seek_ns_from_origin_status { | |
685 | /*! | |
686 | @brief | |
687 | Success. | |
688 | */ | |
689 | BT_MESSAGE_ITERATOR_SEEK_NS_FROM_ORIGIN_STATUS_OK = __BT_FUNC_STATUS_OK, | |
690 | ||
691 | /*! | |
692 | @brief | |
693 | Try again. | |
694 | */ | |
695 | BT_MESSAGE_ITERATOR_SEEK_NS_FROM_ORIGIN_STATUS_AGAIN = __BT_FUNC_STATUS_AGAIN, | |
696 | ||
697 | /*! | |
698 | @brief | |
699 | Out of memory. | |
700 | */ | |
701 | BT_MESSAGE_ITERATOR_SEEK_NS_FROM_ORIGIN_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR, | |
702 | ||
703 | /*! | |
704 | @brief | |
705 | Other error. | |
706 | */ | |
707 | BT_MESSAGE_ITERATOR_SEEK_NS_FROM_ORIGIN_STATUS_ERROR = __BT_FUNC_STATUS_ERROR, | |
708 | } bt_message_iterator_seek_ns_from_origin_status; | |
709 | ||
710 | /*! | |
711 | @brief | |
712 | Makes the message iterator \bt_p{message_iterator} seek a \bt_msg | |
118ae153 | 713 | occurring at or after \bt_p{ns_from_origin} nanoseconds from its |
43c59509 PP |
714 | \ref api-tir-clock-cls-origin "clock class origin". |
715 | ||
716 | See \ref api-msg-iter-op-seek-ns "this operation's documentation". | |
717 | ||
718 | Make sure to call bt_message_iterator_can_seek_ns_from_origin(), | |
719 | without performing any other \ref api-msg-iter-ops "operation" on | |
720 | \bt_p{message_iterator}, before you call this function. | |
721 | ||
722 | @param[in] message_iterator | |
118ae153 | 723 | Message iterator to seek to a message occurring at or after |
43c59509 PP |
724 | \bt_p{ns_from_origin} nanoseconds from its clock class origin. |
725 | @param[in] ns_from_origin | |
726 | Time point to seek. | |
727 | ||
728 | @retval #BT_MESSAGE_ITERATOR_SEEK_NS_FROM_ORIGIN_STATUS_OK | |
729 | Success. | |
730 | @retval #BT_MESSAGE_ITERATOR_SEEK_NS_FROM_ORIGIN_STATUS_AGAIN | |
731 | Try again. | |
732 | @retval #BT_MESSAGE_ITERATOR_SEEK_NS_FROM_ORIGIN_STATUS_MEMORY_ERROR | |
733 | Out of memory. | |
734 | @retval #BT_MESSAGE_ITERATOR_SEEK_NS_FROM_ORIGIN_STATUS_ERROR | |
735 | Other error. | |
9a2c8b8e | 736 | |
43c59509 PP |
737 | @bt_pre_not_null{message_iterator} |
738 | @pre | |
739 | <code>bt_message_iterator_can_seek_ns_from_origin(message_iterator, ns_from_origin)</code> | |
740 | returns #BT_TRUE. | |
741 | ||
742 | @sa bt_message_iterator_can_seek_ns_from_origin() — | |
743 | Returns whether or not a message iterator can currently seek a | |
118ae153 | 744 | message occurring at or after a given time from its clock class |
43c59509 PP |
745 | origin. |
746 | */ | |
9a2c8b8e PP |
747 | extern bt_message_iterator_seek_ns_from_origin_status |
748 | bt_message_iterator_seek_ns_from_origin( | |
43c59509 | 749 | bt_message_iterator *message_iterator, |
4c81a2b7 | 750 | int64_t ns_from_origin) __BT_NOEXCEPT; |
9a2c8b8e | 751 | |
43c59509 PP |
752 | /*! @} */ |
753 | ||
754 | /*! | |
755 | @name Configuration | |
756 | @{ | |
757 | */ | |
758 | ||
759 | /*! | |
760 | @brief | |
761 | Returns whether or not the message iterator \bt_p{message_iterator} | |
762 | can seek forward. | |
763 | ||
764 | A message iterator can seek forward if all the \bt_p_msg of its | |
765 | message sequence have some \bt_cs. | |
766 | ||
767 | @param[in] message_iterator | |
768 | Message iterator of which to get whether or not it can seek forward. | |
9a2c8b8e | 769 | |
43c59509 PP |
770 | @returns |
771 | #BT_TRUE if \bt_p{message_iterator} can seek forward. | |
772 | ||
773 | @sa bt_self_message_iterator_configuration_set_can_seek_forward() — | |
774 | Sets whether or not a message iterator can seek forward. | |
775 | */ | |
9a2c8b8e PP |
776 | extern bt_bool |
777 | bt_message_iterator_can_seek_forward( | |
4c81a2b7 | 778 | bt_message_iterator *message_iterator) __BT_NOEXCEPT; |
43c59509 PP |
779 | |
780 | /*! @} */ | |
781 | ||
782 | /*! | |
783 | @name Reference count | |
784 | @{ | |
785 | */ | |
786 | ||
787 | /*! | |
788 | @brief | |
789 | Increments the \ref api-fund-shared-object "reference count" of | |
790 | the message iterator \bt_p{message_iterator}. | |
9a2c8b8e | 791 | |
43c59509 PP |
792 | @param[in] message_iterator |
793 | @parblock | |
794 | Message iterator of which to increment the reference count. | |
795 | ||
796 | Can be \c NULL. | |
797 | @endparblock | |
798 | ||
799 | @sa bt_message_iterator_put_ref() — | |
800 | Decrements the reference count of a message iterator. | |
801 | */ | |
9a2c8b8e | 802 | extern void bt_message_iterator_get_ref( |
4c81a2b7 | 803 | const bt_message_iterator *message_iterator) __BT_NOEXCEPT; |
9a2c8b8e | 804 | |
43c59509 PP |
805 | /*! |
806 | @brief | |
807 | Decrements the \ref api-fund-shared-object "reference count" of | |
808 | the message iterator \bt_p{message_iterator}. | |
809 | ||
810 | @param[in] message_iterator | |
811 | @parblock | |
812 | Message iterator of which to decrement the reference count. | |
813 | ||
814 | Can be \c NULL. | |
815 | @endparblock | |
816 | ||
817 | @sa bt_message_iterator_get_ref() — | |
818 | Increments the reference count of a message iterator. | |
819 | */ | |
9a2c8b8e | 820 | extern void bt_message_iterator_put_ref( |
4c81a2b7 | 821 | const bt_message_iterator *message_iterator) __BT_NOEXCEPT; |
9a2c8b8e | 822 | |
43c59509 PP |
823 | /*! |
824 | @brief | |
825 | Decrements the reference count of the message iterator | |
826 | \bt_p{_message_iterator}, and then sets \bt_p{_message_iterator} | |
827 | to \c NULL. | |
828 | ||
829 | @param _message_iterator | |
830 | @parblock | |
831 | Message iterator of which to decrement the reference count. | |
832 | ||
833 | Can contain \c NULL. | |
834 | @endparblock | |
835 | ||
836 | @bt_pre_assign_expr{_message_iterator} | |
837 | */ | |
838 | #define BT_MESSAGE_ITERATOR_PUT_REF_AND_RESET(_message_iterator) \ | |
9a2c8b8e | 839 | do { \ |
43c59509 PP |
840 | bt_message_iterator_put_ref(_message_iterator); \ |
841 | (_message_iterator) = NULL; \ | |
9a2c8b8e PP |
842 | } while (0) |
843 | ||
43c59509 PP |
844 | /*! |
845 | @brief | |
846 | Decrements the reference count of the message iterator \bt_p{_dst}, | |
847 | sets \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to | |
848 | \c NULL. | |
849 | ||
850 | This macro effectively moves a message iterator reference from the | |
851 | expression \bt_p{_src} to the expression \bt_p{_dst}, putting the | |
852 | existing \bt_p{_dst} reference. | |
853 | ||
854 | @param _dst | |
855 | @parblock | |
856 | Destination expression. | |
857 | ||
858 | Can contain \c NULL. | |
859 | @endparblock | |
860 | @param _src | |
861 | @parblock | |
862 | Source expression. | |
863 | ||
864 | Can contain \c NULL. | |
865 | @endparblock | |
866 | ||
867 | @bt_pre_assign_expr{_dst} | |
868 | @bt_pre_assign_expr{_src} | |
869 | */ | |
870 | #define BT_MESSAGE_ITERATOR_MOVE_REF(_dst, _src) \ | |
871 | do { \ | |
872 | bt_message_iterator_put_ref(_dst); \ | |
873 | (_dst) = (_src); \ | |
874 | (_src) = NULL; \ | |
9a2c8b8e PP |
875 | } while (0) |
876 | ||
43c59509 PP |
877 | /*! @} */ |
878 | ||
879 | /*! @} */ | |
880 | ||
d24d5663 PP |
881 | #ifdef __cplusplus |
882 | } | |
883 | #endif | |
884 | ||
924dc299 | 885 | #endif /* BABELTRACE2_GRAPH_MESSAGE_ITERATOR_H */ |