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 #ifndef __BT_IN_BABELTRACE_H
11 # error "Please include <babeltrace2/babeltrace.h> instead."
19 @defgroup api-msg-iter Message iterator
20 @ingroup api-comp-cls-dev
23 Iterator of a \bt_msg sequence.
25 A <strong><em>message iterator</em></strong> iterates a sequence of
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).
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().
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().
43 The type of a message iterator is #bt_message_iterator.
45 There are two contexts from which you can create a message iterator:
48 <dt>From another message iterator</dt>
50 This is the case for a \bt_flt_comp's message iterator.
52 Use bt_message_iterator_create_from_message_iterator().
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".
59 <dt>From a \bt_sink_comp</dt>
61 Use bt_message_iterator_create_from_sink_component().
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:
68 - \ref api-comp-cls-dev-meth-graph-configured "Graph is configured"
71 - \ref api-comp-cls-dev-meth-consume "Consume" method.
75 When you call one of the creation functions above, you pass an \bt_iport
76 on which to create the message iterator.
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:
84 - Any \bt_sink_comp is free to create one or more message iterators
85 on any of its connected input ports.
87 - Any message iterator is free to create one or more message iterators
88 on any of its component's connected input ports.
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:
95 @image html msg-iter.png
97 Many message iterator relations are possible, for example:
99 @image html msg-iter-complex.png
101 <h1>\anchor api-msg-iter-ops Operations</h1>
103 Once you have created a message iterator, there are three possible
108 \anchor api-msg-iter-op-next
109 Get the message iterator's next messages
112 This operation returns a batch of the message iterator's next
113 \bt_p_msg considering its current state.
115 This operation returns a batch of messages instead of a single
116 message for performance reasons.
118 This operation is said to \em advance the message iterator.
120 Get the next messages of a message iterator with
121 bt_message_iterator_next().
125 \anchor api-msg-iter-op-seek-beg
126 Make the message iterator seek its beginning
129 This operation resets the message iterator's position to the
130 beginning of its \ref api-msg-seq "message sequence".
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.
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().
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().
148 \anchor api-msg-iter-op-seek-ns
149 Make the message iterator seek a message occurring at or after a
150 given time (in nanoseconds) from its clock class origin
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".
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.
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.
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().
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().
190 @typedef struct bt_message_iterator bt_message_iterator;
205 Status code for bt_message_iterator_create_from_message_iterator().
207 typedef enum bt_message_iterator_create_from_message_iterator_status
{
212 BT_MESSAGE_ITERATOR_CREATE_FROM_MESSAGE_ITERATOR_STATUS_OK
= __BT_FUNC_STATUS_OK
,
218 BT_MESSAGE_ITERATOR_CREATE_FROM_MESSAGE_ITERATOR_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
224 BT_MESSAGE_ITERATOR_CREATE_FROM_MESSAGE_ITERATOR_STATUS_ERROR
= __BT_FUNC_STATUS_ERROR
,
225 } bt_message_iterator_create_from_message_iterator_status
;
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.
233 On success, the message iterator's position is at the beginning
234 of its \ref api-msg-seq "message sequence".
236 @param[in] self_message_iterator
237 Other message iterator from which to create the message iterator.
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.
244 @retval #BT_MESSAGE_ITERATOR_CREATE_FROM_MESSAGE_ITERATOR_STATUS_OK
246 @retval #BT_MESSAGE_ITERATOR_CREATE_FROM_MESSAGE_ITERATOR_STATUS_MEMORY_ERROR
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.
252 @bt_pre_not_null{self_message_iterator}
253 @bt_pre_not_null{port}
255 <code>bt_port_is_connected(port)</code> returns #BT_TRUE.
256 @bt_pre_not_null{message_iterator}
258 @sa bt_message_iterator_create_from_sink_component() —
259 Creates a message iterator from a \bt_sink_comp.
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
);
269 Status code for bt_message_iterator_create_from_sink_component().
271 typedef enum bt_message_iterator_create_from_sink_component_status
{
276 BT_MESSAGE_ITERATOR_CREATE_FROM_SINK_COMPONENT_STATUS_OK
= __BT_FUNC_STATUS_OK
,
282 BT_MESSAGE_ITERATOR_CREATE_FROM_SINK_COMPONENT_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
288 BT_MESSAGE_ITERATOR_CREATE_FROM_SINK_COMPONENT_STATUS_ERROR
= __BT_FUNC_STATUS_ERROR
,
289 } bt_message_iterator_create_from_sink_component_status
;
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.
297 On success, the message iterator's position is at the beginning
298 of its \ref api-msg-seq "message sequence".
300 @param[in] self_component_sink
301 Sink component from which to create the message iterator.
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.
308 @retval #BT_MESSAGE_ITERATOR_CREATE_FROM_MESSAGE_ITERATOR_STATUS_OK
310 @retval #BT_MESSAGE_ITERATOR_CREATE_FROM_MESSAGE_ITERATOR_STATUS_MEMORY_ERROR
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.
316 @bt_pre_not_null{self_component_sink}
317 @bt_pre_not_null{port}
319 <code>bt_port_is_connected(port)</code> returns #BT_TRUE.
320 @bt_pre_not_null{message_iterator}
322 @sa bt_message_iterator_create_from_message_iterator() —
323 Creates a message iterator from another message iterator.
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
);
334 @name Component access
340 Borrows the \bt_comp which provides the \bt_msg_iter
341 \bt_p{message_iterator}.
343 @param[in] message_iterator
344 Message iterator from which to borrow the component which provides
348 Component which provides \bt_p{message_iterator}.
350 @bt_pre_not_null{message_iterator}
352 extern bt_component
*
353 bt_message_iterator_borrow_component(
354 bt_message_iterator
*message_iterator
);
359 @name "Next" operation (get next messages)
365 Status code for bt_message_iterator_next().
367 typedef enum bt_message_iterator_next_status
{
372 BT_MESSAGE_ITERATOR_NEXT_STATUS_OK
= __BT_FUNC_STATUS_OK
,
378 BT_MESSAGE_ITERATOR_NEXT_STATUS_END
= __BT_FUNC_STATUS_END
,
384 BT_MESSAGE_ITERATOR_NEXT_STATUS_AGAIN
= __BT_FUNC_STATUS_AGAIN
,
390 BT_MESSAGE_ITERATOR_NEXT_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
396 BT_MESSAGE_ITERATOR_NEXT_STATUS_ERROR
= __BT_FUNC_STATUS_ERROR
,
397 } bt_message_iterator_next_status
;
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}.
405 See \ref api-msg-iter-op-next "this operation's documentation".
407 On success, the message iterator's position is advanced by \bt_p{*count}
410 @param[in] message_iterator
411 Message iterator from which to get the next messages.
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.
417 \bt_p{*count} is the number of messages in \bt_p{*messages}.
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.
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.
432 <strong>On success</strong>, \bt_p{*count} is the number of messages
435 @retval #BT_MESSAGE_ITERATOR_NEXT_STATUS_OK
437 @retval #BT_MESSAGE_ITERATOR_NEXT_STATUS_END
439 @retval #BT_MESSAGE_ITERATOR_NEXT_STATUS_AGAIN
441 @retval #BT_MESSAGE_ITERATOR_NEXT_STATUS_MEMORY_ERROR
443 @retval #BT_MESSAGE_ITERATOR_NEXT_STATUS_ERROR
446 @bt_pre_not_null{message_iterator}
447 @bt_pre_not_null{messages}
448 @bt_pre_not_null{count}
451 <strong>On success</strong>, \bt_p{*count} ≥ 1.
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
);
466 Status code for bt_message_iterator_can_seek_beginning().
468 typedef enum bt_message_iterator_can_seek_beginning_status
{
473 BT_MESSAGE_ITERATOR_CAN_SEEK_BEGINNING_STATUS_OK
= __BT_FUNC_STATUS_OK
,
479 BT_MESSAGE_ITERATOR_CAN_SEEK_BEGINNING_STATUS_AGAIN
= __BT_FUNC_STATUS_AGAIN
,
485 BT_MESSAGE_ITERATOR_CAN_SEEK_BEGINNING_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
491 BT_MESSAGE_ITERATOR_CAN_SEEK_BEGINNING_STATUS_ERROR
= __BT_FUNC_STATUS_ERROR
,
492 } bt_message_iterator_can_seek_beginning_status
;
496 Returns whether or not the message iterator \bt_p{message_iterator}
497 can currently seek its beginning (first \bt_msg).
499 See the \link api-msg-iter-op-seek-beg "seek beginning"
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().
506 @param[in] message_iterator
507 Message iterator from which to to get whether or not it can seek
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.
513 @retval #BT_MESSAGE_ITERATOR_CAN_SEEK_BEGINNING_STATUS_OK
515 @retval #BT_MESSAGE_ITERATOR_CAN_SEEK_BEGINNING_STATUS_AGAIN
517 @retval #BT_MESSAGE_ITERATOR_CAN_SEEK_BEGINNING_STATUS_MEMORY_ERROR
519 @retval #BT_MESSAGE_ITERATOR_CAN_SEEK_BEGINNING_STATUS_ERROR
522 @bt_pre_not_null{message_iterator}
523 @bt_pre_not_null{can_seek_beginning}
525 @sa bt_message_iterator_seek_beginning() —
526 Makes a message iterator seek its beginning.
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
);
535 Status code for bt_message_iterator_seek_beginning().
537 typedef enum bt_message_iterator_seek_beginning_status
{
542 BT_MESSAGE_ITERATOR_SEEK_BEGINNING_STATUS_OK
= __BT_FUNC_STATUS_OK
,
548 BT_MESSAGE_ITERATOR_SEEK_BEGINNING_STATUS_AGAIN
= __BT_FUNC_STATUS_AGAIN
,
554 BT_MESSAGE_ITERATOR_SEEK_BEGINNING_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
560 BT_MESSAGE_ITERATOR_SEEK_BEGINNING_STATUS_ERROR
= __BT_FUNC_STATUS_ERROR
,
561 } bt_message_iterator_seek_beginning_status
;
565 Makes the message iterator \bt_p{message_iterator} seek its
566 beginning (first \bt_msg).
568 See \ref api-msg-iter-op-seek-beg "this operation's documentation".
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.
574 @param[in] message_iterator
575 Message iterator to seek to its beginning.
577 @retval #BT_MESSAGE_ITERATOR_SEEK_BEGINNING_STATUS_OK
579 @retval #BT_MESSAGE_ITERATOR_SEEK_BEGINNING_STATUS_AGAIN
581 @retval #BT_MESSAGE_ITERATOR_SEEK_BEGINNING_STATUS_MEMORY_ERROR
583 @retval #BT_MESSAGE_ITERATOR_SEEK_BEGINNING_STATUS_ERROR
586 @bt_pre_not_null{message_iterator}
588 <code>bt_message_iterator_can_seek_beginning(message_iterator)</code>
591 @sa bt_message_iterator_can_seek_beginning() —
592 Returns whether or not a message iterator can currently seek its
595 extern bt_message_iterator_seek_beginning_status
596 bt_message_iterator_seek_beginning(
597 bt_message_iterator
*message_iterator
);
601 Status code for bt_message_iterator_can_seek_ns_from_origin().
603 typedef enum bt_message_iterator_can_seek_ns_from_origin_status
{
608 BT_MESSAGE_ITERATOR_CAN_SEEK_NS_FROM_ORIGIN_STATUS_OK
= __BT_FUNC_STATUS_OK
,
614 BT_MESSAGE_ITERATOR_CAN_SEEK_NS_FROM_ORIGIN_STATUS_AGAIN
= __BT_FUNC_STATUS_AGAIN
,
620 BT_MESSAGE_ITERATOR_CAN_SEEK_NS_FROM_ORIGIN_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
626 BT_MESSAGE_ITERATOR_CAN_SEEK_NS_FROM_ORIGIN_STATUS_ERROR
= __BT_FUNC_STATUS_ERROR
,
627 } bt_message_iterator_can_seek_ns_from_origin_status
;
631 Returns whether or not the message iterator \bt_p{message_iterator}
632 can currently seek a \bt_msg occurring at or after
633 \bt_p{ns_from_origin} nanoseconds from its
634 \ref api-tir-clock-cls-origin "clock class origin".
636 See the \link api-msg-iter-op-seek-ns "seek ns from origin"
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().
643 @param[in] message_iterator
644 Message iterator from which to to get whether or not it can seek
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
650 #BT_TRUE if \bt_p{message_iterator} can seek a message occurring at
651 or after \bt_p{ns_from_origin} nanoseconds from its clock class
654 @retval #BT_MESSAGE_ITERATOR_CAN_SEEK_NS_FROM_ORIGIN_STATUS_OK
656 @retval #BT_MESSAGE_ITERATOR_CAN_SEEK_NS_FROM_ORIGIN_STATUS_AGAIN
658 @retval #BT_MESSAGE_ITERATOR_CAN_SEEK_NS_FROM_ORIGIN_STATUS_MEMORY_ERROR
660 @retval #BT_MESSAGE_ITERATOR_CAN_SEEK_NS_FROM_ORIGIN_STATUS_ERROR
663 @bt_pre_not_null{message_iterator}
664 @bt_pre_not_null{can_seek_ns_from_origin}
666 @sa bt_message_iterator_seek_ns_from_origin() —
667 Makes a message iterator seek a message occurring at or after
668 a given time from its clock class origin.
671 extern bt_message_iterator_can_seek_ns_from_origin_status
672 bt_message_iterator_can_seek_ns_from_origin(
673 bt_message_iterator
*message_iterator
,
674 int64_t ns_from_origin
, bt_bool
*can_seek_ns_from_origin
);
678 Status code for bt_message_iterator_seek_ns_from_origin().
680 typedef enum bt_message_iterator_seek_ns_from_origin_status
{
685 BT_MESSAGE_ITERATOR_SEEK_NS_FROM_ORIGIN_STATUS_OK
= __BT_FUNC_STATUS_OK
,
691 BT_MESSAGE_ITERATOR_SEEK_NS_FROM_ORIGIN_STATUS_AGAIN
= __BT_FUNC_STATUS_AGAIN
,
697 BT_MESSAGE_ITERATOR_SEEK_NS_FROM_ORIGIN_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
703 BT_MESSAGE_ITERATOR_SEEK_NS_FROM_ORIGIN_STATUS_ERROR
= __BT_FUNC_STATUS_ERROR
,
704 } bt_message_iterator_seek_ns_from_origin_status
;
708 Makes the message iterator \bt_p{message_iterator} seek a \bt_msg
709 occurring at or after \bt_p{ns_from_origin} nanoseconds from its
710 \ref api-tir-clock-cls-origin "clock class origin".
712 See \ref api-msg-iter-op-seek-ns "this operation's documentation".
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.
718 @param[in] message_iterator
719 Message iterator to seek to a message occurring at or after
720 \bt_p{ns_from_origin} nanoseconds from its clock class origin.
721 @param[in] ns_from_origin
724 @retval #BT_MESSAGE_ITERATOR_SEEK_NS_FROM_ORIGIN_STATUS_OK
726 @retval #BT_MESSAGE_ITERATOR_SEEK_NS_FROM_ORIGIN_STATUS_AGAIN
728 @retval #BT_MESSAGE_ITERATOR_SEEK_NS_FROM_ORIGIN_STATUS_MEMORY_ERROR
730 @retval #BT_MESSAGE_ITERATOR_SEEK_NS_FROM_ORIGIN_STATUS_ERROR
733 @bt_pre_not_null{message_iterator}
735 <code>bt_message_iterator_can_seek_ns_from_origin(message_iterator, ns_from_origin)</code>
738 @sa bt_message_iterator_can_seek_ns_from_origin() —
739 Returns whether or not a message iterator can currently seek a
740 message occurring at or after a given time from its clock class
743 extern bt_message_iterator_seek_ns_from_origin_status
744 bt_message_iterator_seek_ns_from_origin(
745 bt_message_iterator
*message_iterator
,
746 int64_t ns_from_origin
);
757 Returns whether or not the message iterator \bt_p{message_iterator}
760 A message iterator can seek forward if all the \bt_p_msg of its
761 message sequence have some \bt_cs.
763 @param[in] message_iterator
764 Message iterator of which to get whether or not it can seek forward.
767 #BT_TRUE if \bt_p{message_iterator} can seek forward.
769 @sa bt_self_message_iterator_configuration_set_can_seek_forward() —
770 Sets whether or not a message iterator can seek forward.
773 bt_message_iterator_can_seek_forward(
774 bt_message_iterator
*message_iterator
);
779 @name Reference count
785 Increments the \ref api-fund-shared-object "reference count" of
786 the message iterator \bt_p{message_iterator}.
788 @param[in] message_iterator
790 Message iterator of which to increment the reference count.
795 @sa bt_message_iterator_put_ref() —
796 Decrements the reference count of a message iterator.
798 extern void bt_message_iterator_get_ref(
799 const bt_message_iterator
*message_iterator
);
803 Decrements the \ref api-fund-shared-object "reference count" of
804 the message iterator \bt_p{message_iterator}.
806 @param[in] message_iterator
808 Message iterator of which to decrement the reference count.
813 @sa bt_message_iterator_get_ref() —
814 Increments the reference count of a message iterator.
816 extern void bt_message_iterator_put_ref(
817 const bt_message_iterator
*message_iterator
);
821 Decrements the reference count of the message iterator
822 \bt_p{_message_iterator}, and then sets \bt_p{_message_iterator}
825 @param _message_iterator
827 Message iterator of which to decrement the reference count.
832 @bt_pre_assign_expr{_message_iterator}
834 #define BT_MESSAGE_ITERATOR_PUT_REF_AND_RESET(_message_iterator) \
836 bt_message_iterator_put_ref(_message_iterator); \
837 (_message_iterator) = NULL; \
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
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.
852 Destination expression.
863 @bt_pre_assign_expr{_dst}
864 @bt_pre_assign_expr{_src}
866 #define BT_MESSAGE_ITERATOR_MOVE_REF(_dst, _src) \
868 bt_message_iterator_put_ref(_dst); \
881 #endif /* BABELTRACE2_GRAPH_MESSAGE_ITERATOR_H */