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, | |
267 | bt_message_iterator **message_iterator); | |
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, | |
331 | bt_message_iterator **message_iterator); | |
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( | |
356 | bt_message_iterator *message_iterator); | |
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, | |
457 | bt_message_array_const *messages, uint64_t *count); | |
458 | ||
459 | /*! @} */ | |
460 | ||
461 | /*! | |
462 | @name Seeking | |
463 | @{ | |
464 | */ | |
465 | ||
466 | /*! | |
467 | @brief | |
468 | Status code for bt_message_iterator_can_seek_beginning(). | |
469 | */ | |
f2fb1b32 | 470 | typedef enum bt_message_iterator_can_seek_beginning_status { |
43c59509 PP |
471 | /*! |
472 | @brief | |
473 | Success. | |
474 | */ | |
f2fb1b32 | 475 | BT_MESSAGE_ITERATOR_CAN_SEEK_BEGINNING_STATUS_OK = __BT_FUNC_STATUS_OK, |
43c59509 PP |
476 | |
477 | /*! | |
478 | @brief | |
479 | Try again. | |
480 | */ | |
f2fb1b32 | 481 | BT_MESSAGE_ITERATOR_CAN_SEEK_BEGINNING_STATUS_AGAIN = __BT_FUNC_STATUS_AGAIN, |
43c59509 PP |
482 | |
483 | /*! | |
484 | @brief | |
485 | Out of memory. | |
486 | */ | |
f2fb1b32 | 487 | BT_MESSAGE_ITERATOR_CAN_SEEK_BEGINNING_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR, |
43c59509 PP |
488 | |
489 | /*! | |
490 | @brief | |
491 | Other error. | |
492 | */ | |
493 | BT_MESSAGE_ITERATOR_CAN_SEEK_BEGINNING_STATUS_ERROR = __BT_FUNC_STATUS_ERROR, | |
f2fb1b32 SM |
494 | } bt_message_iterator_can_seek_beginning_status; |
495 | ||
43c59509 PP |
496 | /*! |
497 | @brief | |
498 | Returns whether or not the message iterator \bt_p{message_iterator} | |
499 | can currently seek its beginning (first \bt_msg). | |
500 | ||
501 | See the \link api-msg-iter-op-seek-beg "seek beginning" | |
502 | operation\endlink. | |
503 | ||
504 | Make sure to call this function, without performing any other | |
505 | \ref api-msg-iter-ops "operation" on \bt_p{message_iterator}, before you | |
506 | call bt_message_iterator_seek_beginning(). | |
507 | ||
508 | @param[in] message_iterator | |
509 | Message iterator from which to to get whether or not it can seek | |
510 | its beginning. | |
511 | @param[out] can_seek_beginning | |
512 | <strong>On success</strong>, \bt_p{*can_seek_beginning} is #BT_TRUE | |
513 | if \bt_p{message_iterator} can seek its beginning. | |
514 | ||
515 | @retval #BT_MESSAGE_ITERATOR_CAN_SEEK_BEGINNING_STATUS_OK | |
516 | Success. | |
517 | @retval #BT_MESSAGE_ITERATOR_CAN_SEEK_BEGINNING_STATUS_AGAIN | |
518 | Try again. | |
519 | @retval #BT_MESSAGE_ITERATOR_CAN_SEEK_BEGINNING_STATUS_MEMORY_ERROR | |
520 | Out of memory. | |
521 | @retval #BT_MESSAGE_ITERATOR_CAN_SEEK_BEGINNING_STATUS_ERROR | |
522 | Other error. | |
523 | ||
524 | @bt_pre_not_null{message_iterator} | |
525 | @bt_pre_not_null{can_seek_beginning} | |
526 | ||
527 | @sa bt_message_iterator_seek_beginning() — | |
528 | Makes a message iterator seek its beginning. | |
529 | */ | |
530 | extern bt_message_iterator_can_seek_beginning_status | |
531 | bt_message_iterator_can_seek_beginning( | |
532 | bt_message_iterator *message_iterator, | |
533 | bt_bool *can_seek_beginning); | |
534 | ||
535 | /*! | |
536 | @brief | |
537 | Status code for bt_message_iterator_seek_beginning(). | |
538 | */ | |
539 | typedef enum bt_message_iterator_seek_beginning_status { | |
540 | /*! | |
541 | @brief | |
542 | Success. | |
543 | */ | |
544 | BT_MESSAGE_ITERATOR_SEEK_BEGINNING_STATUS_OK = __BT_FUNC_STATUS_OK, | |
545 | ||
546 | /*! | |
547 | @brief | |
548 | Try again. | |
549 | */ | |
550 | BT_MESSAGE_ITERATOR_SEEK_BEGINNING_STATUS_AGAIN = __BT_FUNC_STATUS_AGAIN, | |
551 | ||
552 | /*! | |
553 | @brief | |
554 | Out of memory. | |
555 | */ | |
556 | BT_MESSAGE_ITERATOR_SEEK_BEGINNING_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR, | |
557 | ||
558 | /*! | |
559 | @brief | |
560 | Other error. | |
561 | */ | |
562 | BT_MESSAGE_ITERATOR_SEEK_BEGINNING_STATUS_ERROR = __BT_FUNC_STATUS_ERROR, | |
563 | } bt_message_iterator_seek_beginning_status; | |
564 | ||
565 | /*! | |
566 | @brief | |
567 | Makes the message iterator \bt_p{message_iterator} seek its | |
568 | beginning (first \bt_msg). | |
569 | ||
570 | See \ref api-msg-iter-op-seek-beg "this operation's documentation". | |
571 | ||
572 | Make sure to call bt_message_iterator_can_seek_beginning(), | |
573 | without performing any other \ref api-msg-iter-ops "operation" on | |
574 | \bt_p{message_iterator}, before you call this function. | |
575 | ||
576 | @param[in] message_iterator | |
577 | Message iterator to seek to its beginning. | |
578 | ||
579 | @retval #BT_MESSAGE_ITERATOR_SEEK_BEGINNING_STATUS_OK | |
580 | Success. | |
581 | @retval #BT_MESSAGE_ITERATOR_SEEK_BEGINNING_STATUS_AGAIN | |
582 | Try again. | |
583 | @retval #BT_MESSAGE_ITERATOR_SEEK_BEGINNING_STATUS_MEMORY_ERROR | |
584 | Out of memory. | |
585 | @retval #BT_MESSAGE_ITERATOR_SEEK_BEGINNING_STATUS_ERROR | |
586 | Other error. | |
587 | ||
588 | @bt_pre_not_null{message_iterator} | |
589 | @pre | |
590 | <code>bt_message_iterator_can_seek_beginning(message_iterator)</code> | |
591 | returns #BT_TRUE. | |
592 | ||
593 | @sa bt_message_iterator_can_seek_beginning() — | |
594 | Returns whether or not a message iterator can currently seek its | |
595 | beginning. | |
596 | */ | |
597 | extern bt_message_iterator_seek_beginning_status | |
598 | bt_message_iterator_seek_beginning( | |
599 | bt_message_iterator *message_iterator); | |
600 | ||
601 | /*! | |
602 | @brief | |
603 | Status code for bt_message_iterator_can_seek_ns_from_origin(). | |
604 | */ | |
f2fb1b32 | 605 | typedef enum bt_message_iterator_can_seek_ns_from_origin_status { |
43c59509 PP |
606 | /*! |
607 | @brief | |
608 | Success. | |
609 | */ | |
f2fb1b32 | 610 | BT_MESSAGE_ITERATOR_CAN_SEEK_NS_FROM_ORIGIN_STATUS_OK = __BT_FUNC_STATUS_OK, |
43c59509 PP |
611 | |
612 | /*! | |
613 | @brief | |
614 | Try again. | |
615 | */ | |
f2fb1b32 | 616 | BT_MESSAGE_ITERATOR_CAN_SEEK_NS_FROM_ORIGIN_STATUS_AGAIN = __BT_FUNC_STATUS_AGAIN, |
43c59509 PP |
617 | |
618 | /*! | |
619 | @brief | |
620 | Out of memory. | |
621 | */ | |
f2fb1b32 | 622 | BT_MESSAGE_ITERATOR_CAN_SEEK_NS_FROM_ORIGIN_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR, |
43c59509 PP |
623 | |
624 | /*! | |
625 | @brief | |
626 | Other error. | |
627 | */ | |
628 | BT_MESSAGE_ITERATOR_CAN_SEEK_NS_FROM_ORIGIN_STATUS_ERROR = __BT_FUNC_STATUS_ERROR, | |
f2fb1b32 SM |
629 | } bt_message_iterator_can_seek_ns_from_origin_status; |
630 | ||
43c59509 PP |
631 | /*! |
632 | @brief | |
633 | Returns whether or not the message iterator \bt_p{message_iterator} | |
118ae153 | 634 | can currently seek a \bt_msg occurring at or after |
43c59509 PP |
635 | \bt_p{ns_from_origin} nanoseconds from its |
636 | \ref api-tir-clock-cls-origin "clock class origin". | |
9a2c8b8e | 637 | |
43c59509 PP |
638 | See the \link api-msg-iter-op-seek-ns "seek ns from origin" |
639 | operation\endlink. | |
9a2c8b8e | 640 | |
43c59509 PP |
641 | Make sure to call this function, without performing any other |
642 | \ref api-msg-iter-ops "operation" on \bt_p{message_iterator}, before you | |
643 | call bt_message_iterator_seek_ns_from_origin(). | |
9a2c8b8e | 644 | |
43c59509 PP |
645 | @param[in] message_iterator |
646 | Message iterator from which to to get whether or not it can seek | |
647 | its beginning. | |
648 | @param[in] ns_from_origin | |
649 | Requested time point to seek. | |
650 | @param[out] can_seek_ns_from_origin | |
651 | <strong>On success</strong>, \bt_p{*can_seek_ns_from_origin} is | |
118ae153 | 652 | #BT_TRUE if \bt_p{message_iterator} can seek a message occurring at |
43c59509 PP |
653 | or after \bt_p{ns_from_origin} nanoseconds from its clock class |
654 | origin. | |
9a2c8b8e | 655 | |
43c59509 PP |
656 | @retval #BT_MESSAGE_ITERATOR_CAN_SEEK_NS_FROM_ORIGIN_STATUS_OK |
657 | Success. | |
658 | @retval #BT_MESSAGE_ITERATOR_CAN_SEEK_NS_FROM_ORIGIN_STATUS_AGAIN | |
659 | Try again. | |
660 | @retval #BT_MESSAGE_ITERATOR_CAN_SEEK_NS_FROM_ORIGIN_STATUS_MEMORY_ERROR | |
661 | Out of memory. | |
662 | @retval #BT_MESSAGE_ITERATOR_CAN_SEEK_NS_FROM_ORIGIN_STATUS_ERROR | |
663 | Other error. | |
9a2c8b8e | 664 | |
43c59509 PP |
665 | @bt_pre_not_null{message_iterator} |
666 | @bt_pre_not_null{can_seek_ns_from_origin} | |
9a2c8b8e | 667 | |
43c59509 | 668 | @sa bt_message_iterator_seek_ns_from_origin() — |
118ae153 | 669 | Makes a message iterator seek a message occurring at or after |
43c59509 PP |
670 | a given time from its clock class origin. |
671 | */ | |
9a2c8b8e PP |
672 | |
673 | extern bt_message_iterator_can_seek_ns_from_origin_status | |
674 | bt_message_iterator_can_seek_ns_from_origin( | |
43c59509 PP |
675 | bt_message_iterator *message_iterator, |
676 | int64_t ns_from_origin, bt_bool *can_seek_ns_from_origin); | |
9a2c8b8e | 677 | |
43c59509 PP |
678 | /*! |
679 | @brief | |
680 | Status code for bt_message_iterator_seek_ns_from_origin(). | |
681 | */ | |
682 | typedef enum bt_message_iterator_seek_ns_from_origin_status { | |
683 | /*! | |
684 | @brief | |
685 | Success. | |
686 | */ | |
687 | BT_MESSAGE_ITERATOR_SEEK_NS_FROM_ORIGIN_STATUS_OK = __BT_FUNC_STATUS_OK, | |
688 | ||
689 | /*! | |
690 | @brief | |
691 | Try again. | |
692 | */ | |
693 | BT_MESSAGE_ITERATOR_SEEK_NS_FROM_ORIGIN_STATUS_AGAIN = __BT_FUNC_STATUS_AGAIN, | |
694 | ||
695 | /*! | |
696 | @brief | |
697 | Out of memory. | |
698 | */ | |
699 | BT_MESSAGE_ITERATOR_SEEK_NS_FROM_ORIGIN_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR, | |
700 | ||
701 | /*! | |
702 | @brief | |
703 | Other error. | |
704 | */ | |
705 | BT_MESSAGE_ITERATOR_SEEK_NS_FROM_ORIGIN_STATUS_ERROR = __BT_FUNC_STATUS_ERROR, | |
706 | } bt_message_iterator_seek_ns_from_origin_status; | |
707 | ||
708 | /*! | |
709 | @brief | |
710 | Makes the message iterator \bt_p{message_iterator} seek a \bt_msg | |
118ae153 | 711 | occurring at or after \bt_p{ns_from_origin} nanoseconds from its |
43c59509 PP |
712 | \ref api-tir-clock-cls-origin "clock class origin". |
713 | ||
714 | See \ref api-msg-iter-op-seek-ns "this operation's documentation". | |
715 | ||
716 | Make sure to call bt_message_iterator_can_seek_ns_from_origin(), | |
717 | without performing any other \ref api-msg-iter-ops "operation" on | |
718 | \bt_p{message_iterator}, before you call this function. | |
719 | ||
720 | @param[in] message_iterator | |
118ae153 | 721 | Message iterator to seek to a message occurring at or after |
43c59509 PP |
722 | \bt_p{ns_from_origin} nanoseconds from its clock class origin. |
723 | @param[in] ns_from_origin | |
724 | Time point to seek. | |
725 | ||
726 | @retval #BT_MESSAGE_ITERATOR_SEEK_NS_FROM_ORIGIN_STATUS_OK | |
727 | Success. | |
728 | @retval #BT_MESSAGE_ITERATOR_SEEK_NS_FROM_ORIGIN_STATUS_AGAIN | |
729 | Try again. | |
730 | @retval #BT_MESSAGE_ITERATOR_SEEK_NS_FROM_ORIGIN_STATUS_MEMORY_ERROR | |
731 | Out of memory. | |
732 | @retval #BT_MESSAGE_ITERATOR_SEEK_NS_FROM_ORIGIN_STATUS_ERROR | |
733 | Other error. | |
9a2c8b8e | 734 | |
43c59509 PP |
735 | @bt_pre_not_null{message_iterator} |
736 | @pre | |
737 | <code>bt_message_iterator_can_seek_ns_from_origin(message_iterator, ns_from_origin)</code> | |
738 | returns #BT_TRUE. | |
739 | ||
740 | @sa bt_message_iterator_can_seek_ns_from_origin() — | |
741 | Returns whether or not a message iterator can currently seek a | |
118ae153 | 742 | message occurring at or after a given time from its clock class |
43c59509 PP |
743 | origin. |
744 | */ | |
9a2c8b8e PP |
745 | extern bt_message_iterator_seek_ns_from_origin_status |
746 | bt_message_iterator_seek_ns_from_origin( | |
43c59509 | 747 | bt_message_iterator *message_iterator, |
9a2c8b8e PP |
748 | int64_t ns_from_origin); |
749 | ||
43c59509 PP |
750 | /*! @} */ |
751 | ||
752 | /*! | |
753 | @name Configuration | |
754 | @{ | |
755 | */ | |
756 | ||
757 | /*! | |
758 | @brief | |
759 | Returns whether or not the message iterator \bt_p{message_iterator} | |
760 | can seek forward. | |
761 | ||
762 | A message iterator can seek forward if all the \bt_p_msg of its | |
763 | message sequence have some \bt_cs. | |
764 | ||
765 | @param[in] message_iterator | |
766 | Message iterator of which to get whether or not it can seek forward. | |
9a2c8b8e | 767 | |
43c59509 PP |
768 | @returns |
769 | #BT_TRUE if \bt_p{message_iterator} can seek forward. | |
770 | ||
771 | @sa bt_self_message_iterator_configuration_set_can_seek_forward() — | |
772 | Sets whether or not a message iterator can seek forward. | |
773 | */ | |
9a2c8b8e PP |
774 | extern bt_bool |
775 | bt_message_iterator_can_seek_forward( | |
43c59509 PP |
776 | bt_message_iterator *message_iterator); |
777 | ||
778 | /*! @} */ | |
779 | ||
780 | /*! | |
781 | @name Reference count | |
782 | @{ | |
783 | */ | |
784 | ||
785 | /*! | |
786 | @brief | |
787 | Increments the \ref api-fund-shared-object "reference count" of | |
788 | the message iterator \bt_p{message_iterator}. | |
9a2c8b8e | 789 | |
43c59509 PP |
790 | @param[in] message_iterator |
791 | @parblock | |
792 | Message iterator of which to increment the reference count. | |
793 | ||
794 | Can be \c NULL. | |
795 | @endparblock | |
796 | ||
797 | @sa bt_message_iterator_put_ref() — | |
798 | Decrements the reference count of a message iterator. | |
799 | */ | |
9a2c8b8e PP |
800 | extern void bt_message_iterator_get_ref( |
801 | const bt_message_iterator *message_iterator); | |
802 | ||
43c59509 PP |
803 | /*! |
804 | @brief | |
805 | Decrements the \ref api-fund-shared-object "reference count" of | |
806 | the message iterator \bt_p{message_iterator}. | |
807 | ||
808 | @param[in] message_iterator | |
809 | @parblock | |
810 | Message iterator of which to decrement the reference count. | |
811 | ||
812 | Can be \c NULL. | |
813 | @endparblock | |
814 | ||
815 | @sa bt_message_iterator_get_ref() — | |
816 | Increments the reference count of a message iterator. | |
817 | */ | |
9a2c8b8e PP |
818 | extern void bt_message_iterator_put_ref( |
819 | const bt_message_iterator *message_iterator); | |
820 | ||
43c59509 PP |
821 | /*! |
822 | @brief | |
823 | Decrements the reference count of the message iterator | |
824 | \bt_p{_message_iterator}, and then sets \bt_p{_message_iterator} | |
825 | to \c NULL. | |
826 | ||
827 | @param _message_iterator | |
828 | @parblock | |
829 | Message iterator of which to decrement the reference count. | |
830 | ||
831 | Can contain \c NULL. | |
832 | @endparblock | |
833 | ||
834 | @bt_pre_assign_expr{_message_iterator} | |
835 | */ | |
836 | #define BT_MESSAGE_ITERATOR_PUT_REF_AND_RESET(_message_iterator) \ | |
9a2c8b8e | 837 | do { \ |
43c59509 PP |
838 | bt_message_iterator_put_ref(_message_iterator); \ |
839 | (_message_iterator) = NULL; \ | |
9a2c8b8e PP |
840 | } while (0) |
841 | ||
43c59509 PP |
842 | /*! |
843 | @brief | |
844 | Decrements the reference count of the message iterator \bt_p{_dst}, | |
845 | sets \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to | |
846 | \c NULL. | |
847 | ||
848 | This macro effectively moves a message iterator reference from the | |
849 | expression \bt_p{_src} to the expression \bt_p{_dst}, putting the | |
850 | existing \bt_p{_dst} reference. | |
851 | ||
852 | @param _dst | |
853 | @parblock | |
854 | Destination expression. | |
855 | ||
856 | Can contain \c NULL. | |
857 | @endparblock | |
858 | @param _src | |
859 | @parblock | |
860 | Source expression. | |
861 | ||
862 | Can contain \c NULL. | |
863 | @endparblock | |
864 | ||
865 | @bt_pre_assign_expr{_dst} | |
866 | @bt_pre_assign_expr{_src} | |
867 | */ | |
868 | #define BT_MESSAGE_ITERATOR_MOVE_REF(_dst, _src) \ | |
869 | do { \ | |
870 | bt_message_iterator_put_ref(_dst); \ | |
871 | (_dst) = (_src); \ | |
872 | (_src) = NULL; \ | |
9a2c8b8e PP |
873 | } while (0) |
874 | ||
43c59509 PP |
875 | /*! @} */ |
876 | ||
877 | /*! @} */ | |
878 | ||
d24d5663 PP |
879 | #ifdef __cplusplus |
880 | } | |
881 | #endif | |
882 | ||
924dc299 | 883 | #endif /* BABELTRACE2_GRAPH_MESSAGE_ITERATOR_H */ |