1 #ifndef BABELTRACE2_GRAPH_MESSAGE_ITERATOR_H
2 #define BABELTRACE2_GRAPH_MESSAGE_ITERATOR_H
5 * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
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:
14 * The above copyright notice and this permission notice shall be included in
15 * all copies or substantial portions of the Software.
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
26 #ifndef __BT_IN_BABELTRACE_H
27 # error "Please include <babeltrace2/babeltrace.h> instead."
35 @defgroup api-msg-iter Message iterator
36 @ingroup api-comp-cls-dev
39 Iterator of a \bt_msg sequence.
41 A <strong><em>message iterator</em></strong> iterates a sequence of
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).
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().
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().
59 The type of a message iterator is #bt_message_iterator.
61 There are two contexts from which you can create a message iterator:
64 <dt>From another message iterator</dt>
66 This is the case for a \bt_flt_comp's message iterator.
68 Use bt_message_iterator_create_from_message_iterator().
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".
75 <dt>From a \bt_sink_comp</dt>
77 Use bt_message_iterator_create_from_sink_component().
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:
84 - \ref api-comp-cls-dev-meth-graph-configured "Graph is configured"
87 - \ref api-comp-cls-dev-meth-consume "Consume" method.
91 When you call one of the creation functions above, you pass an \bt_iport
92 on which to create the message iterator.
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:
100 - Any \bt_sink_comp is free to create one or more message iterators
101 on any of its connected input ports.
103 - Any message iterator is free to create one or more message iterators
104 on any of its component's connected input ports.
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:
111 @image html msg-iter.png
113 Many message iterator relations are possible, for example:
115 @image html msg-iter-complex.png
117 <h1>\anchor api-msg-iter-ops Operations</h1>
119 Once you have created a message iterator, there are three possible
124 \anchor api-msg-iter-op-next
125 Get the message iterator's next messages
128 This operation returns a batch of the message iterator's next
129 \bt_p_msg considering its current state.
131 This operation returns a batch of messages instead of a single
132 message for performance reasons.
134 This operation is said to \em advance the message iterator.
136 Get the next messages of a message iterator with
137 bt_message_iterator_next().
141 \anchor api-msg-iter-op-seek-beg
142 Make the message iterator seek its beginning
145 This operation resets the message iterator's position to the
146 beginning of its \ref api-msg-seq "message sequence".
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.
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().
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().
164 \anchor api-msg-iter-op-seek-ns
165 Make the message iterator seek a message occurring at or after a
166 given time (in nanoseconds) from its clock class origin
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".
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.
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.
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().
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().
206 @typedef struct bt_message_iterator bt_message_iterator;
221 Status code for bt_message_iterator_create_from_message_iterator().
223 typedef enum bt_message_iterator_create_from_message_iterator_status
{
228 BT_MESSAGE_ITERATOR_CREATE_FROM_MESSAGE_ITERATOR_STATUS_OK
= __BT_FUNC_STATUS_OK
,
234 BT_MESSAGE_ITERATOR_CREATE_FROM_MESSAGE_ITERATOR_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
240 BT_MESSAGE_ITERATOR_CREATE_FROM_MESSAGE_ITERATOR_STATUS_ERROR
= __BT_FUNC_STATUS_ERROR
,
241 } bt_message_iterator_create_from_message_iterator_status
;
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.
249 On success, the message iterator's position is at the beginning
250 of its \ref api-msg-seq "message sequence".
252 @param[in] self_message_iterator
253 Other message iterator from which to create the message iterator.
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.
260 @retval #BT_MESSAGE_ITERATOR_CREATE_FROM_MESSAGE_ITERATOR_STATUS_OK
262 @retval #BT_MESSAGE_ITERATOR_CREATE_FROM_MESSAGE_ITERATOR_STATUS_MEMORY_ERROR
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.
268 @bt_pre_not_null{self_message_iterator}
269 @bt_pre_not_null{port}
271 <code>bt_port_is_connected(port)</code> returns #BT_TRUE.
272 @bt_pre_not_null{message_iterator}
274 @sa bt_message_iterator_create_from_sink_component() —
275 Creates a message iterator from a \bt_sink_comp.
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
);
285 Status code for bt_message_iterator_create_from_sink_component().
287 typedef enum bt_message_iterator_create_from_sink_component_status
{
292 BT_MESSAGE_ITERATOR_CREATE_FROM_SINK_COMPONENT_STATUS_OK
= __BT_FUNC_STATUS_OK
,
298 BT_MESSAGE_ITERATOR_CREATE_FROM_SINK_COMPONENT_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
304 BT_MESSAGE_ITERATOR_CREATE_FROM_SINK_COMPONENT_STATUS_ERROR
= __BT_FUNC_STATUS_ERROR
,
305 } bt_message_iterator_create_from_sink_component_status
;
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.
313 On success, the message iterator's position is at the beginning
314 of its \ref api-msg-seq "message sequence".
316 @param[in] self_component_sink
317 Sink component from which to create the message iterator.
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.
324 @retval #BT_MESSAGE_ITERATOR_CREATE_FROM_MESSAGE_ITERATOR_STATUS_OK
326 @retval #BT_MESSAGE_ITERATOR_CREATE_FROM_MESSAGE_ITERATOR_STATUS_MEMORY_ERROR
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.
332 @bt_pre_not_null{self_component_sink}
333 @bt_pre_not_null{port}
335 <code>bt_port_is_connected(port)</code> returns #BT_TRUE.
336 @bt_pre_not_null{message_iterator}
338 @sa bt_message_iterator_create_from_message_iterator() —
339 Creates a message iterator from another message iterator.
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
);
350 @name Component access
356 Borrows the \bt_comp which provides the \bt_msg_iter
357 \bt_p{message_iterator}.
359 @param[in] message_iterator
360 Message iterator from which to borrow the component which provides
364 Component which provides \bt_p{message_iterator}.
366 @bt_pre_not_null{message_iterator}
368 extern bt_component
*
369 bt_message_iterator_borrow_component(
370 bt_message_iterator
*message_iterator
);
375 @name "Next" operation (get next messages)
381 Status code for bt_message_iterator_next().
383 typedef enum bt_message_iterator_next_status
{
388 BT_MESSAGE_ITERATOR_NEXT_STATUS_OK
= __BT_FUNC_STATUS_OK
,
394 BT_MESSAGE_ITERATOR_NEXT_STATUS_END
= __BT_FUNC_STATUS_END
,
400 BT_MESSAGE_ITERATOR_NEXT_STATUS_AGAIN
= __BT_FUNC_STATUS_AGAIN
,
406 BT_MESSAGE_ITERATOR_NEXT_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
412 BT_MESSAGE_ITERATOR_NEXT_STATUS_ERROR
= __BT_FUNC_STATUS_ERROR
,
413 } bt_message_iterator_next_status
;
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}.
421 See \ref api-msg-iter-op-next "this operation's documentation".
423 On success, the message iterator's position is advanced by \bt_p{*count}
426 @param[in] message_iterator
427 Message iterator from which to get the next messages.
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.
433 \bt_p{*count} is the number of messages in \bt_p{*messages}.
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.
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.
448 <strong>On success</strong>, \bt_p{*count} is the number of messages
451 @retval #BT_MESSAGE_ITERATOR_NEXT_STATUS_OK
453 @retval #BT_MESSAGE_ITERATOR_NEXT_STATUS_END
455 @retval #BT_MESSAGE_ITERATOR_NEXT_STATUS_AGAIN
457 @retval #BT_MESSAGE_ITERATOR_NEXT_STATUS_MEMORY_ERROR
459 @retval #BT_MESSAGE_ITERATOR_NEXT_STATUS_ERROR
462 @bt_pre_not_null{message_iterator}
463 @bt_pre_not_null{messages}
464 @bt_pre_not_null{count}
467 <strong>On success</strong>, \bt_p{*count} ≥ 1.
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
);
482 Status code for bt_message_iterator_can_seek_beginning().
484 typedef enum bt_message_iterator_can_seek_beginning_status
{
489 BT_MESSAGE_ITERATOR_CAN_SEEK_BEGINNING_STATUS_OK
= __BT_FUNC_STATUS_OK
,
495 BT_MESSAGE_ITERATOR_CAN_SEEK_BEGINNING_STATUS_AGAIN
= __BT_FUNC_STATUS_AGAIN
,
501 BT_MESSAGE_ITERATOR_CAN_SEEK_BEGINNING_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
507 BT_MESSAGE_ITERATOR_CAN_SEEK_BEGINNING_STATUS_ERROR
= __BT_FUNC_STATUS_ERROR
,
508 } bt_message_iterator_can_seek_beginning_status
;
512 Returns whether or not the message iterator \bt_p{message_iterator}
513 can currently seek its beginning (first \bt_msg).
515 See the \link api-msg-iter-op-seek-beg "seek beginning"
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().
522 @param[in] message_iterator
523 Message iterator from which to to get whether or not it can seek
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.
529 @retval #BT_MESSAGE_ITERATOR_CAN_SEEK_BEGINNING_STATUS_OK
531 @retval #BT_MESSAGE_ITERATOR_CAN_SEEK_BEGINNING_STATUS_AGAIN
533 @retval #BT_MESSAGE_ITERATOR_CAN_SEEK_BEGINNING_STATUS_MEMORY_ERROR
535 @retval #BT_MESSAGE_ITERATOR_CAN_SEEK_BEGINNING_STATUS_ERROR
538 @bt_pre_not_null{message_iterator}
539 @bt_pre_not_null{can_seek_beginning}
541 @sa bt_message_iterator_seek_beginning() —
542 Makes a message iterator seek its beginning.
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
);
551 Status code for bt_message_iterator_seek_beginning().
553 typedef enum bt_message_iterator_seek_beginning_status
{
558 BT_MESSAGE_ITERATOR_SEEK_BEGINNING_STATUS_OK
= __BT_FUNC_STATUS_OK
,
564 BT_MESSAGE_ITERATOR_SEEK_BEGINNING_STATUS_AGAIN
= __BT_FUNC_STATUS_AGAIN
,
570 BT_MESSAGE_ITERATOR_SEEK_BEGINNING_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
576 BT_MESSAGE_ITERATOR_SEEK_BEGINNING_STATUS_ERROR
= __BT_FUNC_STATUS_ERROR
,
577 } bt_message_iterator_seek_beginning_status
;
581 Makes the message iterator \bt_p{message_iterator} seek its
582 beginning (first \bt_msg).
584 See \ref api-msg-iter-op-seek-beg "this operation's documentation".
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.
590 @param[in] message_iterator
591 Message iterator to seek to its beginning.
593 @retval #BT_MESSAGE_ITERATOR_SEEK_BEGINNING_STATUS_OK
595 @retval #BT_MESSAGE_ITERATOR_SEEK_BEGINNING_STATUS_AGAIN
597 @retval #BT_MESSAGE_ITERATOR_SEEK_BEGINNING_STATUS_MEMORY_ERROR
599 @retval #BT_MESSAGE_ITERATOR_SEEK_BEGINNING_STATUS_ERROR
602 @bt_pre_not_null{message_iterator}
604 <code>bt_message_iterator_can_seek_beginning(message_iterator)</code>
607 @sa bt_message_iterator_can_seek_beginning() —
608 Returns whether or not a message iterator can currently seek its
611 extern bt_message_iterator_seek_beginning_status
612 bt_message_iterator_seek_beginning(
613 bt_message_iterator
*message_iterator
);
617 Status code for bt_message_iterator_can_seek_ns_from_origin().
619 typedef enum bt_message_iterator_can_seek_ns_from_origin_status
{
624 BT_MESSAGE_ITERATOR_CAN_SEEK_NS_FROM_ORIGIN_STATUS_OK
= __BT_FUNC_STATUS_OK
,
630 BT_MESSAGE_ITERATOR_CAN_SEEK_NS_FROM_ORIGIN_STATUS_AGAIN
= __BT_FUNC_STATUS_AGAIN
,
636 BT_MESSAGE_ITERATOR_CAN_SEEK_NS_FROM_ORIGIN_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
642 BT_MESSAGE_ITERATOR_CAN_SEEK_NS_FROM_ORIGIN_STATUS_ERROR
= __BT_FUNC_STATUS_ERROR
,
643 } bt_message_iterator_can_seek_ns_from_origin_status
;
647 Returns whether or not the message iterator \bt_p{message_iterator}
648 can currently seek a \bt_msg occurring at or after
649 \bt_p{ns_from_origin} nanoseconds from its
650 \ref api-tir-clock-cls-origin "clock class origin".
652 See the \link api-msg-iter-op-seek-ns "seek ns from origin"
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().
659 @param[in] message_iterator
660 Message iterator from which to to get whether or not it can seek
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
666 #BT_TRUE if \bt_p{message_iterator} can seek a message occurring at
667 or after \bt_p{ns_from_origin} nanoseconds from its clock class
670 @retval #BT_MESSAGE_ITERATOR_CAN_SEEK_NS_FROM_ORIGIN_STATUS_OK
672 @retval #BT_MESSAGE_ITERATOR_CAN_SEEK_NS_FROM_ORIGIN_STATUS_AGAIN
674 @retval #BT_MESSAGE_ITERATOR_CAN_SEEK_NS_FROM_ORIGIN_STATUS_MEMORY_ERROR
676 @retval #BT_MESSAGE_ITERATOR_CAN_SEEK_NS_FROM_ORIGIN_STATUS_ERROR
679 @bt_pre_not_null{message_iterator}
680 @bt_pre_not_null{can_seek_ns_from_origin}
682 @sa bt_message_iterator_seek_ns_from_origin() —
683 Makes a message iterator seek a message occurring at or after
684 a given time from its clock class origin.
687 extern bt_message_iterator_can_seek_ns_from_origin_status
688 bt_message_iterator_can_seek_ns_from_origin(
689 bt_message_iterator
*message_iterator
,
690 int64_t ns_from_origin
, bt_bool
*can_seek_ns_from_origin
);
694 Status code for bt_message_iterator_seek_ns_from_origin().
696 typedef enum bt_message_iterator_seek_ns_from_origin_status
{
701 BT_MESSAGE_ITERATOR_SEEK_NS_FROM_ORIGIN_STATUS_OK
= __BT_FUNC_STATUS_OK
,
707 BT_MESSAGE_ITERATOR_SEEK_NS_FROM_ORIGIN_STATUS_AGAIN
= __BT_FUNC_STATUS_AGAIN
,
713 BT_MESSAGE_ITERATOR_SEEK_NS_FROM_ORIGIN_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
719 BT_MESSAGE_ITERATOR_SEEK_NS_FROM_ORIGIN_STATUS_ERROR
= __BT_FUNC_STATUS_ERROR
,
720 } bt_message_iterator_seek_ns_from_origin_status
;
724 Makes the message iterator \bt_p{message_iterator} seek a \bt_msg
725 occurring at or after \bt_p{ns_from_origin} nanoseconds from its
726 \ref api-tir-clock-cls-origin "clock class origin".
728 See \ref api-msg-iter-op-seek-ns "this operation's documentation".
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.
734 @param[in] message_iterator
735 Message iterator to seek to a message occurring at or after
736 \bt_p{ns_from_origin} nanoseconds from its clock class origin.
737 @param[in] ns_from_origin
740 @retval #BT_MESSAGE_ITERATOR_SEEK_NS_FROM_ORIGIN_STATUS_OK
742 @retval #BT_MESSAGE_ITERATOR_SEEK_NS_FROM_ORIGIN_STATUS_AGAIN
744 @retval #BT_MESSAGE_ITERATOR_SEEK_NS_FROM_ORIGIN_STATUS_MEMORY_ERROR
746 @retval #BT_MESSAGE_ITERATOR_SEEK_NS_FROM_ORIGIN_STATUS_ERROR
749 @bt_pre_not_null{message_iterator}
751 <code>bt_message_iterator_can_seek_ns_from_origin(message_iterator, ns_from_origin)</code>
754 @sa bt_message_iterator_can_seek_ns_from_origin() —
755 Returns whether or not a message iterator can currently seek a
756 message occurring at or after a given time from its clock class
759 extern bt_message_iterator_seek_ns_from_origin_status
760 bt_message_iterator_seek_ns_from_origin(
761 bt_message_iterator
*message_iterator
,
762 int64_t ns_from_origin
);
773 Returns whether or not the message iterator \bt_p{message_iterator}
776 A message iterator can seek forward if all the \bt_p_msg of its
777 message sequence have some \bt_cs.
779 @param[in] message_iterator
780 Message iterator of which to get whether or not it can seek forward.
783 #BT_TRUE if \bt_p{message_iterator} can seek forward.
785 @sa bt_self_message_iterator_configuration_set_can_seek_forward() —
786 Sets whether or not a message iterator can seek forward.
789 bt_message_iterator_can_seek_forward(
790 bt_message_iterator
*message_iterator
);
795 @name Reference count
801 Increments the \ref api-fund-shared-object "reference count" of
802 the message iterator \bt_p{message_iterator}.
804 @param[in] message_iterator
806 Message iterator of which to increment the reference count.
811 @sa bt_message_iterator_put_ref() —
812 Decrements the reference count of a message iterator.
814 extern void bt_message_iterator_get_ref(
815 const bt_message_iterator
*message_iterator
);
819 Decrements the \ref api-fund-shared-object "reference count" of
820 the message iterator \bt_p{message_iterator}.
822 @param[in] message_iterator
824 Message iterator of which to decrement the reference count.
829 @sa bt_message_iterator_get_ref() —
830 Increments the reference count of a message iterator.
832 extern void bt_message_iterator_put_ref(
833 const bt_message_iterator
*message_iterator
);
837 Decrements the reference count of the message iterator
838 \bt_p{_message_iterator}, and then sets \bt_p{_message_iterator}
841 @param _message_iterator
843 Message iterator of which to decrement the reference count.
848 @bt_pre_assign_expr{_message_iterator}
850 #define BT_MESSAGE_ITERATOR_PUT_REF_AND_RESET(_message_iterator) \
852 bt_message_iterator_put_ref(_message_iterator); \
853 (_message_iterator) = NULL; \
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
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.
868 Destination expression.
879 @bt_pre_assign_expr{_dst}
880 @bt_pre_assign_expr{_src}
882 #define BT_MESSAGE_ITERATOR_MOVE_REF(_dst, _src) \
884 bt_message_iterator_put_ref(_dst); \
897 #endif /* BABELTRACE2_GRAPH_MESSAGE_ITERATOR_H */