Message iterator

Detailed Description

Iterator of a message sequence.

A message iterator iterates a sequence of messages.

A message iterator is the Babeltrace 2 mechanism for the components of a trace processing graph to exchange information. This information takes the form of a sequence of individual messages which contain trace data (events, for example).

A message iterator is a message iterator class instance. Because a message iterator class is part of a source component class or filter component class, a message iterator is part of a source component or filter component. Borrow the component of a message iterator with bt_message_iterator_borrow_component().

A message iterator is a shared object: get a new reference with bt_component_get_ref() and put an existing reference with bt_component_put_ref().

The type of a message iterator is bt_message_iterator.

There are two contexts from which you can create a message iterator:

From another message iterator

This is the case for the message iterator of a filter component.

Use bt_message_iterator_create_from_message_iterator().

You can call this function from any message iterator method except the finalization method.

From a sink component

Use bt_message_iterator_create_from_sink_component().

You can call this function from a sink component method once the trace processing graph which contains the component is configured, that is:

• Graph is configured method (typical).
• Consume method.

When you call one of the creation functions above, you pass an input port on which to create the message iterator.

You can create more than one message iterator on a given connected input port. The connections between ports in a trace processing graph establish which components and message iterators can create message iterators of other components. Then:

• Any sink component is free to create one or more message iterators on any of its connected input ports.
• Any message iterator is free to create one or more message iterators on any of the connected input ports of its component.

The following illustration shows a very simple use case where the consuming method of a sink component uses a single filter component message iterator which itself uses a single source component message iterator:

Many message iterator relations are possible, for example:

Operations

Once you have created a message iterator, there are three possible operations:

Get the next messages of the message iterator.

This operation returns a batch of the next messages of the message iterator considering its current state.

This operation returns a batch of messages instead of a single message for performance reasons.

This operation is said to advance the message iterator.

Get the next messages of a message iterator with bt_message_iterator_next().

Make the message iterator seek its beginning

This operation resets the position of the message iterator to the beginning of its message sequence.

If the operation is successful, then the next call to bt_message_iterator_next() returns the first messages of the sequence of the message iterator.

If bt_message_iterator_seek_ns_from_origin() returns something else than BT_MESSAGE_ITERATOR_SEEK_BEGINNING_STATUS_OK, then you cannot call bt_message_iterator_next() afterwards. In that case, you can only call bt_message_iterator_seek_beginning() again or bt_message_iterator_seek_ns_from_origin().

Before you call bt_message_iterator_seek_beginning() to make the message iterator seek its beginning, check if it can currently do it with bt_message_iterator_can_seek_beginning().

Make the message iterator seek a message occurring at or after a given time (in nanoseconds) from its clock class origin

This operation changes the position of the message iterator within its sequence so that the next call to bt_message_iterator_next() returns messages which occur at or after a given time (in nanoseconds) from its clock class origin.

When you call bt_message_iterator_seek_ns_from_origin() to perform the operation, your pass the specific time to seek as the ns_from_origin parameter. You don't pass any clock class: the function operates at the nanosecond from some origin level and it's left to the implementation of the message iterator to seek a message having at least this time.

If the requested time point is after the last message of the sequence of the message iterator, then the next call to bt_message_iterator_next() returns BT_MESSAGE_ITERATOR_NEXT_STATUS_END.

If bt_message_iterator_seek_ns_from_origin() returns something else than BT_MESSAGE_ITERATOR_SEEK_NS_FROM_ORIGIN_STATUS_OK, then you cannot call bt_message_iterator_next() afterwards. In that case, you can only call bt_message_iterator_seek_ns_from_origin() again or bt_message_iterator_seek_beginning().

Before you call bt_message_iterator_seek_ns_from_origin() to make the message iterator seek a specific point in time, check if it can currently do it with bt_message_iterator_can_seek_ns_from_origin().

Creation
enum	bt_message_iterator_create_from_message_iterator_status {   BT_MESSAGE_ITERATOR_CREATE_FROM_MESSAGE_ITERATOR_STATUS_OK ,   BT_MESSAGE_ITERATOR_CREATE_FROM_MESSAGE_ITERATOR_STATUS_MEMORY_ERROR ,   BT_MESSAGE_ITERATOR_CREATE_FROM_MESSAGE_ITERATOR_STATUS_ERROR }
	Status code for bt_message_iterator_create_from_message_iterator(). More...
enum	bt_message_iterator_create_from_sink_component_status {   BT_MESSAGE_ITERATOR_CREATE_FROM_SINK_COMPONENT_STATUS_OK ,   BT_MESSAGE_ITERATOR_CREATE_FROM_SINK_COMPONENT_STATUS_MEMORY_ERROR ,   BT_MESSAGE_ITERATOR_CREATE_FROM_SINK_COMPONENT_STATUS_ERROR }
	Status code for bt_message_iterator_create_from_sink_component(). More...
typedef enum bt_message_iterator_create_from_message_iterator_status	bt_message_iterator_create_from_message_iterator_status
	Status code for bt_message_iterator_create_from_message_iterator().
typedef enum bt_message_iterator_create_from_sink_component_status	bt_message_iterator_create_from_sink_component_status
	Status code for bt_message_iterator_create_from_sink_component().
bt_message_iterator_create_from_message_iterator_status	bt_message_iterator_create_from_message_iterator (bt_self_message_iterator *self_message_iterator, bt_self_component_port_input *port, bt_message_iterator **message_iterator)
	Creates a message iterator on the input port port from another message iterator self_message_iterator, and sets *message_iterator to the resulting message iterator.
bt_message_iterator_create_from_sink_component_status	bt_message_iterator_create_from_sink_component (bt_self_component_sink *self_component_sink, bt_self_component_port_input *port, bt_message_iterator **message_iterator)
	Creates a message iterator on the input port port from the sink component self_component_sink, and sets *message_iterator to the resulting message iterator.

"Next" operation (get next messages)
enum	bt_message_iterator_next_status {   BT_MESSAGE_ITERATOR_NEXT_STATUS_OK ,   BT_MESSAGE_ITERATOR_NEXT_STATUS_END ,   BT_MESSAGE_ITERATOR_NEXT_STATUS_AGAIN ,   BT_MESSAGE_ITERATOR_NEXT_STATUS_MEMORY_ERROR ,   BT_MESSAGE_ITERATOR_NEXT_STATUS_ERROR }
	Status code for bt_message_iterator_next(). More...
typedef enum bt_message_iterator_next_status	bt_message_iterator_next_status
	Status code for bt_message_iterator_next().
bt_message_iterator_next_status	bt_message_iterator_next (bt_message_iterator *message_iterator, bt_message_array_const *messages, uint64_t *count)
	Returns the next messages of the message iterator message_iterator into the *messages array of size *count, effectively advancing message_iterator.

Seeking
enum	bt_message_iterator_can_seek_beginning_status {   BT_MESSAGE_ITERATOR_CAN_SEEK_BEGINNING_STATUS_OK ,   BT_MESSAGE_ITERATOR_CAN_SEEK_BEGINNING_STATUS_AGAIN ,   BT_MESSAGE_ITERATOR_CAN_SEEK_BEGINNING_STATUS_MEMORY_ERROR ,   BT_MESSAGE_ITERATOR_CAN_SEEK_BEGINNING_STATUS_ERROR }
	Status code for bt_message_iterator_can_seek_beginning(). More...
enum	bt_message_iterator_seek_beginning_status {   BT_MESSAGE_ITERATOR_SEEK_BEGINNING_STATUS_OK ,   BT_MESSAGE_ITERATOR_SEEK_BEGINNING_STATUS_AGAIN ,   BT_MESSAGE_ITERATOR_SEEK_BEGINNING_STATUS_MEMORY_ERROR ,   BT_MESSAGE_ITERATOR_SEEK_BEGINNING_STATUS_ERROR }
	Status code for bt_message_iterator_seek_beginning(). More...
enum	bt_message_iterator_can_seek_ns_from_origin_status {   BT_MESSAGE_ITERATOR_CAN_SEEK_NS_FROM_ORIGIN_STATUS_OK ,   BT_MESSAGE_ITERATOR_CAN_SEEK_NS_FROM_ORIGIN_STATUS_AGAIN ,   BT_MESSAGE_ITERATOR_CAN_SEEK_NS_FROM_ORIGIN_STATUS_MEMORY_ERROR ,   BT_MESSAGE_ITERATOR_CAN_SEEK_NS_FROM_ORIGIN_STATUS_ERROR }
	Status code for bt_message_iterator_can_seek_ns_from_origin(). More...
enum	bt_message_iterator_seek_ns_from_origin_status {   BT_MESSAGE_ITERATOR_SEEK_NS_FROM_ORIGIN_STATUS_OK ,   BT_MESSAGE_ITERATOR_SEEK_NS_FROM_ORIGIN_STATUS_AGAIN ,   BT_MESSAGE_ITERATOR_SEEK_NS_FROM_ORIGIN_STATUS_MEMORY_ERROR ,   BT_MESSAGE_ITERATOR_SEEK_NS_FROM_ORIGIN_STATUS_ERROR }
	Status code for bt_message_iterator_seek_ns_from_origin(). More...
typedef enum bt_message_iterator_can_seek_beginning_status	bt_message_iterator_can_seek_beginning_status
	Status code for bt_message_iterator_can_seek_beginning().
typedef enum bt_message_iterator_seek_beginning_status	bt_message_iterator_seek_beginning_status
	Status code for bt_message_iterator_seek_beginning().
typedef enum bt_message_iterator_can_seek_ns_from_origin_status	bt_message_iterator_can_seek_ns_from_origin_status
	Status code for bt_message_iterator_can_seek_ns_from_origin().
typedef enum bt_message_iterator_seek_ns_from_origin_status	bt_message_iterator_seek_ns_from_origin_status
	Status code for bt_message_iterator_seek_ns_from_origin().
bt_message_iterator_can_seek_beginning_status	bt_message_iterator_can_seek_beginning (bt_message_iterator *message_iterator, bt_bool *can_seek_beginning)
	Returns whether or not the message iterator message_iterator can currently seek its beginning (first message).
bt_message_iterator_seek_beginning_status	bt_message_iterator_seek_beginning (bt_message_iterator *message_iterator)
	Makes the message iterator message_iterator seek its beginning (first message).
bt_message_iterator_can_seek_ns_from_origin_status	bt_message_iterator_can_seek_ns_from_origin (bt_message_iterator *message_iterator, int64_t ns_from_origin, bt_bool *can_seek_ns_from_origin)
	Returns whether or not the message iterator message_iterator can currently seek a message occurring at or after ns_from_origin nanoseconds from its clock class origin.
bt_message_iterator_seek_ns_from_origin_status	bt_message_iterator_seek_ns_from_origin (bt_message_iterator *message_iterator, int64_t ns_from_origin)
	Makes the message iterator message_iterator seek a message occurring at or after ns_from_origin nanoseconds from its clock class origin.

Type
typedef struct bt_message_iterator	bt_message_iterator
	Message iterator.

Component access
bt_component *	bt_message_iterator_borrow_component (bt_message_iterator *message_iterator)
	Borrows the component which provides the message iterator message_iterator.

Configuration
bt_bool	bt_message_iterator_can_seek_forward (bt_message_iterator *message_iterator)
	Returns whether or not the message iterator message_iterator can seek forward.

Reference count
void	bt_message_iterator_get_ref (const bt_message_iterator *message_iterator)
	Increments the reference count of the message iterator message_iterator.
void	bt_message_iterator_put_ref (const bt_message_iterator *message_iterator)
	Decrements the reference count of the message iterator message_iterator.
#define	BT_MESSAGE_ITERATOR_PUT_REF_AND_RESET(_message_iterator)
	Decrements the reference count of the message iterator _message_iterator, and then sets _message_iterator to NULL.
#define	BT_MESSAGE_ITERATOR_MOVE_REF(_dst, _src)
	Decrements the reference count of the message iterator _dst, sets _dst to _src, and then sets _src to NULL.

Enumeration Type Documentation

bt_message_iterator_create_from_message_iterator_status

enum bt_message_iterator_create_from_message_iterator_status

Status code for bt_message_iterator_create_from_message_iterator().

Enumerator
BT_MESSAGE_ITERATOR_CREATE_FROM_MESSAGE_ITERATOR_STATUS_OK	Success.
BT_MESSAGE_ITERATOR_CREATE_FROM_MESSAGE_ITERATOR_STATUS_MEMORY_ERROR	Out of memory.
BT_MESSAGE_ITERATOR_CREATE_FROM_MESSAGE_ITERATOR_STATUS_ERROR	Other error.

bt_message_iterator_create_from_sink_component_status

enum bt_message_iterator_create_from_sink_component_status

Status code for bt_message_iterator_create_from_sink_component().

Enumerator
BT_MESSAGE_ITERATOR_CREATE_FROM_SINK_COMPONENT_STATUS_OK	Success.
BT_MESSAGE_ITERATOR_CREATE_FROM_SINK_COMPONENT_STATUS_MEMORY_ERROR	Out of memory.
BT_MESSAGE_ITERATOR_CREATE_FROM_SINK_COMPONENT_STATUS_ERROR	Other error.

bt_message_iterator_next_status

enum bt_message_iterator_next_status

Status code for bt_message_iterator_next().

Enumerator
BT_MESSAGE_ITERATOR_NEXT_STATUS_OK	Success.
BT_MESSAGE_ITERATOR_NEXT_STATUS_END	End of iteration.
BT_MESSAGE_ITERATOR_NEXT_STATUS_AGAIN	Try again.
BT_MESSAGE_ITERATOR_NEXT_STATUS_MEMORY_ERROR	Out of memory.
BT_MESSAGE_ITERATOR_NEXT_STATUS_ERROR	Other error.

bt_message_iterator_can_seek_beginning_status

enum bt_message_iterator_can_seek_beginning_status

Status code for bt_message_iterator_can_seek_beginning().

Enumerator
BT_MESSAGE_ITERATOR_CAN_SEEK_BEGINNING_STATUS_OK	Success.
BT_MESSAGE_ITERATOR_CAN_SEEK_BEGINNING_STATUS_AGAIN	Try again.
BT_MESSAGE_ITERATOR_CAN_SEEK_BEGINNING_STATUS_MEMORY_ERROR	Out of memory.
BT_MESSAGE_ITERATOR_CAN_SEEK_BEGINNING_STATUS_ERROR	Other error.

bt_message_iterator_seek_beginning_status

enum bt_message_iterator_seek_beginning_status

Status code for bt_message_iterator_seek_beginning().

Enumerator
BT_MESSAGE_ITERATOR_SEEK_BEGINNING_STATUS_OK	Success.
BT_MESSAGE_ITERATOR_SEEK_BEGINNING_STATUS_AGAIN	Try again.
BT_MESSAGE_ITERATOR_SEEK_BEGINNING_STATUS_MEMORY_ERROR	Out of memory.
BT_MESSAGE_ITERATOR_SEEK_BEGINNING_STATUS_ERROR	Other error.

bt_message_iterator_can_seek_ns_from_origin_status

enum bt_message_iterator_can_seek_ns_from_origin_status

Status code for bt_message_iterator_can_seek_ns_from_origin().

Enumerator
BT_MESSAGE_ITERATOR_CAN_SEEK_NS_FROM_ORIGIN_STATUS_OK	Success.
BT_MESSAGE_ITERATOR_CAN_SEEK_NS_FROM_ORIGIN_STATUS_AGAIN	Try again.
BT_MESSAGE_ITERATOR_CAN_SEEK_NS_FROM_ORIGIN_STATUS_MEMORY_ERROR	Out of memory.
BT_MESSAGE_ITERATOR_CAN_SEEK_NS_FROM_ORIGIN_STATUS_ERROR	Other error.

bt_message_iterator_seek_ns_from_origin_status

enum bt_message_iterator_seek_ns_from_origin_status

Status code for bt_message_iterator_seek_ns_from_origin().

Enumerator
BT_MESSAGE_ITERATOR_SEEK_NS_FROM_ORIGIN_STATUS_OK	Success.
BT_MESSAGE_ITERATOR_SEEK_NS_FROM_ORIGIN_STATUS_AGAIN	Try again.
BT_MESSAGE_ITERATOR_SEEK_NS_FROM_ORIGIN_STATUS_MEMORY_ERROR	Out of memory.
BT_MESSAGE_ITERATOR_SEEK_NS_FROM_ORIGIN_STATUS_ERROR	Other error.

Macro Definition Documentation

BT_MESSAGE_ITERATOR_PUT_REF_AND_RESET

#define BT_MESSAGE_ITERATOR_PUT_REF_AND_RESET

(

_message_iterator

)

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

Parameters

_message_iterator

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

Precondition

_message_iterator is an assignable expression.

BT_MESSAGE_ITERATOR_MOVE_REF

#define BT_MESSAGE_ITERATOR_MOVE_REF	(		_dst,
			_src )

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

This macro effectively moves a message iterator 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_create_from_message_iterator()

bt_message_iterator_create_from_message_iterator_status bt_message_iterator_create_from_message_iterator ( bt_self_message_iterator * self_message_iterator, bt_self_component_port_input * port, bt_message_iterator ** message_iterator )

extern

Creates a message iterator on the input port port from another message iterator self_message_iterator, and sets *message_iterator to the resulting message iterator.

On success, the position of *message_iterator is at the beginning of its message sequence.

Parameters

[in]	self_message_iterator	Other message iterator from which to create the message iterator.
[in]	port	Input port on which to create the message iterator.
[out]	message_iterator	On success, *message_iterator is a new message iterator reference.

Return values

BT_MESSAGE_ITERATOR_CREATE_FROM_MESSAGE_ITERATOR_STATUS_OK	Success.
BT_MESSAGE_ITERATOR_CREATE_FROM_MESSAGE_ITERATOR_STATUS_MEMORY_ERROR	Out of memory.
BT_MESSAGE_ITERATOR_CREATE_FROM_MESSAGE_ITERATOR_STATUS_ERROR	Other error, for example, the initialization method of the created message iterator failed.

Precondition

self_message_iterator is not NULL.

port is not NULL.

bt_port_is_connected(port) returns BT_TRUE.

message_iterator is not NULL.

See also

bt_message_iterator_create_from_sink_component() — Creates a message iterator from a sink component.

bt_message_iterator_create_from_sink_component()

bt_message_iterator_create_from_sink_component_status bt_message_iterator_create_from_sink_component ( bt_self_component_sink * self_component_sink, bt_self_component_port_input * port, bt_message_iterator ** message_iterator )

extern

Creates a message iterator on the input port port from the sink component self_component_sink, and sets *message_iterator to the resulting message iterator.

On success, the position of *message_iterator is at the beginning of its message sequence.

Parameters

[in]	self_component_sink	Sink component from which to create the message iterator.
[in]	port	Input port on which to create the message iterator.
[out]	message_iterator	On success, *message_iterator is a new message iterator reference.

Return values

BT_MESSAGE_ITERATOR_CREATE_FROM_MESSAGE_ITERATOR_STATUS_OK	Success.
BT_MESSAGE_ITERATOR_CREATE_FROM_MESSAGE_ITERATOR_STATUS_MEMORY_ERROR	Out of memory.
BT_MESSAGE_ITERATOR_CREATE_FROM_MESSAGE_ITERATOR_STATUS_ERROR	Other error, for example, the initialization method of the created message iterator failed.

Precondition

self_component_sink is not NULL.

port is not NULL.

bt_port_is_connected(port) returns BT_TRUE.

message_iterator is not NULL.

See also

bt_message_iterator_create_from_message_iterator() — Creates a message iterator from another message iterator.

bt_message_iterator_borrow_component()

bt_component * bt_message_iterator_borrow_component ( bt_message_iterator * message_iterator )

extern

Borrows the component which provides the message iterator message_iterator.

Parameters

[in]

message_iterator

Message iterator from which to borrow the component which provides it.

Returns

Component which provides message_iterator.

Precondition

message_iterator is not NULL.

bt_message_iterator_next()

bt_message_iterator_next_status bt_message_iterator_next ( bt_message_iterator * message_iterator, bt_message_array_const * messages, uint64_t * count )

extern

Returns the next messages of the message iterator message_iterator into the *messages array of size *count, effectively advancing message_iterator.

See the documentation of this operation.

On success, the position of message_iterator is advanced by *count messages.

Parameters

[in]	message_iterator	Message iterator from which to get the next messages.
[out]	messages	On success, *messages is an array containing the next messages of message_iterator as its first elements. *count is the number of messages in *messages. The library allocates and manages this array, but until you perform another operation on message_iterator, you're free to modify it. For example, you can set its elements to NULL if your use case needs it. You own the references of the messages this array contains. In other words, you must put them with bt_message_put_ref() or move them to another message array (from a "next" method) before you perform another operation on message_iterator or before message_iterator is destroyed.
[out]	count	On success, *count is the number of messages in *messages.

Return values

BT_MESSAGE_ITERATOR_NEXT_STATUS_OK	Success.
BT_MESSAGE_ITERATOR_NEXT_STATUS_END	End of iteration.
BT_MESSAGE_ITERATOR_NEXT_STATUS_AGAIN	Try again.
BT_MESSAGE_ITERATOR_NEXT_STATUS_MEMORY_ERROR	Out of memory.
BT_MESSAGE_ITERATOR_NEXT_STATUS_ERROR	Other error.

Precondition

message_iterator is not NULL.

messages is not NULL.

count is not NULL.

Postcondition

On success, *count ≥ 1.

bt_message_iterator_can_seek_beginning()

bt_message_iterator_can_seek_beginning_status bt_message_iterator_can_seek_beginning ( bt_message_iterator * message_iterator, bt_bool * can_seek_beginning )

extern

Returns whether or not the message iterator message_iterator can currently seek its beginning (first message).

See the "seek beginning" operation.

Make sure to call this function, without performing any other operation on message_iterator, before you call bt_message_iterator_seek_beginning().

Parameters

[in]	message_iterator	Message iterator from which to to get whether or not it can seek its beginning.
[out]	can_seek_beginning	On success, *can_seek_beginning is BT_TRUE if message_iterator can seek its beginning.

Return values

BT_MESSAGE_ITERATOR_CAN_SEEK_BEGINNING_STATUS_OK	Success.
BT_MESSAGE_ITERATOR_CAN_SEEK_BEGINNING_STATUS_AGAIN	Try again.
BT_MESSAGE_ITERATOR_CAN_SEEK_BEGINNING_STATUS_MEMORY_ERROR	Out of memory.
BT_MESSAGE_ITERATOR_CAN_SEEK_BEGINNING_STATUS_ERROR	Other error.

Precondition

message_iterator is not NULL.

can_seek_beginning is not NULL.

See also

bt_message_iterator_seek_beginning() — Makes a message iterator seek its beginning.

bt_message_iterator_seek_beginning()

bt_message_iterator_seek_beginning_status bt_message_iterator_seek_beginning ( bt_message_iterator * message_iterator )

extern

Makes the message iterator message_iterator seek its beginning (first message).

See the documentation of this operation.

Make sure to call bt_message_iterator_can_seek_beginning(), without performing any other operation on message_iterator, before you call this function.

Parameters

[in]

message_iterator

Message iterator to seek to its beginning.

Return values

BT_MESSAGE_ITERATOR_SEEK_BEGINNING_STATUS_OK	Success.
BT_MESSAGE_ITERATOR_SEEK_BEGINNING_STATUS_AGAIN	Try again.
BT_MESSAGE_ITERATOR_SEEK_BEGINNING_STATUS_MEMORY_ERROR	Out of memory.
BT_MESSAGE_ITERATOR_SEEK_BEGINNING_STATUS_ERROR	Other error.

Precondition

message_iterator is not NULL.

bt_message_iterator_can_seek_beginning(message_iterator) returns BT_TRUE.

See also

bt_message_iterator_can_seek_beginning() — Returns whether or not a message iterator can currently seek its beginning.

bt_message_iterator_can_seek_ns_from_origin()

bt_message_iterator_can_seek_ns_from_origin_status bt_message_iterator_can_seek_ns_from_origin ( bt_message_iterator * message_iterator, int64_t ns_from_origin, bt_bool * can_seek_ns_from_origin )

extern

Returns whether or not the message iterator message_iterator can currently seek a message occurring at or after ns_from_origin nanoseconds from its clock class origin.

See the "seek ns from origin" operation.

Make sure to call this function, without performing any other operation on message_iterator, before you call bt_message_iterator_seek_ns_from_origin().

Parameters

[in]	message_iterator	Message iterator from which to to get whether or not it can seek its beginning.
[in]	ns_from_origin	Requested time point to seek.
[out]	can_seek_ns_from_origin	On success, *can_seek_ns_from_origin is BT_TRUE if message_iterator can seek a message occurring at or after ns_from_origin nanoseconds from its clock class origin.

Return values

BT_MESSAGE_ITERATOR_CAN_SEEK_NS_FROM_ORIGIN_STATUS_OK	Success.
BT_MESSAGE_ITERATOR_CAN_SEEK_NS_FROM_ORIGIN_STATUS_AGAIN	Try again.
BT_MESSAGE_ITERATOR_CAN_SEEK_NS_FROM_ORIGIN_STATUS_MEMORY_ERROR	Out of memory.
BT_MESSAGE_ITERATOR_CAN_SEEK_NS_FROM_ORIGIN_STATUS_ERROR	Other error.

Precondition

message_iterator is not NULL.

can_seek_ns_from_origin is not NULL.

See also

bt_message_iterator_seek_ns_from_origin() — Makes a message iterator seek a message occurring at or after a given time from its clock class origin.

bt_message_iterator_seek_ns_from_origin()

bt_message_iterator_seek_ns_from_origin_status bt_message_iterator_seek_ns_from_origin ( bt_message_iterator * message_iterator, int64_t ns_from_origin )

extern

Makes the message iterator message_iterator seek a message occurring at or after ns_from_origin nanoseconds from its clock class origin.

See the documentation of this operation.

Make sure to call bt_message_iterator_can_seek_ns_from_origin(), without performing any other operation on message_iterator, before you call this function.

Parameters

[in]	message_iterator	Message iterator to seek to a message occurring at or after ns_from_origin nanoseconds from its clock class origin.
[in]	ns_from_origin	Time point to seek.

Return values

BT_MESSAGE_ITERATOR_SEEK_NS_FROM_ORIGIN_STATUS_OK	Success.
BT_MESSAGE_ITERATOR_SEEK_NS_FROM_ORIGIN_STATUS_AGAIN	Try again.
BT_MESSAGE_ITERATOR_SEEK_NS_FROM_ORIGIN_STATUS_MEMORY_ERROR	Out of memory.
BT_MESSAGE_ITERATOR_SEEK_NS_FROM_ORIGIN_STATUS_ERROR	Other error.

Precondition

message_iterator is not NULL.

bt_message_iterator_can_seek_ns_from_origin(message_iterator, ns_from_origin) returns BT_TRUE.

See also

bt_message_iterator_can_seek_ns_from_origin() — Returns whether or not a message iterator can currently seek a message occurring at or after a given time from its clock class origin.

bt_message_iterator_can_seek_forward()

bt_bool bt_message_iterator_can_seek_forward ( bt_message_iterator * message_iterator )

extern

Returns whether or not the message iterator message_iterator can seek forward.

A message iterator can seek forward if all the messages of its message sequence have some clock snapshot.

Parameters

[in]

message_iterator

Message iterator of which to get whether or not it can seek forward.

Returns

BT_TRUE if message_iterator can seek forward.

See also

bt_self_message_iterator_configuration_set_can_seek_forward() — Sets whether or not a message iterator can seek forward.

bt_message_iterator_get_ref()

void bt_message_iterator_get_ref ( const bt_message_iterator * message_iterator )

extern

Increments the reference count of the message iterator message_iterator.

Parameters

[in]

message_iterator

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

See also

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

bt_message_iterator_put_ref()

void bt_message_iterator_put_ref ( const bt_message_iterator * message_iterator )

extern

Decrements the reference count of the message iterator message_iterator.

Parameters

[in]

message_iterator

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

See also

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