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