|
Babeltrace 2 C API
2.0.0
Open-source trace manipulation framework
|
|
Babeltrace 2 C API
2.0.0
Open-source trace manipulation framework
|
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 a message iterator's component 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:
This is the case for a filter component's message iterator.
Use bt_message_iterator_create_from_message_iterator().
You can call this function from any message iterator method except the finalization method.
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:
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:
The following illustration shows a very simple use case where the consuming method of a sink component uses a single filter component's message iterator which itself uses a single source component's message iterator:
Many message iterator relations are possible, for example:
Once you have created a message iterator, there are three possible operations:
This operation returns a batch of the message iterator's next messages 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().
This operation resets the message iterator's position 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 message iterator's sequence.
If bt_message_iterator_seek_ns_from_origin() returns something else than BT_MESSAGE_ITERATOR_SEEK_BEGINNING_STATUS_OK, 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().
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 is left to the message iterator's implementation to seek a message having at least this time.
If the requested time point is after the message iterator's sequence's last message, 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, 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().
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. More... | |
"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. More... | |
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. More... | |
Reference count | |
| void | bt_message_iterator_get_ref (const bt_message_iterator *message_iterator) |
| Increments the reference count of the message iterator message_iterator. More... | |
| void | bt_message_iterator_put_ref (const bt_message_iterator *message_iterator) |
| Decrements the reference count of the message iterator message_iterator. More... | |
| #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. More... | |
| #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. More... | |
Status code for bt_message_iterator_create_from_message_iterator().
Status code for bt_message_iterator_create_from_sink_component().
Status code for bt_message_iterator_next().
Status code for bt_message_iterator_can_seek_beginning().
Status code for bt_message_iterator_seek_beginning().
Status code for bt_message_iterator_can_seek_ns_from_origin().
Status code for bt_message_iterator_seek_ns_from_origin().
| #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.
| _message_iterator | Message iterator of which to decrement the reference count. Can contain |
| #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.
| _dst | Destination expression. Can contain |
| _src | Source expression. Can contain |
| 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.
On success, the message iterator's position is at the beginning of its message sequence.
| [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. |
| 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 created message iterator's initialization method failed. |
NULL. NULL. bt_port_is_connected(port) returns BT_TRUE. NULL.| 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.
On success, the message iterator's position is at the beginning of its message sequence.
| [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. |
| 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 created message iterator's initialization method failed. |
NULL. NULL. bt_port_is_connected(port) returns BT_TRUE. NULL.| bt_component* bt_message_iterator_borrow_component | ( | bt_message_iterator * | message_iterator | ) |
Borrows the component which provides the message iterator message_iterator.
| [in] | message_iterator | Message iterator from which to borrow the component which provides it. |
NULL. | 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.
See this operation's documentation.
On success, the message iterator's position is advanced by *count messages.
| [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 are free to modify it. For example, you can set its elements to 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. |
| 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. |
NULL. NULL. NULL.| 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).
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().
| [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. |
NULL. NULL.| 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).
See this operation's documentation.
Make sure to call bt_message_iterator_can_seek_beginning(), without performing any other operation on message_iterator, before you call this function.
| [in] | message_iterator | Message iterator to seek to its beginning. |
NULL. bt_message_iterator_can_seek_beginning(message_iterator) returns BT_TRUE.| 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 occuring 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().
| [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 occuring at or after ns_from_origin nanoseconds from its clock class origin. |
NULL. NULL.| 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 occuring at or after ns_from_origin nanoseconds from its clock class origin.
See this operation's documentation.
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.
| [in] | message_iterator | Message iterator to seek to a message occuring at or after ns_from_origin nanoseconds from its clock class origin. |
| [in] | ns_from_origin | Time point to seek. |
NULL. bt_message_iterator_can_seek_ns_from_origin(message_iterator, ns_from_origin) returns BT_TRUE.| 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.
A message iterator can seek forward if all the messages of its message sequence have some clock snapshot.
| [in] | message_iterator | Message iterator of which to get whether or not it can seek forward. |
| void bt_message_iterator_get_ref | ( | const bt_message_iterator * | message_iterator | ) |
Increments the reference count of the message iterator message_iterator.
| [in] | message_iterator | Message iterator of which to increment the reference count. Can be |
| void bt_message_iterator_put_ref | ( | const bt_message_iterator * | message_iterator | ) |
Decrements the reference count of the message iterator message_iterator.
| [in] | message_iterator | Message iterator of which to decrement the reference count. Can be |
1.8.16