1 #ifndef BABELTRACE2_GRAPH_MESSAGE_ITERATOR_CLASS_H
2 #define BABELTRACE2_GRAPH_MESSAGE_ITERATOR_CLASS_H
5 * Copyright (c) 2019 EfficiOS Inc.
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."
36 @defgroup api-msg-iter-cls Message iterator class
37 @ingroup api-comp-cls-dev
42 A <strong><em>message iterator class</em></strong> is the class of a
45 @image html msg-iter-cls.png
47 \bt_cp_src_comp_cls and \bt_p_flt_comp_cls contain a message iterator
48 class. For such a component class, its message iterator class is the
49 class of any message iterator created for any \bt_oport of the
50 component class's instances (\bt_p_comp).
52 Therefore, the only thing you can do with a message iterator class is to
53 pass it to bt_component_class_source_create() or
54 bt_component_class_filter_create() to set it as the created component
55 class's message iterator class.
57 A message iterator class has <em>methods</em>. This module essentially
60 - Message iterator class method type definitions.
62 - A message iterator class creation function, to which you must pass
63 the mandatory \link api-msg-iter-cls-meth-next "next" method\endlink.
65 - Functions to set optional message iterator class methods.
67 A message iterator class method is a user function. All message iterator
68 class methods operate on an instance (a \bt_msg_iter). The type of the
69 method's first parameter is #bt_self_message_iterator. This is similar
70 to an instance method in Python (where the instance object name is
71 generally <code>self</code>) or a member function in C++ (where the
72 instance pointer is named <code>this</code>), for example.
74 See \ref api-msg-iter-cls-methods "Methods" to learn more about the
75 different types of message iterator class methods.
77 A message iterator class is a
78 \ref api-fund-shared-object "shared object": get a new reference with
79 bt_message_iterator_class_get_ref() and put an existing reference with
80 bt_message_iterator_class_put_ref().
82 Some library functions \ref api-fund-freezing "freeze" message iterator
83 classes on success. The documentation of those functions indicate this
86 The type of a message iterator class is #bt_message_iterator_class.
88 Create a message iterator class with bt_message_iterator_class_create().
89 When you call this function, you must pass the message iterator
91 \link api-msg-iter-cls-meth-next "next" method\endlink.
93 <h1>\anchor api-msg-iter-cls-methods Methods</h1>
95 To learn when exactly the methods below are called, see
96 \ref api-graph-lc "Trace processing graph life cycle" and
99 The available message iterator class methods to implement are:
107 <td>Can seek beginning?
109 <td>#bt_message_iterator_class_can_seek_beginning_method
111 <td>Can seek ns from origin?
113 <td>#bt_message_iterator_class_can_seek_ns_from_origin_method
117 <td>#bt_message_iterator_class_finalize_method
121 <td>#bt_message_iterator_class_initialize_method
125 <td>#bt_message_iterator_class_next_method
129 <td>#bt_message_iterator_class_seek_beginning_method
131 <td>Seek ns from origin
133 <td>#bt_message_iterator_class_seek_ns_from_origin_method
138 \anchor api-msg-iter-cls-meth-can-seek-beg
142 Called to check whether or not your \bt_msg_iter can currently
143 seek its beginning (the very first message of its
144 \ref api-msg-seq "sequence").
146 There are some use cases in which a message iterator cannot always
147 seek its beginning, depending on its state.
149 If you don't implement this method, then, if you implement the
150 \ref api-msg-iter-cls-meth-seek-beg "seek beginning" method, the
151 library assumes that your message iterator can always seek its
154 The message iterator of a \bt_flt_comp will typically consider
155 the beginning seeking capability of its own upstream message
156 iterator(s) (with bt_message_iterator_can_seek_beginning()) in this
157 method's implementation.
159 If you need to block the thread to compute whether or not your
160 message iterator can seek its beginning, you can instead report to
161 try again later to the caller by returning
162 #BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_BEGINNING_METHOD_STATUS_AGAIN.
164 Set this optional method with the \bt_p{can_seek_method} parameter
165 of bt_message_iterator_class_set_seek_beginning_methods().
169 \anchor api-msg-iter-cls-meth-can-seek-ns
170 Can seek ns from origin?
173 Called to check whether or not your \bt_msg_iter can currently
174 seek a message occurring at or after a specific time given in
176 \ref api-tir-clock-cls-origin "clock class origin".
178 There are some use cases in which a message iterator cannot always
179 seek some specific time, depending on its state.
181 Within this method, your receive the specific time to seek as the
182 \bt_p{ns_from_origin} parameter. You don't receive any
183 \bt_clock_cls: the method operates at the nanosecond from some
184 origin level and it is left to the implementation to decide whether
185 or not the message iterator can seek this point in time.
187 If you don't implement this method, then, if you implement the
188 \ref api-msg-iter-cls-meth-seek-ns "seek ns from origin" method, the
189 library assumes that your message iterator can always seek any
190 message occurring at or after any time.
192 The message iterator of a \bt_flt_comp will typically consider
193 the time seeking capability of its own upstream message
194 iterator(s) (with bt_message_iterator_can_seek_ns_from_origin()) in
195 this method's implementation.
197 If you need to block the thread to compute whether or not your
198 message iterator can seek a message occurring at or after a given
199 time, you can instead report to try again later to the caller by
201 #BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_AGAIN.
203 Set this optional method with the \bt_p{can_seek_method} parameter
204 of bt_message_iterator_class_set_seek_ns_from_origin_methods().
208 \anchor api-msg-iter-cls-meth-fini
212 Called to finalize your \bt_msg_iter, that is, to let you
213 destroy/free/finalize any user data you have (retrieved with
214 bt_self_message_iterator_get_data()).
216 The \bt_name library does not specify exactly when this method is
217 called, but guarantees that it's called before the message iterator
220 The library guarantees that all message iterators are destroyed
221 before their component is destroyed.
223 This method is \em not called if the message iterator's
224 \ref api-msg-iter-cls-meth-init "initialization method"
225 previously returned an error status code.
227 Set this optional method with
228 bt_message_iterator_class_set_finalize_method().
232 \anchor api-msg-iter-cls-meth-init
236 Called within bt_message_iterator_create_from_message_iterator()
237 or bt_message_iterator_create_from_sink_component() to initialize
240 Within this method, you can access your \bt_comp's user data
241 by first borrowing it with
242 bt_self_message_iterator_borrow_component() and then using
243 bt_self_component_get_data().
245 For the message iterator of a \bt_flt_comp, this method is
246 typically where you create an upstream \bt_msg_iter
247 with bt_message_iterator_create_from_message_iterator().
249 You can create user data and set it as the \bt_self_msg_iter's user
250 data with bt_self_message_iterator_set_data().
252 If you return #BT_MESSAGE_ITERATOR_CLASS_INITIALIZE_METHOD_STATUS_OK
253 from this method, then your message iterator's
254 \ref api-msg-iter-cls-meth-fini "finalization method" will be
255 called, if it exists, when your message iterator is finalized.
257 This method receives a message iterator configuration object
258 (#bt_self_message_iterator_configuration type). As of
259 \bt_name_version_min_maj, you can use
260 bt_self_message_iterator_configuration_set_can_seek_forward()
261 during, and only during, this method's execution to set whether or
262 not your message iterator can <em>seek forward</em>.
264 For a message iterator to be able to seek forward, all the \bt_p_msg
265 of its message sequence must have some \bt_cs.
266 bt_message_iterator_seek_ns_from_origin() uses this configuration
267 option and the beginning seeking capability of a message iterator
268 (bt_message_iterator_can_seek_beginning())
269 to make it seek a message occurring at or after a specific time even
270 when the message iterator does not implement the
271 \ref api-msg-iter-cls-meth-seek-ns "seek ns from origin" method.
273 Set this optional method with
274 bt_message_iterator_class_set_initialize_method().
278 \anchor api-msg-iter-cls-meth-next
279 "Next" (get next messages)
282 Called within bt_message_iterator_next()
283 to "advance" your \bt_msg_iter, that is, to get its next
286 Within this method, you receive:
288 - An array of \bt_p_msg to fill (\bt_p{messages} parameter)
289 with your message iterator's next messages, if any.
291 Note that this array needs its own message
292 \ref api-fund-shared-object "references". In other
293 words, if you have a message reference and you put this message
294 into the array without calling bt_message_get_ref(), then you just
295 \em moved the message reference to the array (the array owns the
298 - The capacity of the message array (\bt_p{capacity} parameter),
299 that is, the maximum number of messages you can put in it.
301 - A message count output parameter (\bt_p{count}) which, on success,
302 you must set to the number of messages you put in the message
305 If you return #BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_OK
306 from this method, then you must put at least one message in the
307 message array. In other words, \bt_p{*count} must be greater than
310 You must honour the \ref api-msg-seq "message sequence rules" when
311 you put new or existing messages in the message array.
313 If you return #BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_OK,
314 then all the messages of the message array become
315 \ref api-fund-freezing "frozen".
317 This method typically:
320 <dt>For a \bt_src_comp's message iterator</dt>
322 Creates brand new \bt_p_msg to represent one or more input
326 <dt>For a \bt_flt_comp's message iterator</dt>
328 Gets \em one message batch from one (or more) upstream
329 \bt_msg_iter and filters them.
333 For a source component's message iterator, you are free to create
334 as many as \bt_p{capacity} messages. For a filter component's
335 message iterator, you are free to get more than one batch of
336 messages from upstream message iterators if needed. However, in both
337 cases, keep in mind that the \bt_name project recommends that this
338 method executes fast enough so as not to block an interactive
339 application running on the same thread.
341 During what you consider to be a long, blocking operation, the
342 project recommends that you periodically check whether or not you
343 are interrupted with bt_self_message_iterator_is_interrupted(). When
344 you are, you can return either
345 #BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_AGAIN or
346 #BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_ERROR, depending on
347 your capability to continue the current operation later.
349 If you need to block the thread to insert messages into the message
350 array, you can instead report to try again later to the caller by
351 returning #BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_AGAIN.
352 When you return this status code, you must \em not put any message
353 into the message array.
355 If your message iterator's iteration process is done (you have no
356 more messages to emit), then return
357 #BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_END. When you return
358 this status code, you must \em not put any message into the message
361 Set this mandatory method at message iterator class creation time
362 with bt_message_iterator_class_create().
366 \anchor api-msg-iter-cls-meth-seek-beg
370 Called within bt_message_iterator_seek_beginning() to make
371 your message iterator seek its beginning, that is, the very first
372 message of its \ref api-msg-seq "sequence".
374 The sequence of messages of a given message iterator must always be
375 the same, in that, if your message iterator emitted the messages A,
376 B, C, D, and E, and then this "seek beginning" method is called
379 #BT_MESSAGE_ITERATOR_CLASS_SEEK_BEGINNING_METHOD_STATUS_OK),
380 then your message iterator's next messages (the next time your
381 \link api-msg-iter-cls-meth-next "next" method\endlink
382 is called) must be A, B, C, D, and E.
384 The \bt_name project recommends that this method executes fast
385 enough so as not to block an interactive application running on the
388 During what you consider to be a long, blocking operation, the
389 project recommends that you periodically check whether or not you
390 are interrupted with bt_self_message_iterator_is_interrupted(). When
391 you are, you can return either
392 #BT_MESSAGE_ITERATOR_CLASS_SEEK_BEGINNING_METHOD_STATUS_AGAIN or
393 #BT_MESSAGE_ITERATOR_CLASS_SEEK_BEGINNING_METHOD_STATUS_ERROR,
394 depending on your capability to continue the current operation
397 If you need to block the thread to make your message iterator seek
398 its beginning, you can instead report to try again later to the
400 #BT_MESSAGE_ITERATOR_CLASS_SEEK_BEGINNING_METHOD_STATUS_AGAIN.
403 \ref api-msg-iter-cls-meth-can-seek-beg "can seek beginning?"
404 method can indicate whether or not your message iterator can
405 currently seek its beginning. If you implement it, the library
406 guarantees that it is called and returns #BT_TRUE before this "seek
407 beginning" is called, without any other message iterator methods
408 being called in between.
410 Set this optional method with the \bt_p{seek_method} parameter
411 of bt_message_iterator_class_set_seek_beginning_methods().
415 \anchor api-msg-iter-cls-meth-seek-ns
419 Called within bt_message_iterator_seek_ns_from_origin() to make
420 your message iterator seek a message occurring at or after a specific
421 time given in nanoseconds from its
422 \ref api-tir-clock-cls-origin "clock class origin".
424 Within this method, your receive the specific time to seek as the
425 \bt_p{ns_from_origin} parameter. You don't receive any
426 \bt_clock_cls: the method operates at the nanosecond from some
427 origin level and it is left to the implementation to seek a message
428 having at least this time while still honouring the
429 \ref api-msg-seq "message sequence rules" the next time your
430 \link api-msg-iter-cls-meth-next "next" method\endlink is called.
433 #BT_MESSAGE_ITERATOR_CLASS_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_OK from
434 this method, then the next time your
435 \link api-msg-iter-cls-meth-next "next" method\endlink is called:
437 - For each "active" \bt_stream at the seeked time point, you must
438 emit a \bt_sb_msg for this stream before you emit any other
439 message for this stream.
441 The stream beginning message must have a
442 \ref api-msg-sb-prop-cs "default clock snapshot" which corresponds
443 to the seeked time point.
445 - For each "active" \bt_pkt at the seeked time point, you must
446 emit a \bt_pb_msg for this packet before you emit any other
447 message for this packet.
449 The packet beginning message must have a
450 \ref api-msg-pb-prop-cs "default clock snapshot" which corresponds
451 to the seeked time point.
453 The \bt_name project recommends that this method executes fast
454 enough so as not to block an interactive application running on the
457 During what you consider to be a long, blocking operation, the
458 project recommends that you periodically check whether or not you
459 are interrupted with bt_self_message_iterator_is_interrupted(). When
460 you are, you can return either
461 #BT_MESSAGE_ITERATOR_CLASS_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_AGAIN
463 #BT_MESSAGE_ITERATOR_CLASS_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_ERROR,
464 depending on your capability to continue the current operation
467 If you need to block the thread to make your message iterator seek a
468 message occurring at or after a given time, you can instead report to
469 try again later to the caller by returning
470 #BT_MESSAGE_ITERATOR_CLASS_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_AGAIN.
473 \ref api-msg-iter-cls-meth-can-seek-ns "can seek ns from origin?"
474 method can indicate whether or not your message iterator can
475 currently seek a specific time. If you implement it, the library
476 guarantees that it is called and returns #BT_TRUE before this "seek
477 ns from origin" is called, without any other message iterator
478 methods being called in between.
480 Set this optional method with the \bt_p{seek_method} parameter
481 of bt_message_iterator_class_set_seek_ns_from_origin_methods().
485 Within any method, you can access the \bt_msg_iter's \bt_comp's
486 configured \ref #bt_logging_level "logging level" by first upcasting the
487 \bt_self_comp to the #bt_component type with
488 bt_self_component_as_component(), and then with
489 bt_component_get_logging_level().
498 @typedef struct bt_message_iterator_class bt_message_iterator_class;
501 Message iterator class.
513 Status codes for #bt_message_iterator_class_can_seek_beginning_method.
515 typedef enum bt_message_iterator_class_can_seek_beginning_method_status
{
520 BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_BEGINNING_METHOD_STATUS_OK
= __BT_FUNC_STATUS_OK
,
526 BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_BEGINNING_METHOD_STATUS_AGAIN
= __BT_FUNC_STATUS_AGAIN
,
532 BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_BEGINNING_METHOD_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
538 BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_BEGINNING_METHOD_STATUS_ERROR
= __BT_FUNC_STATUS_ERROR
,
539 } bt_message_iterator_class_can_seek_beginning_method_status
;
543 \bt_c_msg_iter "can seek beginning?" method.
545 See the \ref api-msg-iter-cls-meth-can-seek-beg "can seek beginning?"
548 @param[in] self_message_iterator
549 Message iterator instance.
550 @param[out] can_seek_beginning
551 <strong>On success</strong>, \bt_p{*can_seek_beginning} is
552 #BT_TRUE if \bt_p{self_message_iterator} can currently seek its
555 @retval #BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_BEGINNING_METHOD_STATUS_OK
557 @retval #BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_BEGINNING_METHOD_STATUS_AGAIN
559 @retval #BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_BEGINNING_METHOD_STATUS_MEMORY_ERROR
561 @retval #BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_BEGINNING_METHOD_STATUS_ERROR
564 @bt_pre_not_null{self_message_iterator}
565 @bt_pre_not_null{can_seek_beginning}
568 <strong>On success</strong>, \bt_p{*can_seek_beginning} is set.
570 @sa bt_message_iterator_class_set_seek_beginning_methods() —
571 Sets the "seek beginning" and "can seek beginning?" methods of a
572 message iterator class.
574 typedef bt_message_iterator_class_can_seek_beginning_method_status
575 (*bt_message_iterator_class_can_seek_beginning_method
)(
576 bt_self_message_iterator
*self_message_iterator
,
577 bt_bool
*can_seek_beginning
);
581 Status codes for #bt_message_iterator_class_can_seek_ns_from_origin_method.
583 typedef enum bt_message_iterator_class_can_seek_ns_from_origin_method_status
{
588 BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_OK
= __BT_FUNC_STATUS_OK
,
594 BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_AGAIN
= __BT_FUNC_STATUS_AGAIN
,
600 BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
606 BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_ERROR
= __BT_FUNC_STATUS_ERROR
,
607 } bt_message_iterator_class_can_seek_ns_from_origin_method_status
;
611 \bt_c_msg_iter "can seek ns from origin?" method.
613 See the \ref api-msg-iter-cls-meth-can-seek-ns "can seek ns from origin?"
616 @param[in] self_message_iterator
617 Message iterator instance.
618 @param[in] ns_from_origin
619 Requested time point to seek.
620 @param[out] can_seek_ns_from_origin
621 <strong>On success</strong>, set \bt_p{*can_seek_ns_from_origin} to
622 #BT_TRUE if \bt_p{self_message_iterator} can currently seek a
623 message occurring at or after \bt_p{ns_from_origin} nanoseconds from
624 its \ref api-tir-clock-cls-origin "clock class origin".
626 @retval #BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_OK
628 @retval #BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_AGAIN
630 @retval #BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_MEMORY_ERROR
632 @retval #BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_ERROR
635 @bt_pre_not_null{self_message_iterator}
636 @bt_pre_not_null{can_seek_ns_from_origin}
639 <strong>On success</strong>, \bt_p{*can_seek_ns_from_origin} is set.
641 @sa bt_message_iterator_class_set_seek_ns_from_origin_methods() —
642 Sets the "seek ns from origin" and "can seek ns from origin?"
643 methods of a message iterator class.
645 typedef bt_message_iterator_class_can_seek_ns_from_origin_method_status
646 (*bt_message_iterator_class_can_seek_ns_from_origin_method
)(
647 bt_self_message_iterator
*self_message_iterator
,
648 int64_t ns_from_origin
, bt_bool
*can_seek_ns_from_origin
);
652 \bt_c_msg_iter finalization method.
654 See the \ref api-msg-iter-cls-meth-fini "finalize" method.
656 @param[in] self_message_iterator
657 Message iterator instance.
659 @bt_pre_not_null{self_message_iterator}
663 @sa bt_message_iterator_class_set_finalize_method() —
664 Sets the finalization method of a message iterator class.
667 (*bt_message_iterator_class_finalize_method
)(
668 bt_self_message_iterator
*self_message_iterator
);
672 Status codes for #bt_message_iterator_class_initialize_method.
674 typedef enum bt_message_iterator_class_initialize_method_status
{
679 BT_MESSAGE_ITERATOR_CLASS_INITIALIZE_METHOD_STATUS_OK
= __BT_FUNC_STATUS_OK
,
685 BT_MESSAGE_ITERATOR_CLASS_INITIALIZE_METHOD_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
691 BT_MESSAGE_ITERATOR_CLASS_INITIALIZE_METHOD_STATUS_ERROR
= __BT_FUNC_STATUS_ERROR
,
692 } bt_message_iterator_class_initialize_method_status
;
696 \bt_c_msg_iter initialization method.
698 See the \ref api-msg-iter-cls-meth-init "initialize" method.
700 @param[in] self_message_iterator
701 Message iterator instance.
702 @param[in] configuration
703 Message iterator's configuration.
705 \bt_c_oport for which \bt_p{self_message_iterator} was created.
707 @retval #BT_MESSAGE_ITERATOR_CLASS_INITIALIZE_METHOD_STATUS_OK
709 @retval #BT_MESSAGE_ITERATOR_CLASS_INITIALIZE_METHOD_STATUS_MEMORY_ERROR
711 @retval #BT_MESSAGE_ITERATOR_CLASS_INITIALIZE_METHOD_STATUS_ERROR
714 @bt_pre_not_null{self_message_iterator}
715 @bt_pre_not_null{configuration}
716 @bt_pre_not_null{port}
718 @sa bt_message_iterator_class_set_initialize_method() —
719 Sets the initialization method of a message iterator class.
721 typedef bt_message_iterator_class_initialize_method_status
722 (*bt_message_iterator_class_initialize_method
)(
723 bt_self_message_iterator
*self_message_iterator
,
724 bt_self_message_iterator_configuration
*configuration
,
725 bt_self_component_port_output
*port
);
729 Status codes for #bt_message_iterator_class_next_method.
731 typedef enum bt_message_iterator_class_next_method_status
{
736 BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_OK
= __BT_FUNC_STATUS_OK
,
742 BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_END
= __BT_FUNC_STATUS_END
,
748 BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_AGAIN
= __BT_FUNC_STATUS_AGAIN
,
754 BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
760 BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_ERROR
= __BT_FUNC_STATUS_ERROR
,
761 } bt_message_iterator_class_next_method_status
;
765 \bt_c_msg_iter "next" (get next messages) method.
767 See the \link api-msg-iter-cls-meth-next "next"\endlink method.
769 If this method returns #BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_OK,
770 then all the messages of the message array become
771 \ref api-fund-freezing "frozen".
773 @param[in] self_message_iterator
774 Message iterator instance.
777 Message array to fill, on success, with the \bt_p_msg to emit.
779 This array needs its own message
780 \ref api-fund-shared-object "references". In other
781 words, if you have a message reference and you put this message
782 into the array without calling bt_message_get_ref(), then you just
783 \em moved the message reference to the array (the array owns the
786 The capacity of this array (maximum number of messages you can put
787 in it) is \bt_p{capacity}.
790 Capacity of the \bt_p{messages} array (maximum number of messages
793 <strong>On success</strong>, \bt_p{*count} is the number of messages
794 you put in \bt_p{messages}.
796 @retval #BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_OK
798 @retval #BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_END
800 @retval #BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_AGAIN
802 @retval #BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_MEMORY_ERROR
804 @retval #BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_ERROR
807 @bt_pre_not_null{self_message_iterator}
808 @bt_pre_not_null{messages}
810 \bt_p{capacity} ≥ 1.
811 @bt_pre_not_null{count}
814 <strong>On success</strong>, \bt_p{messages} contains \bt_p{*count}
815 message references as its first \bt_p{*count} elements.
817 <strong>On success</strong>, the \bt_p_msg in \bt_p{messages} honour
818 the \ref api-msg-seq "message sequence rules".
820 <strong>On success</strong>, for any \bt_ev_msg in
822 \ref api-tir-ev-prop-payload "payload field",
823 \ref api-tir-ev-prop-spec-ctx "specific context field",
824 \ref api-tir-ev-prop-common-ctx "common context field", and all
825 their inner \bt_p_field, recursively, are set.
827 <strong>On success</strong>, \bt_p{*count} ≥ 1.
829 <strong>On success</strong>,
830 \bt_p{*count} ≤ \bt_p{capacity}.
832 @sa bt_message_iterator_class_create() —
833 Creates a message iterator class.
835 typedef bt_message_iterator_class_next_method_status
836 (*bt_message_iterator_class_next_method
)(
837 bt_self_message_iterator
*self_message_iterator
,
838 bt_message_array_const messages
, uint64_t capacity
,
843 Status codes for #bt_message_iterator_class_seek_beginning_method.
845 typedef enum bt_message_iterator_class_seek_beginning_method_status
{
850 BT_MESSAGE_ITERATOR_CLASS_SEEK_BEGINNING_METHOD_STATUS_OK
= __BT_FUNC_STATUS_OK
,
856 BT_MESSAGE_ITERATOR_CLASS_SEEK_BEGINNING_METHOD_STATUS_AGAIN
= __BT_FUNC_STATUS_AGAIN
,
862 BT_MESSAGE_ITERATOR_CLASS_SEEK_BEGINNING_METHOD_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
868 BT_MESSAGE_ITERATOR_CLASS_SEEK_BEGINNING_METHOD_STATUS_ERROR
= __BT_FUNC_STATUS_ERROR
,
869 } bt_message_iterator_class_seek_beginning_method_status
;
873 \bt_c_msg_iter "seek beginning" method.
875 See the \ref api-msg-iter-cls-meth-seek-beg "seek beginning" method.
877 @param[in] self_message_iterator
878 Message iterator instance.
880 @retval #BT_MESSAGE_ITERATOR_CLASS_SEEK_BEGINNING_METHOD_STATUS_OK
882 @retval #BT_MESSAGE_ITERATOR_CLASS_SEEK_BEGINNING_METHOD_STATUS_AGAIN
884 @retval #BT_MESSAGE_ITERATOR_CLASS_SEEK_BEGINNING_METHOD_STATUS_MEMORY_ERROR
886 @retval #BT_MESSAGE_ITERATOR_CLASS_SEEK_BEGINNING_METHOD_STATUS_ERROR
889 @bt_pre_not_null{self_message_iterator}
891 <strong>If \bt_p{self_message_iterator} has a
892 \ref api-msg-iter-cls-meth-can-seek-beg "can seek beginning?"
893 method</strong>, then it was called and returned #BT_TRUE before
894 this "seek beginning" method is called, without any other method of
895 \bt_p{self_message_iterator} called in between.
897 @sa bt_message_iterator_class_set_seek_beginning_methods() —
898 Sets the "seek beginning" and "can seek beginning?" methods of a
899 message iterator class.
901 typedef bt_message_iterator_class_seek_beginning_method_status
902 (*bt_message_iterator_class_seek_beginning_method
)(
903 bt_self_message_iterator
*self_message_iterator
);
907 Status codes for #bt_message_iterator_class_seek_ns_from_origin_method.
909 typedef enum bt_message_iterator_class_seek_ns_from_origin_method_status
{
914 BT_MESSAGE_ITERATOR_CLASS_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_OK
= __BT_FUNC_STATUS_OK
,
920 BT_MESSAGE_ITERATOR_CLASS_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_AGAIN
= __BT_FUNC_STATUS_AGAIN
,
926 BT_MESSAGE_ITERATOR_CLASS_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
932 BT_MESSAGE_ITERATOR_CLASS_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_ERROR
= __BT_FUNC_STATUS_ERROR
,
933 } bt_message_iterator_class_seek_ns_from_origin_method_status
;
937 \bt_c_msg_iter "seek ns from origin" method.
939 See the \ref api-msg-iter-cls-meth-seek-ns "seek ns from origin" method.
941 @param[in] self_message_iterator
942 Message iterator instance.
943 @param[in] ns_from_origin
946 @retval #BT_MESSAGE_ITERATOR_CLASS_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_OK
948 @retval #BT_MESSAGE_ITERATOR_CLASS_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_AGAIN
950 @retval #BT_MESSAGE_ITERATOR_CLASS_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_MEMORY_ERROR
952 @retval #BT_MESSAGE_ITERATOR_CLASS_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_ERROR
955 @bt_pre_not_null{self_message_iterator}
957 <strong>If \bt_p{self_message_iterator} has a
958 \ref api-msg-iter-cls-meth-can-seek-ns "can seek ns from origin?"
959 method</strong>, then it was called and returned #BT_TRUE before
960 this "seek ns from origin" method is called, without any other
961 method of \bt_p{self_message_iterator} called in between.
963 @sa bt_message_iterator_class_set_seek_ns_from_origin_methods() —
964 Sets the "seek ns from origin" and "can seek ns from origin?"
965 methods of a message iterator class.
967 typedef bt_message_iterator_class_seek_ns_from_origin_method_status
968 (*bt_message_iterator_class_seek_ns_from_origin_method
)(
969 bt_self_message_iterator
*self_message_iterator
,
970 int64_t ns_from_origin
);
981 Creates a message iterator class having the
982 \link api-msg-iter-cls-meth-next "next" method\endlink method
985 @param[in] next_method
986 "Next" method of the message iterator class to create.
989 New message iterator class reference, or \c NULL on memory error.
991 @bt_pre_not_null{next_method}
993 extern bt_message_iterator_class
*
994 bt_message_iterator_class_create(
995 bt_message_iterator_class_next_method next_method
);
1000 @name Method setting
1007 <code>bt_message_iterator_class_set_*_method()</code> functions.
1009 typedef enum bt_message_iterator_class_set_method_status
{
1014 BT_MESSAGE_ITERATOR_CLASS_SET_METHOD_STATUS_OK
= __BT_FUNC_STATUS_OK
,
1015 } bt_message_iterator_class_set_method_status
;
1019 Sets the optional finalization method of the message iterator class
1020 \bt_p{message_iterator_class} to \bt_p{method}.
1022 See the \ref api-msg-iter-cls-meth-fini "finalize" method.
1024 @param[in] message_iterator_class
1025 Message iterator class of which to set the finalization method to
1028 New finalization method of \bt_p{message_iterator_class}.
1030 @retval #BT_MESSAGE_ITERATOR_CLASS_SET_METHOD_STATUS_OK
1033 @bt_pre_not_null{message_iterator_class}
1034 @bt_pre_hot{message_iterator_class}
1035 @bt_pre_not_null{method}
1037 extern bt_message_iterator_class_set_method_status
1038 bt_message_iterator_class_set_finalize_method(
1039 bt_message_iterator_class
*message_iterator_class
,
1040 bt_message_iterator_class_finalize_method method
);
1044 Sets the optional initialization method of the message iterator
1045 class \bt_p{message_iterator_class} to \bt_p{method}.
1047 See the \ref api-msg-iter-cls-meth-init "initialize" method.
1049 @param[in] message_iterator_class
1050 Message iterator class of which to set the initialization method to
1053 New initialization method of \bt_p{message_iterator_class}.
1055 @retval #BT_MESSAGE_ITERATOR_CLASS_SET_METHOD_STATUS_OK
1058 @bt_pre_not_null{message_iterator_class}
1059 @bt_pre_hot{message_iterator_class}
1060 @bt_pre_not_null{method}
1062 extern bt_message_iterator_class_set_method_status
1063 bt_message_iterator_class_set_initialize_method(
1064 bt_message_iterator_class
*message_iterator_class
,
1065 bt_message_iterator_class_initialize_method method
);
1069 Sets the optional "seek beginning" and
1070 "can seek beginning?" methods of the message iterator class
1071 \bt_p{message_iterator_class} to \bt_p{seek_method} and
1072 \bt_p{can_seek_method}.
1074 See the \ref api-msg-iter-cls-meth-seek-beg "seek beginning"
1075 and \ref api-msg-iter-cls-meth-can-seek-beg "can seek beginning?"
1078 @param[in] message_iterator_class
1079 Message iterator class of which to set the "seek beginning"
1080 and "can seek beginning?" methods.
1081 @param[in] seek_method
1082 New "seek beginning" method of \bt_p{message_iterator_class}.
1083 @param[in] can_seek_method
1085 New "can seek beginning?" method of \bt_p{message_iterator_class}.
1087 Can be \c NULL, in which case it is equivalent to setting a method
1088 which always returns #BT_TRUE.
1091 @retval #BT_MESSAGE_ITERATOR_CLASS_SET_METHOD_STATUS_OK
1094 @bt_pre_not_null{message_iterator_class}
1095 @bt_pre_hot{message_iterator_class}
1096 @bt_pre_not_null{seek_method}
1098 extern bt_message_iterator_class_set_method_status
1099 bt_message_iterator_class_set_seek_beginning_methods(
1100 bt_message_iterator_class
*message_iterator_class
,
1101 bt_message_iterator_class_seek_beginning_method seek_method
,
1102 bt_message_iterator_class_can_seek_beginning_method can_seek_method
);
1106 Sets the optional "seek ns from origin" and
1107 "can seek ns from origin?" methods of the message iterator class
1108 \bt_p{message_iterator_class} to \bt_p{seek_method} and
1109 \bt_p{can_seek_method}.
1111 See the \ref api-msg-iter-cls-meth-seek-ns "seek ns from origin"
1113 \ref api-msg-iter-cls-meth-can-seek-ns "can seek ns from origin?"
1116 @param[in] message_iterator_class
1117 Message iterator class of which to set the "seek ns from origin"
1118 and "can seek ns from origin?" methods.
1119 @param[in] seek_method
1120 New "seek ns from origin" method of \bt_p{message_iterator_class}.
1121 @param[in] can_seek_method
1123 New "can seek ns from origin?" method of
1124 \bt_p{message_iterator_class}.
1126 Can be \c NULL, in which case it is equivalent to setting a method
1127 which always returns #BT_TRUE.
1130 @retval #BT_MESSAGE_ITERATOR_CLASS_SET_METHOD_STATUS_OK
1133 @bt_pre_not_null{message_iterator_class}
1134 @bt_pre_hot{message_iterator_class}
1135 @bt_pre_not_null{seek_method}
1137 extern bt_message_iterator_class_set_method_status
1138 bt_message_iterator_class_set_seek_ns_from_origin_methods(
1139 bt_message_iterator_class
*message_iterator_class
,
1140 bt_message_iterator_class_seek_ns_from_origin_method seek_method
,
1141 bt_message_iterator_class_can_seek_ns_from_origin_method can_seek_method
);
1146 @name Reference count
1152 Increments the \ref api-fund-shared-object "reference count" of
1153 the message iterator class \bt_p{message_iterator_class}.
1155 @param[in] message_iterator_class
1157 Message iterator class of which to increment the reference count.
1162 @sa bt_component_put_ref() —
1163 Decrements the reference count of a message iterator class.
1165 extern void bt_message_iterator_class_get_ref(
1166 const bt_message_iterator_class
*message_iterator_class
);
1170 Decrements the \ref api-fund-shared-object "reference count" of
1171 the message iterator class \bt_p{message_iterator_class}.
1173 @param[in] message_iterator_class
1175 Message iterator class of which to decrement the reference count.
1180 @sa bt_component_get_ref() —
1181 Increments the reference count of a message iterator class.
1183 extern void bt_message_iterator_class_put_ref(
1184 const bt_message_iterator_class
*message_iterator_class
);
1188 Decrements the reference count of the message iterator class
1189 \bt_p{_message_iterator_class}, and then sets
1190 \bt_p{_message_iterator_class} to \c NULL.
1192 @param _message_iterator_class
1194 Message iterator class of which to decrement the reference count.
1196 Can contain \c NULL.
1199 @bt_pre_assign_expr{_message_iterator_class}
1201 #define BT_MESSAGE_ITERATOR_CLASS_PUT_REF_AND_RESET(_message_iterator_class) \
1203 bt_message_iterator_class_put_ref(_message_iterator_class); \
1204 (_message_iterator_class) = NULL; \
1209 Decrements the reference count of the message iterator class \bt_p{_dst},
1210 sets \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src}
1213 This macro effectively moves a message iterator class reference from the
1214 expression \bt_p{_src} to the expression \bt_p{_dst}, putting the
1215 existing \bt_p{_dst} reference.
1219 Destination expression.
1221 Can contain \c NULL.
1227 Can contain \c NULL.
1230 @bt_pre_assign_expr{_dst}
1231 @bt_pre_assign_expr{_src}
1233 #define BT_MESSAGE_ITERATOR_CLASS_MOVE_MOVE_REF(_dst, _src) \
1235 bt_message_iterator_class_put_ref(_dst); \
1248 #endif /* BABELTRACE2_GRAPH_MESSAGE_ITERATOR_CLASS_H */