Message iterator class

Detailed Description

Message iterator class.

A message iterator class is the class of a message iterator.

Source component classes and filter component classes contain a message iterator class. For such a component class, its message iterator class is the class of any message iterator created for any output port of the component class's instances (components).

Therefore, the only thing you can do with a message iterator class is to pass it to bt_component_class_source_create() or bt_component_class_filter_create() to set it as the created component class's message iterator class.

A message iterator class has methods. This module essentially offers:

• Message iterator class method type definitions.
• A message iterator class creation function, to which you must pass the mandatory "next" method.
• Functions to set optional message iterator class methods.

A message iterator class method is a user function. All message iterator class methods operate on an instance (a message iterator). The type of the method's first parameter is bt_self_message_iterator. This is similar to an instance method in Python (where the instance object name is generally self) or a member function in C++ (where the instance pointer is named this), for example.

See Methods to learn more about the different types of message iterator class methods.

A message iterator class is a shared object: get a new reference with bt_message_iterator_class_get_ref() and put an existing reference with bt_message_iterator_class_put_ref().

Some library functions freeze message iterator classes on success. The documentation of those functions indicate this postcondition.

The type of a message iterator class is bt_message_iterator_class.

Create a message iterator class with bt_message_iterator_class_create(). When you call this function, you must pass the message iterator class's mandatory "next" method.

Methods

To learn when exactly the methods below are called, see Trace processing graph life cycle and Message iterator.

The available message iterator class methods to implement are:

Name	Requirement	C type
Can seek beginning?	Optional	bt_message_iterator_class_can_seek_beginning_method
Can seek ns from origin?	Optional	bt_message_iterator_class_can_seek_ns_from_origin_method
Finalize	Optional	bt_message_iterator_class_finalize_method
Initialize	Optional	bt_message_iterator_class_initialize_method
Next	Mandatory	bt_message_iterator_class_next_method
Seek beginning	Optional	bt_message_iterator_class_seek_beginning_method
Seek ns from origin	Optional	bt_message_iterator_class_seek_ns_from_origin_method

Can seek beginning?

Called to check whether or not your message iterator can currently seek its beginning (the very first message of its sequence).

There are some use cases in which a message iterator cannot always seek its beginning, depending on its state.

If you don't implement this method, then, if you implement the seek beginning method, the library assumes that your message iterator can always seek its beginning.

The message iterator of a filter component will typically consider the beginning seeking capability of its own upstream message iterator(s) (with bt_message_iterator_can_seek_beginning()) in this method's implementation.

If you need to block the thread to compute whether or not your message iterator can seek its beginning, you can instead report to try again later to the caller by returning BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_BEGINNING_METHOD_STATUS_AGAIN.

Set this optional method with the can_seek_method parameter of bt_message_iterator_class_set_seek_beginning_methods().

Can seek ns from origin?

Called to check whether or not your message iterator can currently seek a message occuring at or after a specific time given in nanoseconds from its clock class origin.

There are some use cases in which a message iterator cannot always seek some specific time, depending on its state.

Within this method, your receive the specific time to seek as the ns_from_origin parameter. You don't receive any clock class: the method operates at the nanosecond from some origin level and it is left to the implementation to decide whether or not the message iterator can seek this point in time.

If you don't implement this method, then, if you implement the seek ns from origin method, the library assumes that your message iterator can always seek any message occuring at or after any time.

The message iterator of a filter component will typically consider the time seeking capability of its own upstream message iterator(s) (with bt_message_iterator_can_seek_ns_from_origin()) in this method's implementation.

If you need to block the thread to compute whether or not your message iterator can seek a message occuring at or after a given time, you can instead report to try again later to the caller by returning BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_AGAIN.

Set this optional method with the can_seek_method parameter of bt_message_iterator_class_set_seek_ns_from_origin_methods().

Finalize

Called to finalize your message iterator, that is, to let you destroy/free/finalize any user data you have (retrieved with bt_self_message_iterator_get_data()).

The Babeltrace 2 library does not specify exactly when this method is called, but guarantees that it's called before the message iterator is destroyed.

The library guarantees that all message iterators are destroyed before their component is destroyed.

This method is not called if the message iterator's initialization method previously returned an error status code.

Set this optional method with bt_message_iterator_class_set_finalize_method().

Initialize

Called within bt_message_iterator_create_from_message_iterator() or bt_message_iterator_create_from_sink_component() to initialize your message iterator.

Within this method, you can access your component's user data by first borrowing it with bt_self_message_iterator_borrow_component() and then using bt_self_component_get_data().

For the message iterator of a filter component, this method is typically where you create an upstream message iterator with bt_message_iterator_create_from_message_iterator().

You can create user data and set it as the self message iterator's user data with bt_self_message_iterator_set_data().

If you return BT_MESSAGE_ITERATOR_CLASS_INITIALIZE_METHOD_STATUS_OK from this method, then your message iterator's finalization method will be called, if it exists, when your message iterator is finalized.

This method receives a message iterator configuration object (bt_self_message_iterator_configuration type). As of Babeltrace 2.0, you can use bt_self_message_iterator_configuration_set_can_seek_forward() during, and only during, this method's execution to set whether or not your message iterator can seek forward.

For a message iterator to be able to seek forward, all the messages of its message sequence must have some clock snapshot. bt_message_iterator_seek_ns_from_origin() uses this configuration option and the beginning seeking capability of a message iterator (bt_message_iterator_can_seek_beginning()) to make it seek a message occuring at or after a specific time even when the message iterator does not implement the seek ns from origin method.

Set this optional method with bt_message_iterator_class_set_initialize_method().

"Next" (get next messages)

Called within bt_message_iterator_next() to "advance" your message iterator, that is, to get its next messages.

Within this method, you receive:

• An array of messages to fill (messages parameter) with your message iterator's next messages, if any.

  Note that this array needs its own message references. In other words, if you have a message reference and you put this message into the array without calling bt_message_get_ref(), then you just moved the message reference to the array (the array owns the message now).

• The capacity of the message array (capacity parameter), that is, the maximum number of messages you can put in it.
• A message count output parameter (count) which, on success, you must set to the number of messages you put in the message array.

If you return BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_OK from this method, then you must put at least one message in the message array. In other words, *count must be greater than zero.

You must honour the message sequence rules when you put new or existing messages in the message array.

If you return BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_OK, then all the messages of the message array become frozen.

This method typically:

For a source component's message iterator

Creates brand new messages to represent one or more input traces.

For a filter component's message iterator

Gets one message batch from one (or more) upstream message iterator and filters them.

For a source component's message iterator, you are free to create as many as capacity messages. For a filter component's message iterator, you are free to get more than one batch of messages from upstream message iterators if needed. However, in both cases, keep in mind that the Babeltrace 2 project recommends that this method executes fast enough so as not to block an interactive application running on the same thread.

During what you consider to be a long, blocking operation, the project recommends that you periodically check whether or not you are interrupted with bt_self_message_iterator_is_interrupted(). When you are, you can return either BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_AGAIN or BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_ERROR, depending on your capability to continue the current operation later.

If you need to block the thread to insert messages into the message array, you can instead report to try again later to the caller by returning BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_AGAIN. When you return this status code, you must not put any message into the message array.

If your message iterator's iteration process is done (you have no more messages to emit), then return BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_END. When you return this status code, you must not put any message into the message array.

Set this mandatory method at message iterator class creation time with bt_message_iterator_class_create().

Seek beginning

Called within bt_message_iterator_seek_beginning() to make your message iterator seek its beginning, that is, the very first message of its sequence.

The sequence of messages of a given message iterator must always be the same, in that, if your message iterator emitted the messages A, B, C, D, and E, and then this "seek beginning" method is called successfully (it returns BT_MESSAGE_ITERATOR_CLASS_SEEK_BEGINNING_METHOD_STATUS_OK), then your message iterator's next messages (the next time your "next" method is called) must be A, B, C, D, and E.

The Babeltrace 2 project recommends that this method executes fast enough so as not to block an interactive application running on the same thread.

During what you consider to be a long, blocking operation, the project recommends that you periodically check whether or not you are interrupted with bt_self_message_iterator_is_interrupted(). When you are, you can return either BT_MESSAGE_ITERATOR_CLASS_SEEK_BEGINNING_METHOD_STATUS_AGAIN or BT_MESSAGE_ITERATOR_CLASS_SEEK_BEGINNING_METHOD_STATUS_ERROR, depending on your capability to continue the current operation later.

If you need to block the thread to make your message iterator seek its beginning, you can instead report to try again later to the caller by returning BT_MESSAGE_ITERATOR_CLASS_SEEK_BEGINNING_METHOD_STATUS_AGAIN.

The optional can seek beginning? method can indicate whether or not your message iterator can currently seek its beginning. If you implement it, the library guarantees that it is called and returns BT_TRUE before this "seek beginning" is called, without any other message iterator methods being called in between.

Set this optional method with the seek_method parameter of bt_message_iterator_class_set_seek_beginning_methods().

Seek ns from origin

Called within bt_message_iterator_seek_ns_from_origin() to make your message iterator seek a message occuring at or after a specific time given in nanoseconds from its clock class origin.

Within this method, your receive the specific time to seek as the ns_from_origin parameter. You don't receive any clock class: the method operates at the nanosecond from some origin level and it is left to the implementation to seek a message having at least this time while still honouring the message sequence rules the next time your "next" method is called.

If you return BT_MESSAGE_ITERATOR_CLASS_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_OK from this method, then the next time your "next" method is called:

• For each "active" stream at the seeked time point, you must emit a stream beginning message for this stream before you emit any other message for this stream.

  The stream beginning message must have a default clock snapshot which corresponds to the seeked time point.

• For each "active" packet at the seeked time point, you must emit a packet beginning message for this packet before you emit any other message for this packet.

  The packet beginning message must have a default clock snapshot which corresponds to the seeked time point.

The Babeltrace 2 project recommends that this method executes fast enough so as not to block an interactive application running on the same thread.

During what you consider to be a long, blocking operation, the project recommends that you periodically check whether or not you are interrupted with bt_self_message_iterator_is_interrupted(). When you are, you can return either BT_MESSAGE_ITERATOR_CLASS_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_AGAIN or BT_MESSAGE_ITERATOR_CLASS_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_ERROR, depending on your capability to continue the current operation later.

If you need to block the thread to make your message iterator seek a message occuring at or after a given time, you can instead report to try again later to the caller by returning BT_MESSAGE_ITERATOR_CLASS_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_AGAIN.

The optional can seek ns from origin? method can indicate whether or not your message iterator can currently seek a specific time. If you implement it, the library guarantees that it is called and returns BT_TRUE before this "seek ns from origin" is called, without any other message iterator methods being called in between.

Set this optional method with the seek_method parameter of bt_message_iterator_class_set_seek_ns_from_origin_methods().

Within any method, you can access the message iterator's component's configured logging level by first upcasting the self component to the bt_component type with bt_self_component_as_component(), and then with bt_component_get_logging_level().

Modules
	Self message iterator
	Private view of a message iterator for methods.

Type
typedef struct bt_message_iterator_class	bt_message_iterator_class
	Message iterator class.

Method types
enum	bt_message_iterator_class_can_seek_beginning_method_status {   BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_BEGINNING_METHOD_STATUS_OK,   BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_BEGINNING_METHOD_STATUS_AGAIN,   BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_BEGINNING_METHOD_STATUS_MEMORY_ERROR,   BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_BEGINNING_METHOD_STATUS_ERROR }
	Status codes for bt_message_iterator_class_can_seek_beginning_method. More...
enum	bt_message_iterator_class_can_seek_ns_from_origin_method_status {   BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_OK,   BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_AGAIN,   BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_MEMORY_ERROR,   BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_ERROR }
	Status codes for bt_message_iterator_class_can_seek_ns_from_origin_method. More...
enum	bt_message_iterator_class_initialize_method_status {   BT_MESSAGE_ITERATOR_CLASS_INITIALIZE_METHOD_STATUS_OK,   BT_MESSAGE_ITERATOR_CLASS_INITIALIZE_METHOD_STATUS_MEMORY_ERROR,   BT_MESSAGE_ITERATOR_CLASS_INITIALIZE_METHOD_STATUS_ERROR }
	Status codes for bt_message_iterator_class_initialize_method. More...
enum	bt_message_iterator_class_next_method_status {   BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_OK,   BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_END,   BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_AGAIN,   BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_MEMORY_ERROR,   BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_ERROR }
	Status codes for bt_message_iterator_class_next_method. More...
enum	bt_message_iterator_class_seek_beginning_method_status {   BT_MESSAGE_ITERATOR_CLASS_SEEK_BEGINNING_METHOD_STATUS_OK,   BT_MESSAGE_ITERATOR_CLASS_SEEK_BEGINNING_METHOD_STATUS_AGAIN,   BT_MESSAGE_ITERATOR_CLASS_SEEK_BEGINNING_METHOD_STATUS_MEMORY_ERROR,   BT_MESSAGE_ITERATOR_CLASS_SEEK_BEGINNING_METHOD_STATUS_ERROR }
	Status codes for bt_message_iterator_class_seek_beginning_method. More...
enum	bt_message_iterator_class_seek_ns_from_origin_method_status {   BT_MESSAGE_ITERATOR_CLASS_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_OK,   BT_MESSAGE_ITERATOR_CLASS_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_AGAIN,   BT_MESSAGE_ITERATOR_CLASS_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_MEMORY_ERROR,   BT_MESSAGE_ITERATOR_CLASS_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_ERROR }
	Status codes for bt_message_iterator_class_seek_ns_from_origin_method. More...
typedef enum bt_message_iterator_class_can_seek_beginning_method_status	bt_message_iterator_class_can_seek_beginning_method_status
	Status codes for bt_message_iterator_class_can_seek_beginning_method.
typedef bt_message_iterator_class_can_seek_beginning_method_status(*	bt_message_iterator_class_can_seek_beginning_method) (bt_self_message_iterator *self_message_iterator, bt_bool *can_seek_beginning)
	Message iterator "can seek beginning?" method. More...
typedef enum bt_message_iterator_class_can_seek_ns_from_origin_method_status	bt_message_iterator_class_can_seek_ns_from_origin_method_status
	Status codes for bt_message_iterator_class_can_seek_ns_from_origin_method.
typedef bt_message_iterator_class_can_seek_ns_from_origin_method_status(*	bt_message_iterator_class_can_seek_ns_from_origin_method) (bt_self_message_iterator *self_message_iterator, int64_t ns_from_origin, bt_bool *can_seek_ns_from_origin)
	Message iterator "can seek ns from origin?" method. More...
typedef void(*	bt_message_iterator_class_finalize_method) (bt_self_message_iterator *self_message_iterator)
	Message iterator finalization method. More...
typedef enum bt_message_iterator_class_initialize_method_status	bt_message_iterator_class_initialize_method_status
	Status codes for bt_message_iterator_class_initialize_method.
typedef bt_message_iterator_class_initialize_method_status(*	bt_message_iterator_class_initialize_method) (bt_self_message_iterator *self_message_iterator, bt_self_message_iterator_configuration *configuration, bt_self_component_port_output *port)
	Message iterator initialization method. More...
typedef enum bt_message_iterator_class_next_method_status	bt_message_iterator_class_next_method_status
	Status codes for bt_message_iterator_class_next_method.
typedef bt_message_iterator_class_next_method_status(*	bt_message_iterator_class_next_method) (bt_self_message_iterator *self_message_iterator, bt_message_array_const messages, uint64_t capacity, uint64_t *count)
	Message iterator "next" (get next messages) method. More...
typedef enum bt_message_iterator_class_seek_beginning_method_status	bt_message_iterator_class_seek_beginning_method_status
	Status codes for bt_message_iterator_class_seek_beginning_method.
typedef bt_message_iterator_class_seek_beginning_method_status(*	bt_message_iterator_class_seek_beginning_method) (bt_self_message_iterator *self_message_iterator)
	Message iterator "seek beginning" method. More...
typedef enum bt_message_iterator_class_seek_ns_from_origin_method_status	bt_message_iterator_class_seek_ns_from_origin_method_status
	Status codes for bt_message_iterator_class_seek_ns_from_origin_method.
typedef bt_message_iterator_class_seek_ns_from_origin_method_status(*	bt_message_iterator_class_seek_ns_from_origin_method) (bt_self_message_iterator *self_message_iterator, int64_t ns_from_origin)
	Message iterator "seek ns from origin" method. More...

Creation
bt_message_iterator_class *	bt_message_iterator_class_create (bt_message_iterator_class_next_method next_method)
	Creates a message iterator class having the "next" method method next_method. More...

Method setting
enum	bt_message_iterator_class_set_method_status { BT_MESSAGE_ITERATOR_CLASS_SET_METHOD_STATUS_OK }
	Status code for the bt_message_iterator_class_set_*_method() functions. More...
typedef enum bt_message_iterator_class_set_method_status	bt_message_iterator_class_set_method_status
	Status code for the bt_message_iterator_class_set_*_method() functions.
bt_message_iterator_class_set_method_status	bt_message_iterator_class_set_finalize_method (bt_message_iterator_class *message_iterator_class, bt_message_iterator_class_finalize_method method)
	Sets the optional finalization method of the message iterator class message_iterator_class to method. More...
bt_message_iterator_class_set_method_status	bt_message_iterator_class_set_initialize_method (bt_message_iterator_class *message_iterator_class, bt_message_iterator_class_initialize_method method)
	Sets the optional initialization method of the message iterator class message_iterator_class to method. More...
bt_message_iterator_class_set_method_status	bt_message_iterator_class_set_seek_beginning_methods (bt_message_iterator_class *message_iterator_class, bt_message_iterator_class_seek_beginning_method seek_method, bt_message_iterator_class_can_seek_beginning_method can_seek_method)
	Sets the optional "seek beginning" and "can seek beginning?" methods of the message iterator class message_iterator_class to seek_method and can_seek_method. More...
bt_message_iterator_class_set_method_status	bt_message_iterator_class_set_seek_ns_from_origin_methods (bt_message_iterator_class *message_iterator_class, bt_message_iterator_class_seek_ns_from_origin_method seek_method, bt_message_iterator_class_can_seek_ns_from_origin_method can_seek_method)
	Sets the optional "seek ns from origin" and "can seek ns from origin?" methods of the message iterator class message_iterator_class to seek_method and can_seek_method. More...

Reference count
void	bt_message_iterator_class_get_ref (const bt_message_iterator_class *message_iterator_class)
	Increments the reference count of the message iterator class message_iterator_class. More...
void	bt_message_iterator_class_put_ref (const bt_message_iterator_class *message_iterator_class)
	Decrements the reference count of the message iterator class message_iterator_class. More...
#define	BT_MESSAGE_ITERATOR_CLASS_PUT_REF_AND_RESET(_message_iterator_class)
	Decrements the reference count of the message iterator class _message_iterator_class, and then sets _message_iterator_class to NULL. More...
#define	BT_MESSAGE_ITERATOR_CLASS_MOVE_MOVE_REF(_dst, _src)
	Decrements the reference count of the message iterator class _dst, sets _dst to _src, and then sets _src to NULL. More...

Typedef Documentation

bt_message_iterator_class_can_seek_beginning_method

typedef bt_message_iterator_class_can_seek_beginning_method_status(* bt_message_iterator_class_can_seek_beginning_method) (bt_self_message_iterator *self_message_iterator, bt_bool *can_seek_beginning)

Message iterator "can seek beginning?" method.

See the can seek beginning? method.

Parameters

[in]	self_message_iterator	Message iterator instance.
[out]	can_seek_beginning	On success, *can_seek_beginning is BT_TRUE if self_message_iterator can currently seek its beginning.

Return values

BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_BEGINNING_METHOD_STATUS_OK	Success.
BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_BEGINNING_METHOD_STATUS_AGAIN	Try again.
BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_BEGINNING_METHOD_STATUS_MEMORY_ERROR	Out of memory.
BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_BEGINNING_METHOD_STATUS_ERROR	User error.

Precondition

self_message_iterator is not NULL.

can_seek_beginning is not NULL.

Postcondition

On success, *can_seek_beginning is set.

See also

bt_message_iterator_class_set_seek_beginning_methods() — Sets the "seek beginning" and "can seek beginning?" methods of a message iterator class.

bt_message_iterator_class_can_seek_ns_from_origin_method

typedef bt_message_iterator_class_can_seek_ns_from_origin_method_status(* bt_message_iterator_class_can_seek_ns_from_origin_method) (bt_self_message_iterator *self_message_iterator, int64_t ns_from_origin, bt_bool *can_seek_ns_from_origin)

Message iterator "can seek ns from origin?" method.

See the can seek ns from origin? method.

Parameters

[in]	self_message_iterator	Message iterator instance.
[in]	ns_from_origin	Requested time point to seek.
[out]	can_seek_ns_from_origin	On success, set *can_seek_ns_from_origin to BT_TRUE if self_message_iterator can currently seek a message occuring at or after ns_from_origin nanoseconds from its clock class origin.

Return values

BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_OK	Success.
BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_AGAIN	Try again.
BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_MEMORY_ERROR	Out of memory.
BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_ERROR	User error.

Precondition

self_message_iterator is not NULL.

can_seek_ns_from_origin is not NULL.

Postcondition

On success, *can_seek_ns_from_origin is set.

See also

bt_message_iterator_class_set_seek_ns_from_origin_methods() — Sets the "seek ns from origin" and "can seek ns from origin?" methods of a message iterator class.

bt_message_iterator_class_finalize_method

typedef void(* bt_message_iterator_class_finalize_method) (bt_self_message_iterator *self_message_iterator)

Message iterator finalization method.

See the finalize method.

Parameters

[in]

self_message_iterator

Message iterator instance.

Precondition

self_message_iterator is not NULL.

Postcondition

The current thread has no error.

See also

bt_message_iterator_class_set_finalize_method() — Sets the finalization method of a message iterator class.

bt_message_iterator_class_initialize_method

typedef bt_message_iterator_class_initialize_method_status(* bt_message_iterator_class_initialize_method) (bt_self_message_iterator *self_message_iterator, bt_self_message_iterator_configuration *configuration, bt_self_component_port_output *port)

Message iterator initialization method.

See the initialize method.

Parameters

[in]	self_message_iterator	Message iterator instance.
[in]	configuration	Message iterator's configuration.
[in]	port	Output port for which self_message_iterator was created.

Return values

BT_MESSAGE_ITERATOR_CLASS_INITIALIZE_METHOD_STATUS_OK	Success.
BT_MESSAGE_ITERATOR_CLASS_INITIALIZE_METHOD_STATUS_MEMORY_ERROR	Out of memory.
BT_MESSAGE_ITERATOR_CLASS_INITIALIZE_METHOD_STATUS_ERROR	User error.

Precondition

self_message_iterator is not NULL.

configuration is not NULL.

port is not NULL.

See also

bt_message_iterator_class_set_initialize_method() — Sets the initialization method of a message iterator class.

bt_message_iterator_class_next_method

typedef bt_message_iterator_class_next_method_status(* bt_message_iterator_class_next_method) (bt_self_message_iterator *self_message_iterator, bt_message_array_const messages, uint64_t capacity, uint64_t *count)

Message iterator "next" (get next messages) method.

See the "next" method.

If this method returns BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_OK, then all the messages of the message array become frozen.

Parameters

[in]	self_message_iterator	Message iterator instance.
[out]	messages	Message array to fill, on success, with the messages to emit. This array needs its own message references. In other words, if you have a message reference and you put this message into the array without calling bt_message_get_ref(), then you just moved the message reference to the array (the array owns the message now). The capacity of this array (maximum number of messages you can put in it) is capacity.
[in]	capacity	Capacity of the messages array (maximum number of messages you can put in it).
[out]	count	On success, *count is the number of messages you put in messages.

Return values

BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_OK	Success.
BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_END	End of iteration.
BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_AGAIN	Try again.
BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_MEMORY_ERROR	Out of memory.
BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_ERROR	User error.

Precondition

self_message_iterator is not NULL.

messages is not NULL.

capacity ≥ 1.

count is not NULL.

Postcondition

On success, messages contains *count message references as its first *count elements.

On success, the messages in messages honour the message sequence rules.

On success, for any event message in messages, its payload field, specific context field, common context field, and all their inner fields, recursively, are set.

On success, *count ≥ 1.

On success, *count ≤ capacity.

See also

bt_message_iterator_class_create() — Creates a message iterator class.

bt_message_iterator_class_seek_beginning_method

typedef bt_message_iterator_class_seek_beginning_method_status(* bt_message_iterator_class_seek_beginning_method) (bt_self_message_iterator *self_message_iterator)

Message iterator "seek beginning" method.

See the seek beginning method.

Parameters

[in]

self_message_iterator

Message iterator instance.

Return values

BT_MESSAGE_ITERATOR_CLASS_SEEK_BEGINNING_METHOD_STATUS_OK	Success.
BT_MESSAGE_ITERATOR_CLASS_SEEK_BEGINNING_METHOD_STATUS_AGAIN	Try again.
BT_MESSAGE_ITERATOR_CLASS_SEEK_BEGINNING_METHOD_STATUS_MEMORY_ERROR	Out of memory.
BT_MESSAGE_ITERATOR_CLASS_SEEK_BEGINNING_METHOD_STATUS_ERROR	User error.

Precondition

self_message_iterator is not NULL.

If self_message_iterator has a can seek beginning? method, then it was called and returned BT_TRUE before this "seek beginning" method is called, without any other method of self_message_iterator called in between.

See also

bt_message_iterator_class_set_seek_beginning_methods() — Sets the "seek beginning" and "can seek beginning?" methods of a message iterator class.

bt_message_iterator_class_seek_ns_from_origin_method

typedef bt_message_iterator_class_seek_ns_from_origin_method_status(* bt_message_iterator_class_seek_ns_from_origin_method) (bt_self_message_iterator *self_message_iterator, int64_t ns_from_origin)

Message iterator "seek ns from origin" method.

See the seek ns from origin method.

Parameters

[in]	self_message_iterator	Message iterator instance.
[in]	ns_from_origin	Time point to seek.

Return values

BT_MESSAGE_ITERATOR_CLASS_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_OK	Success.
BT_MESSAGE_ITERATOR_CLASS_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_AGAIN	Try again.
BT_MESSAGE_ITERATOR_CLASS_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_MEMORY_ERROR	Out of memory.
BT_MESSAGE_ITERATOR_CLASS_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_ERROR	User error.

Precondition

self_message_iterator is not NULL.

If self_message_iterator has a can seek ns from origin? method, then it was called and returned BT_TRUE before this "seek ns from origin" method is called, without any other method of self_message_iterator called in between.

See also

bt_message_iterator_class_set_seek_ns_from_origin_methods() — Sets the "seek ns from origin" and "can seek ns from origin?" methods of a message iterator class.

Enumeration Type Documentation

bt_message_iterator_class_can_seek_beginning_method_status

enum bt_message_iterator_class_can_seek_beginning_method_status

Status codes for bt_message_iterator_class_can_seek_beginning_method.

Enumerator
BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_BEGINNING_METHOD_STATUS_OK	Success.
BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_BEGINNING_METHOD_STATUS_AGAIN	Try again.
BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_BEGINNING_METHOD_STATUS_MEMORY_ERROR	Out of memory.
BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_BEGINNING_METHOD_STATUS_ERROR	User error.

bt_message_iterator_class_can_seek_ns_from_origin_method_status

enum bt_message_iterator_class_can_seek_ns_from_origin_method_status

Status codes for bt_message_iterator_class_can_seek_ns_from_origin_method.

Enumerator
BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_OK	Success.
BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_AGAIN	Try again.
BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_MEMORY_ERROR	Out of memory.
BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_ERROR	User error.

bt_message_iterator_class_initialize_method_status

enum bt_message_iterator_class_initialize_method_status

Status codes for bt_message_iterator_class_initialize_method.

Enumerator
BT_MESSAGE_ITERATOR_CLASS_INITIALIZE_METHOD_STATUS_OK	Success.
BT_MESSAGE_ITERATOR_CLASS_INITIALIZE_METHOD_STATUS_MEMORY_ERROR	Out of memory.
BT_MESSAGE_ITERATOR_CLASS_INITIALIZE_METHOD_STATUS_ERROR	User error.

bt_message_iterator_class_next_method_status

enum bt_message_iterator_class_next_method_status

Status codes for bt_message_iterator_class_next_method.

Enumerator
BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_OK	Success.
BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_END	End of iteration.
BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_AGAIN	Try again.
BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_MEMORY_ERROR	Out of memory.
BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_ERROR	User error.

bt_message_iterator_class_seek_beginning_method_status

enum bt_message_iterator_class_seek_beginning_method_status

Status codes for bt_message_iterator_class_seek_beginning_method.

Enumerator
BT_MESSAGE_ITERATOR_CLASS_SEEK_BEGINNING_METHOD_STATUS_OK	Success.
BT_MESSAGE_ITERATOR_CLASS_SEEK_BEGINNING_METHOD_STATUS_AGAIN	Try again.
BT_MESSAGE_ITERATOR_CLASS_SEEK_BEGINNING_METHOD_STATUS_MEMORY_ERROR	Out of memory.
BT_MESSAGE_ITERATOR_CLASS_SEEK_BEGINNING_METHOD_STATUS_ERROR	User error.

bt_message_iterator_class_seek_ns_from_origin_method_status

enum bt_message_iterator_class_seek_ns_from_origin_method_status

Status codes for bt_message_iterator_class_seek_ns_from_origin_method.

Enumerator
BT_MESSAGE_ITERATOR_CLASS_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_OK	Success.
BT_MESSAGE_ITERATOR_CLASS_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_AGAIN	Try again.
BT_MESSAGE_ITERATOR_CLASS_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_MEMORY_ERROR	Out of memory.
BT_MESSAGE_ITERATOR_CLASS_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_ERROR	User error.

bt_message_iterator_class_set_method_status

enum bt_message_iterator_class_set_method_status

Status code for the bt_message_iterator_class_set_*_method() functions.

Enumerator
BT_MESSAGE_ITERATOR_CLASS_SET_METHOD_STATUS_OK	Success.

Macro Definition Documentation

BT_MESSAGE_ITERATOR_CLASS_PUT_REF_AND_RESET

#define BT_MESSAGE_ITERATOR_CLASS_PUT_REF_AND_RESET

(

_message_iterator_class

)

Decrements the reference count of the message iterator class _message_iterator_class, and then sets _message_iterator_class to NULL.

Parameters

_message_iterator_class

Message iterator class of which to decrement the reference count. Can contain NULL.

Precondition

_message_iterator_class is an assignable expression.

BT_MESSAGE_ITERATOR_CLASS_MOVE_MOVE_REF

#define BT_MESSAGE_ITERATOR_CLASS_MOVE_MOVE_REF	(		_dst,
			_src
	)

Decrements the reference count of the message iterator class _dst, sets _dst to _src, and then sets _src to NULL.

This macro effectively moves a message iterator class reference from the expression _src to the expression _dst, putting the existing _dst reference.

Parameters

_dst	Destination expression. Can contain NULL.
_src	Source expression. Can contain NULL.

Precondition

_dst is an assignable expression.

_src is an assignable expression.

Function Documentation

bt_message_iterator_class_create()

bt_message_iterator_class* bt_message_iterator_class_create

(

bt_message_iterator_class_next_method

next_method

)

Creates a message iterator class having the "next" method method next_method.

Parameters

[in]

next_method

"Next" method of the message iterator class to create.

Returns

New message iterator class reference, or NULL on memory error.

Precondition

next_method is not NULL.

bt_message_iterator_class_set_finalize_method()

bt_message_iterator_class_set_method_status bt_message_iterator_class_set_finalize_method	(	bt_message_iterator_class *	message_iterator_class,
		bt_message_iterator_class_finalize_method	method
	)

Sets the optional finalization method of the message iterator class message_iterator_class to method.

See the finalize method.

Parameters

[in]	message_iterator_class	Message iterator class of which to set the finalization method to method.
[in]	method	New finalization method of message_iterator_class.

Return values

BT_MESSAGE_ITERATOR_CLASS_SET_METHOD_STATUS_OK

Success.

Precondition

message_iterator_class is not NULL.

message_iterator_class is not frozen.

method is not NULL.

bt_message_iterator_class_set_initialize_method()

bt_message_iterator_class_set_method_status bt_message_iterator_class_set_initialize_method	(	bt_message_iterator_class *	message_iterator_class,
		bt_message_iterator_class_initialize_method	method
	)

Sets the optional initialization method of the message iterator class message_iterator_class to method.

See the initialize method.

Parameters

[in]	message_iterator_class	Message iterator class of which to set the initialization method to method.
[in]	method	New initialization method of message_iterator_class.

Return values

BT_MESSAGE_ITERATOR_CLASS_SET_METHOD_STATUS_OK

Success.

Precondition

message_iterator_class is not NULL.

message_iterator_class is not frozen.

method is not NULL.

bt_message_iterator_class_set_seek_beginning_methods()

bt_message_iterator_class_set_method_status bt_message_iterator_class_set_seek_beginning_methods	(	bt_message_iterator_class *	message_iterator_class,
		bt_message_iterator_class_seek_beginning_method	seek_method,
		bt_message_iterator_class_can_seek_beginning_method	can_seek_method
	)

Sets the optional "seek beginning" and "can seek beginning?" methods of the message iterator class message_iterator_class to seek_method and can_seek_method.

See the seek beginning and can seek beginning? methods.

Parameters

[in]	message_iterator_class	Message iterator class of which to set the "seek beginning" and "can seek beginning?" methods.
[in]	seek_method	New "seek beginning" method of message_iterator_class.
[in]	can_seek_method	New "can seek beginning?" method of message_iterator_class. Can be NULL, in which case it is equivalent to setting a method which always returns BT_TRUE.

Return values

BT_MESSAGE_ITERATOR_CLASS_SET_METHOD_STATUS_OK

Success.

Precondition

message_iterator_class is not NULL.

message_iterator_class is not frozen.

seek_method is not NULL.

bt_message_iterator_class_set_seek_ns_from_origin_methods()

bt_message_iterator_class_set_method_status bt_message_iterator_class_set_seek_ns_from_origin_methods	(	bt_message_iterator_class *	message_iterator_class,
		bt_message_iterator_class_seek_ns_from_origin_method	seek_method,
		bt_message_iterator_class_can_seek_ns_from_origin_method	can_seek_method
	)

Sets the optional "seek ns from origin" and "can seek ns from origin?" methods of the message iterator class message_iterator_class to seek_method and can_seek_method.

See the seek ns from origin and can seek ns from origin? methods.

Parameters

[in]	message_iterator_class	Message iterator class of which to set the "seek ns from origin" and "can seek ns from origin?" methods.
[in]	seek_method	New "seek ns from origin" method of message_iterator_class.
[in]	can_seek_method	New "can seek ns from origin?" method of message_iterator_class. Can be NULL, in which case it is equivalent to setting a method which always returns BT_TRUE.

Return values

BT_MESSAGE_ITERATOR_CLASS_SET_METHOD_STATUS_OK

Success.

Precondition

message_iterator_class is not NULL.

message_iterator_class is not frozen.

seek_method is not NULL.

bt_message_iterator_class_get_ref()

void bt_message_iterator_class_get_ref

(

const bt_message_iterator_class *

message_iterator_class

)

Increments the reference count of the message iterator class message_iterator_class.

Parameters

[in]

message_iterator_class

Message iterator class of which to increment the reference count. Can be NULL.

See also

bt_component_put_ref() — Decrements the reference count of a message iterator class.

bt_message_iterator_class_put_ref()

void bt_message_iterator_class_put_ref

(

const bt_message_iterator_class *

message_iterator_class

)

Decrements the reference count of the message iterator class message_iterator_class.

Parameters

[in]

message_iterator_class

Message iterator class of which to decrement the reference count. Can be NULL.

See also

bt_component_get_ref() — Increments the reference count of a message iterator class.