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