0b6d102c39f36aa1459f4815e4d8c5e321534653
[babeltrace.git] / include / babeltrace2 / graph / message-iterator.h
1 /*
2 * SPDX-License-Identifier: MIT
3 *
4 * Copyright (C) 2010-2019 EfficiOS Inc. and Linux Foundation
5 */
6
7 #ifndef BABELTRACE2_GRAPH_MESSAGE_ITERATOR_H
8 #define BABELTRACE2_GRAPH_MESSAGE_ITERATOR_H
9
10 /* IWYU pragma: private, include <babeltrace2/babeltrace.h> */
11
12 #ifndef __BT_IN_BABELTRACE_H
13 # error "Please include <babeltrace2/babeltrace.h> instead."
14 #endif
15
16 #ifdef __cplusplus
17 extern "C" {
18 #endif
19
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
151 Make the message iterator seek a message occurring at or after a
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() &mdash;
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() &mdash;
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 */
369 typedef enum bt_message_iterator_next_status {
370 /*!
371 @brief
372 Success.
373 */
374 BT_MESSAGE_ITERATOR_NEXT_STATUS_OK = __BT_FUNC_STATUS_OK,
375
376 /*!
377 @brief
378 End of iteration.
379 */
380 BT_MESSAGE_ITERATOR_NEXT_STATUS_END = __BT_FUNC_STATUS_END,
381
382 /*!
383 @brief
384 Try again.
385 */
386 BT_MESSAGE_ITERATOR_NEXT_STATUS_AGAIN = __BT_FUNC_STATUS_AGAIN,
387
388 /*!
389 @brief
390 Out of memory.
391 */
392 BT_MESSAGE_ITERATOR_NEXT_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
393
394 /*!
395 @brief
396 Other error.
397 */
398 BT_MESSAGE_ITERATOR_NEXT_STATUS_ERROR = __BT_FUNC_STATUS_ERROR,
399 } bt_message_iterator_next_status;
400
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}.
406
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}.
420
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}&nbsp;≥&nbsp;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 */
470 typedef enum bt_message_iterator_can_seek_beginning_status {
471 /*!
472 @brief
473 Success.
474 */
475 BT_MESSAGE_ITERATOR_CAN_SEEK_BEGINNING_STATUS_OK = __BT_FUNC_STATUS_OK,
476
477 /*!
478 @brief
479 Try again.
480 */
481 BT_MESSAGE_ITERATOR_CAN_SEEK_BEGINNING_STATUS_AGAIN = __BT_FUNC_STATUS_AGAIN,
482
483 /*!
484 @brief
485 Out of memory.
486 */
487 BT_MESSAGE_ITERATOR_CAN_SEEK_BEGINNING_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
488
489 /*!
490 @brief
491 Other error.
492 */
493 BT_MESSAGE_ITERATOR_CAN_SEEK_BEGINNING_STATUS_ERROR = __BT_FUNC_STATUS_ERROR,
494 } bt_message_iterator_can_seek_beginning_status;
495
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() &mdash;
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() &mdash;
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 */
605 typedef enum bt_message_iterator_can_seek_ns_from_origin_status {
606 /*!
607 @brief
608 Success.
609 */
610 BT_MESSAGE_ITERATOR_CAN_SEEK_NS_FROM_ORIGIN_STATUS_OK = __BT_FUNC_STATUS_OK,
611
612 /*!
613 @brief
614 Try again.
615 */
616 BT_MESSAGE_ITERATOR_CAN_SEEK_NS_FROM_ORIGIN_STATUS_AGAIN = __BT_FUNC_STATUS_AGAIN,
617
618 /*!
619 @brief
620 Out of memory.
621 */
622 BT_MESSAGE_ITERATOR_CAN_SEEK_NS_FROM_ORIGIN_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
623
624 /*!
625 @brief
626 Other error.
627 */
628 BT_MESSAGE_ITERATOR_CAN_SEEK_NS_FROM_ORIGIN_STATUS_ERROR = __BT_FUNC_STATUS_ERROR,
629 } bt_message_iterator_can_seek_ns_from_origin_status;
630
631 /*!
632 @brief
633 Returns whether or not the message iterator \bt_p{message_iterator}
634 can currently seek a \bt_msg occurring at or after
635 \bt_p{ns_from_origin} nanoseconds from its
636 \ref api-tir-clock-cls-origin "clock class origin".
637
638 See the \link api-msg-iter-op-seek-ns "seek ns from origin"
639 operation\endlink.
640
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().
644
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
652 #BT_TRUE if \bt_p{message_iterator} can seek a message occurring at
653 or after \bt_p{ns_from_origin} nanoseconds from its clock class
654 origin.
655
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.
664
665 @bt_pre_not_null{message_iterator}
666 @bt_pre_not_null{can_seek_ns_from_origin}
667
668 @sa bt_message_iterator_seek_ns_from_origin() &mdash;
669 Makes a message iterator seek a message occurring at or after
670 a given time from its clock class origin.
671 */
672
673 extern bt_message_iterator_can_seek_ns_from_origin_status
674 bt_message_iterator_can_seek_ns_from_origin(
675 bt_message_iterator *message_iterator,
676 int64_t ns_from_origin, bt_bool *can_seek_ns_from_origin);
677
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
711 occurring at or after \bt_p{ns_from_origin} nanoseconds from its
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
721 Message iterator to seek to a message occurring at or after
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.
734
735 @bt_pre_not_null{message_iterator}
736 @pre
737 <code>bt_message_iterator_can_seek_ns_from_origin(message_iterator,&nbsp;ns_from_origin)</code>
738 returns #BT_TRUE.
739
740 @sa bt_message_iterator_can_seek_ns_from_origin() &mdash;
741 Returns whether or not a message iterator can currently seek a
742 message occurring at or after a given time from its clock class
743 origin.
744 */
745 extern bt_message_iterator_seek_ns_from_origin_status
746 bt_message_iterator_seek_ns_from_origin(
747 bt_message_iterator *message_iterator,
748 int64_t ns_from_origin);
749
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.
767
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() &mdash;
772 Sets whether or not a message iterator can seek forward.
773 */
774 extern bt_bool
775 bt_message_iterator_can_seek_forward(
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}.
789
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() &mdash;
798 Decrements the reference count of a message iterator.
799 */
800 extern void bt_message_iterator_get_ref(
801 const bt_message_iterator *message_iterator);
802
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() &mdash;
816 Increments the reference count of a message iterator.
817 */
818 extern void bt_message_iterator_put_ref(
819 const bt_message_iterator *message_iterator);
820
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) \
837 do { \
838 bt_message_iterator_put_ref(_message_iterator); \
839 (_message_iterator) = NULL; \
840 } while (0)
841
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; \
873 } while (0)
874
875 /*! @} */
876
877 /*! @} */
878
879 #ifdef __cplusplus
880 }
881 #endif
882
883 #endif /* BABELTRACE2_GRAPH_MESSAGE_ITERATOR_H */
This page took 0.049184 seconds and 3 git commands to generate.