2 * SPDX-License-Identifier: MIT
4 * Copyright (C) 2010-2019 EfficiOS Inc. and Linux Foundation
7 #ifndef BABELTRACE2_GRAPH_MESSAGE_ITERATOR_H
8 #define BABELTRACE2_GRAPH_MESSAGE_ITERATOR_H
10 /* IWYU pragma: private, include <babeltrace2/babeltrace.h> */
12 #ifndef __BT_IN_BABELTRACE_H
13 # error "Please include <babeltrace2/babeltrace.h> instead."
21 @defgroup api-msg-iter Message iterator
22 @ingroup api-comp-cls-dev
25 Iterator of a \bt_msg sequence.
27 A <strong><em>message iterator</em></strong> iterates a sequence of
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).
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().
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().
45 The type of a message iterator is #bt_message_iterator.
47 There are two contexts from which you can create a message iterator:
50 <dt>From another message iterator</dt>
52 This is the case for a \bt_flt_comp's message iterator.
54 Use bt_message_iterator_create_from_message_iterator().
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".
61 <dt>From a \bt_sink_comp</dt>
63 Use bt_message_iterator_create_from_sink_component().
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:
70 - \ref api-comp-cls-dev-meth-graph-configured "Graph is configured"
73 - \ref api-comp-cls-dev-meth-consume "Consume" method.
77 When you call one of the creation functions above, you pass an \bt_iport
78 on which to create the message iterator.
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:
86 - Any \bt_sink_comp is free to create one or more message iterators
87 on any of its connected input ports.
89 - Any message iterator is free to create one or more message iterators
90 on any of its component's connected input ports.
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:
97 @image html msg-iter.png
99 Many message iterator relations are possible, for example:
101 @image html msg-iter-complex.png
103 <h1>\anchor api-msg-iter-ops Operations</h1>
105 Once you have created a message iterator, there are three possible
110 \anchor api-msg-iter-op-next
111 Get the message iterator's next messages
114 This operation returns a batch of the message iterator's next
115 \bt_p_msg considering its current state.
117 This operation returns a batch of messages instead of a single
118 message for performance reasons.
120 This operation is said to \em advance the message iterator.
122 Get the next messages of a message iterator with
123 bt_message_iterator_next().
127 \anchor api-msg-iter-op-seek-beg
128 Make the message iterator seek its beginning
131 This operation resets the message iterator's position to the
132 beginning of its \ref api-msg-seq "message sequence".
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.
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().
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().
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
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".
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.
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.
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().
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().
192 @typedef struct bt_message_iterator bt_message_iterator;
207 Status code for bt_message_iterator_create_from_message_iterator().
209 typedef enum bt_message_iterator_create_from_message_iterator_status
{
214 BT_MESSAGE_ITERATOR_CREATE_FROM_MESSAGE_ITERATOR_STATUS_OK
= __BT_FUNC_STATUS_OK
,
220 BT_MESSAGE_ITERATOR_CREATE_FROM_MESSAGE_ITERATOR_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
226 BT_MESSAGE_ITERATOR_CREATE_FROM_MESSAGE_ITERATOR_STATUS_ERROR
= __BT_FUNC_STATUS_ERROR
,
227 } bt_message_iterator_create_from_message_iterator_status
;
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.
235 On success, the message iterator's position is at the beginning
236 of its \ref api-msg-seq "message sequence".
238 @param[in] self_message_iterator
239 Other message iterator from which to create the message iterator.
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.
246 @retval #BT_MESSAGE_ITERATOR_CREATE_FROM_MESSAGE_ITERATOR_STATUS_OK
248 @retval #BT_MESSAGE_ITERATOR_CREATE_FROM_MESSAGE_ITERATOR_STATUS_MEMORY_ERROR
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.
254 @bt_pre_not_null{self_message_iterator}
255 @bt_pre_not_null{port}
257 <code>bt_port_is_connected(port)</code> returns #BT_TRUE.
258 @bt_pre_not_null{message_iterator}
260 @sa bt_message_iterator_create_from_sink_component() —
261 Creates a message iterator from a \bt_sink_comp.
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
);
271 Status code for bt_message_iterator_create_from_sink_component().
273 typedef enum bt_message_iterator_create_from_sink_component_status
{
278 BT_MESSAGE_ITERATOR_CREATE_FROM_SINK_COMPONENT_STATUS_OK
= __BT_FUNC_STATUS_OK
,
284 BT_MESSAGE_ITERATOR_CREATE_FROM_SINK_COMPONENT_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
290 BT_MESSAGE_ITERATOR_CREATE_FROM_SINK_COMPONENT_STATUS_ERROR
= __BT_FUNC_STATUS_ERROR
,
291 } bt_message_iterator_create_from_sink_component_status
;
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.
299 On success, the message iterator's position is at the beginning
300 of its \ref api-msg-seq "message sequence".
302 @param[in] self_component_sink
303 Sink component from which to create the message iterator.
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.
310 @retval #BT_MESSAGE_ITERATOR_CREATE_FROM_MESSAGE_ITERATOR_STATUS_OK
312 @retval #BT_MESSAGE_ITERATOR_CREATE_FROM_MESSAGE_ITERATOR_STATUS_MEMORY_ERROR
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.
318 @bt_pre_not_null{self_component_sink}
319 @bt_pre_not_null{port}
321 <code>bt_port_is_connected(port)</code> returns #BT_TRUE.
322 @bt_pre_not_null{message_iterator}
324 @sa bt_message_iterator_create_from_message_iterator() —
325 Creates a message iterator from another message iterator.
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
);
336 @name Component access
342 Borrows the \bt_comp which provides the \bt_msg_iter
343 \bt_p{message_iterator}.
345 @param[in] message_iterator
346 Message iterator from which to borrow the component which provides
350 Component which provides \bt_p{message_iterator}.
352 @bt_pre_not_null{message_iterator}
354 extern bt_component
*
355 bt_message_iterator_borrow_component(
356 bt_message_iterator
*message_iterator
);
361 @name "Next" operation (get next messages)
367 Status code for bt_message_iterator_next().
369 typedef enum bt_message_iterator_next_status
{
374 BT_MESSAGE_ITERATOR_NEXT_STATUS_OK
= __BT_FUNC_STATUS_OK
,
380 BT_MESSAGE_ITERATOR_NEXT_STATUS_END
= __BT_FUNC_STATUS_END
,
386 BT_MESSAGE_ITERATOR_NEXT_STATUS_AGAIN
= __BT_FUNC_STATUS_AGAIN
,
392 BT_MESSAGE_ITERATOR_NEXT_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
398 BT_MESSAGE_ITERATOR_NEXT_STATUS_ERROR
= __BT_FUNC_STATUS_ERROR
,
399 } bt_message_iterator_next_status
;
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}.
407 See \ref api-msg-iter-op-next "this operation's documentation".
409 On success, the message iterator's position is advanced by \bt_p{*count}
412 @param[in] message_iterator
413 Message iterator from which to get the next messages.
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.
419 \bt_p{*count} is the number of messages in \bt_p{*messages}.
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.
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.
434 <strong>On success</strong>, \bt_p{*count} is the number of messages
437 @retval #BT_MESSAGE_ITERATOR_NEXT_STATUS_OK
439 @retval #BT_MESSAGE_ITERATOR_NEXT_STATUS_END
441 @retval #BT_MESSAGE_ITERATOR_NEXT_STATUS_AGAIN
443 @retval #BT_MESSAGE_ITERATOR_NEXT_STATUS_MEMORY_ERROR
445 @retval #BT_MESSAGE_ITERATOR_NEXT_STATUS_ERROR
448 @bt_pre_not_null{message_iterator}
449 @bt_pre_not_null{messages}
450 @bt_pre_not_null{count}
453 <strong>On success</strong>, \bt_p{*count} ≥ 1.
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
);
468 Status code for bt_message_iterator_can_seek_beginning().
470 typedef enum bt_message_iterator_can_seek_beginning_status
{
475 BT_MESSAGE_ITERATOR_CAN_SEEK_BEGINNING_STATUS_OK
= __BT_FUNC_STATUS_OK
,
481 BT_MESSAGE_ITERATOR_CAN_SEEK_BEGINNING_STATUS_AGAIN
= __BT_FUNC_STATUS_AGAIN
,
487 BT_MESSAGE_ITERATOR_CAN_SEEK_BEGINNING_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
493 BT_MESSAGE_ITERATOR_CAN_SEEK_BEGINNING_STATUS_ERROR
= __BT_FUNC_STATUS_ERROR
,
494 } bt_message_iterator_can_seek_beginning_status
;
498 Returns whether or not the message iterator \bt_p{message_iterator}
499 can currently seek its beginning (first \bt_msg).
501 See the \link api-msg-iter-op-seek-beg "seek beginning"
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().
508 @param[in] message_iterator
509 Message iterator from which to to get whether or not it can seek
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.
515 @retval #BT_MESSAGE_ITERATOR_CAN_SEEK_BEGINNING_STATUS_OK
517 @retval #BT_MESSAGE_ITERATOR_CAN_SEEK_BEGINNING_STATUS_AGAIN
519 @retval #BT_MESSAGE_ITERATOR_CAN_SEEK_BEGINNING_STATUS_MEMORY_ERROR
521 @retval #BT_MESSAGE_ITERATOR_CAN_SEEK_BEGINNING_STATUS_ERROR
524 @bt_pre_not_null{message_iterator}
525 @bt_pre_not_null{can_seek_beginning}
527 @sa bt_message_iterator_seek_beginning() —
528 Makes a message iterator seek its beginning.
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
);
537 Status code for bt_message_iterator_seek_beginning().
539 typedef enum bt_message_iterator_seek_beginning_status
{
544 BT_MESSAGE_ITERATOR_SEEK_BEGINNING_STATUS_OK
= __BT_FUNC_STATUS_OK
,
550 BT_MESSAGE_ITERATOR_SEEK_BEGINNING_STATUS_AGAIN
= __BT_FUNC_STATUS_AGAIN
,
556 BT_MESSAGE_ITERATOR_SEEK_BEGINNING_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
562 BT_MESSAGE_ITERATOR_SEEK_BEGINNING_STATUS_ERROR
= __BT_FUNC_STATUS_ERROR
,
563 } bt_message_iterator_seek_beginning_status
;
567 Makes the message iterator \bt_p{message_iterator} seek its
568 beginning (first \bt_msg).
570 See \ref api-msg-iter-op-seek-beg "this operation's documentation".
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.
576 @param[in] message_iterator
577 Message iterator to seek to its beginning.
579 @retval #BT_MESSAGE_ITERATOR_SEEK_BEGINNING_STATUS_OK
581 @retval #BT_MESSAGE_ITERATOR_SEEK_BEGINNING_STATUS_AGAIN
583 @retval #BT_MESSAGE_ITERATOR_SEEK_BEGINNING_STATUS_MEMORY_ERROR
585 @retval #BT_MESSAGE_ITERATOR_SEEK_BEGINNING_STATUS_ERROR
588 @bt_pre_not_null{message_iterator}
590 <code>bt_message_iterator_can_seek_beginning(message_iterator)</code>
593 @sa bt_message_iterator_can_seek_beginning() —
594 Returns whether or not a message iterator can currently seek its
597 extern bt_message_iterator_seek_beginning_status
598 bt_message_iterator_seek_beginning(
599 bt_message_iterator
*message_iterator
);
603 Status code for bt_message_iterator_can_seek_ns_from_origin().
605 typedef enum bt_message_iterator_can_seek_ns_from_origin_status
{
610 BT_MESSAGE_ITERATOR_CAN_SEEK_NS_FROM_ORIGIN_STATUS_OK
= __BT_FUNC_STATUS_OK
,
616 BT_MESSAGE_ITERATOR_CAN_SEEK_NS_FROM_ORIGIN_STATUS_AGAIN
= __BT_FUNC_STATUS_AGAIN
,
622 BT_MESSAGE_ITERATOR_CAN_SEEK_NS_FROM_ORIGIN_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
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
;
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".
638 See the \link api-msg-iter-op-seek-ns "seek ns from origin"
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().
645 @param[in] message_iterator
646 Message iterator from which to to get whether or not it can seek
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
656 @retval #BT_MESSAGE_ITERATOR_CAN_SEEK_NS_FROM_ORIGIN_STATUS_OK
658 @retval #BT_MESSAGE_ITERATOR_CAN_SEEK_NS_FROM_ORIGIN_STATUS_AGAIN
660 @retval #BT_MESSAGE_ITERATOR_CAN_SEEK_NS_FROM_ORIGIN_STATUS_MEMORY_ERROR
662 @retval #BT_MESSAGE_ITERATOR_CAN_SEEK_NS_FROM_ORIGIN_STATUS_ERROR
665 @bt_pre_not_null{message_iterator}
666 @bt_pre_not_null{can_seek_ns_from_origin}
668 @sa bt_message_iterator_seek_ns_from_origin() —
669 Makes a message iterator seek a message occurring at or after
670 a given time from its clock class origin.
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
);
680 Status code for bt_message_iterator_seek_ns_from_origin().
682 typedef enum bt_message_iterator_seek_ns_from_origin_status
{
687 BT_MESSAGE_ITERATOR_SEEK_NS_FROM_ORIGIN_STATUS_OK
= __BT_FUNC_STATUS_OK
,
693 BT_MESSAGE_ITERATOR_SEEK_NS_FROM_ORIGIN_STATUS_AGAIN
= __BT_FUNC_STATUS_AGAIN
,
699 BT_MESSAGE_ITERATOR_SEEK_NS_FROM_ORIGIN_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
705 BT_MESSAGE_ITERATOR_SEEK_NS_FROM_ORIGIN_STATUS_ERROR
= __BT_FUNC_STATUS_ERROR
,
706 } bt_message_iterator_seek_ns_from_origin_status
;
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".
714 See \ref api-msg-iter-op-seek-ns "this operation's documentation".
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.
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
726 @retval #BT_MESSAGE_ITERATOR_SEEK_NS_FROM_ORIGIN_STATUS_OK
728 @retval #BT_MESSAGE_ITERATOR_SEEK_NS_FROM_ORIGIN_STATUS_AGAIN
730 @retval #BT_MESSAGE_ITERATOR_SEEK_NS_FROM_ORIGIN_STATUS_MEMORY_ERROR
732 @retval #BT_MESSAGE_ITERATOR_SEEK_NS_FROM_ORIGIN_STATUS_ERROR
735 @bt_pre_not_null{message_iterator}
737 <code>bt_message_iterator_can_seek_ns_from_origin(message_iterator, ns_from_origin)</code>
740 @sa bt_message_iterator_can_seek_ns_from_origin() —
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
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
);
759 Returns whether or not the message iterator \bt_p{message_iterator}
762 A message iterator can seek forward if all the \bt_p_msg of its
763 message sequence have some \bt_cs.
765 @param[in] message_iterator
766 Message iterator of which to get whether or not it can seek forward.
769 #BT_TRUE if \bt_p{message_iterator} can seek forward.
771 @sa bt_self_message_iterator_configuration_set_can_seek_forward() —
772 Sets whether or not a message iterator can seek forward.
775 bt_message_iterator_can_seek_forward(
776 bt_message_iterator
*message_iterator
);
781 @name Reference count
787 Increments the \ref api-fund-shared-object "reference count" of
788 the message iterator \bt_p{message_iterator}.
790 @param[in] message_iterator
792 Message iterator of which to increment the reference count.
797 @sa bt_message_iterator_put_ref() —
798 Decrements the reference count of a message iterator.
800 extern void bt_message_iterator_get_ref(
801 const bt_message_iterator
*message_iterator
);
805 Decrements the \ref api-fund-shared-object "reference count" of
806 the message iterator \bt_p{message_iterator}.
808 @param[in] message_iterator
810 Message iterator of which to decrement the reference count.
815 @sa bt_message_iterator_get_ref() —
816 Increments the reference count of a message iterator.
818 extern void bt_message_iterator_put_ref(
819 const bt_message_iterator
*message_iterator
);
823 Decrements the reference count of the message iterator
824 \bt_p{_message_iterator}, and then sets \bt_p{_message_iterator}
827 @param _message_iterator
829 Message iterator of which to decrement the reference count.
834 @bt_pre_assign_expr{_message_iterator}
836 #define BT_MESSAGE_ITERATOR_PUT_REF_AND_RESET(_message_iterator) \
838 bt_message_iterator_put_ref(_message_iterator); \
839 (_message_iterator) = NULL; \
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
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.
854 Destination expression.
865 @bt_pre_assign_expr{_dst}
866 @bt_pre_assign_expr{_src}
868 #define BT_MESSAGE_ITERATOR_MOVE_REF(_dst, _src) \
870 bt_message_iterator_put_ref(_dst); \
883 #endif /* BABELTRACE2_GRAPH_MESSAGE_ITERATOR_H */