|
Babeltrace 2 C API 2.1.0
Open-source trace manipulation framework
|
|
Babeltrace 2 C API 2.1.0
Open-source trace manipulation framework
|
Elements exchanged between components.
Messages are the objects which are exchanged between components in a trace processing graph to accomplish a trace processing job.
Message iterators create messages while message iterators and sink components consume messages.
There are eight types of messages:
The type of a message is bt_message.
Get the type enumerator of a message with bt_message_get_type().
A message is a shared object: get a new reference with bt_message_get_ref() and put an existing reference with bt_message_put_ref().
Some library functions freeze messages on success. The documentation of those functions indicate this postcondition.
Messages transport objects of the Trace IR API, which is an intermediate representation of the tracing domain concepts.
All types of messages, except the message iterator inactivity message type, are related to a specific stream, which represents a conceptual sequence of messages.
Some types of messages can have a default clock snapshot, depending on whether or not their stream has a conceptual default clock, that is, whether or not the class of the stream has a default clock class. The creation functions for those types of messages contain _with_default_clock_snapshot (for example, bt_message_event_create_with_default_clock_snapshot()).
For the stream beginning message and stream end message, the default clock snapshot property is optional, therefore they have dedicated bt_message_stream_beginning_set_default_clock_snapshot() and bt_message_stream_end_set_default_clock_snapshot() functions.
All the message creation functions take a self message iterator as their first parameter. This is because a message iterator method is the only valid context to create a message.
This section details each type of message.
The following table shows the creation functions and types for each type of message:
A stream beginning message indicates the beginning of a stream.
For a given stream:
Create a stream beginning message with bt_message_stream_beginning_create().
A stream beginning message has the following properties:
Stream of which the message indicates the beginning.
You cannot change the stream once the message is created.
Borrow the stream of a stream beginning message with bt_message_stream_beginning_borrow_stream() and bt_message_stream_beginning_borrow_stream_const().
Snapshot of the default clock of the stream of the message when the stream begins.
A stream beginning message can only have a default clock snapshot if the class of its stream has a default clock class.
When a stream beginning message has no default clock snapshot, then its time is unknown.
Set the default clock snapshot of a stream beginning message with bt_message_stream_beginning_set_default_clock_snapshot().
Borrow the default clock snapshot of a stream beginning message with bt_message_stream_beginning_borrow_default_clock_snapshot_const().
A stream end message indicates the end of a stream.
For a given stream:
Create a stream end message with bt_message_stream_end_create().
A stream end message has the following properties:
Stream of which the message indicates the end.
You cannot change the stream once the message is created.
Borrow the stream of a stream end message with bt_message_stream_end_borrow_stream() and bt_message_stream_end_borrow_stream_const().
Snapshot of the default clock of the stream of the message when the stream ends.
A stream end message can only have a default clock snapshot if the class of its stream has a default clock class.
When a stream end message has no default clock snapshot, then its time is unknown.
Set the default clock snapshot of a stream end message with bt_message_stream_end_set_default_clock_snapshot().
Borrow the default clock snapshot of a stream end message with bt_message_stream_end_borrow_default_clock_snapshot_const().
An event message transports an event and has, possibly, a default clock snapshot.
Within the message sequence of its stream, an event message can only occur:
After a packet beginning message and before a packet end message.
To create an event message for a given stream, use:
bt_message_event_create_with_packet_and_default_clock_snapshot()
Those two creation functions accept a packet parameter which is the packet logically containing the event of the message. A packet is part of a stream.
The four creation functions above accept an event class parameter. When you create the message, the library instantiates this event class as an event. Borrow the resulting event with bt_message_event_borrow_event(). This event class must be part of the class of the stream of the event message.
The event of an event message is initially not set: before you emit the event message from the "next" method of a message iterator, you need to borrow each of its fields (with bt_event_borrow_payload_field(), bt_event_borrow_specific_context_field(), and bt_event_borrow_common_context_field()) and, recursively, set the values of the all their inner fields.
An event message has the following properties:
Event which the message transports.
This is an instance of the event class which was passed to the creation function of the message.
With this event, you can access its packet (if any) with bt_event_borrow_packet_const() and its stream with bt_event_borrow_stream_const().
Borrow the event of an event message with bt_message_event_borrow_event() and bt_message_event_borrow_event_const().
Snapshot of the default clock of the stream of the message when the event occurs.
An event message has a default clock snapshot if the class of its stream has a default clock class, and has none otherwise.
Within the message sequence of its message iterator, the default clock snapshot of an event message must be greater than or equal to any default clock snapshot of any previous message.
Borrow the default clock snapshot of an event message with bt_message_event_borrow_default_clock_snapshot_const().
A packet beginning message indicates the beginning of a packet.
A packet beginning message can only exist if the class of its stream supports packets.
For a given packet, there can be only one packet beginning message.
Within the message sequence of its stream, a packet beginning message can only occur after the stream beginning message and before the stream end message.
To create a packet beginning message for a given stream, use:
bt_message_packet_beginning_create_with_default_clock_snapshot()
A packet beginning message has the following properties:
Packet of which the message indicates the beginning.
You cannot change the packet once the message is created.
Borrow the packet of a packet beginning message with bt_message_packet_beginning_borrow_packet() and bt_message_packet_beginning_borrow_packet_const().
Snapshot of the default clock of the stream of the message when the packet begins.
A packet beginning message has a default clock snapshot if:
Within its the message sequence of its message iterator, the default clock snapshot of a packet beginning message must be greater than or equal to any clock snapshot of any previous message.
Borrow the default clock snapshot of a packet beginning message with bt_message_packet_beginning_borrow_default_clock_snapshot_const().
A packet end message indicates the end of a packet.
A packet end message can only exist if the class of its stream supports packets.
For a given packet, there can be only one packet end message.
Within the message sequence of its stream, a packet end message can only occur:
To create a packet end message for a given stream, use:
A packet end message has the following properties:
Packet of which the message indicates the end.
You cannot change the packet once the message is created.
Borrow the packet of a packet end message with bt_message_packet_end_borrow_packet() and bt_message_packet_end_borrow_packet_const().
Snapshot of the default clock of the stream of the message when the packet ends.
A packet end message has a default clock snapshot if:
Within its the message sequence of its message iterator, the default clock snapshot of a packet end message must be greater than or equal to any clock snapshot of any previous message.
Borrow the default clock snapshot of a packet end message with bt_message_packet_end_borrow_default_clock_snapshot_const().
A discarded events message indicates that events were discarded at tracing time. It does not indicate that event messages were dropped during a trace processing graph run.
A discarded events message can only exist if the class of its stream supports discarded events.
Within the message sequence of its stream, a discarded events message can only occur after the stream beginning message and before the stream end message.
To create a discarded events message for a given stream, use:
bt_message_discarded_events_create_with_default_clock_snapshots()
A discarded events message has the following properties:
Stream into which events were discarded.
You cannot change the stream once the message is created.
Borrow the stream of a discarded events message with bt_message_discarded_events_borrow_stream() and bt_message_discarded_events_borrow_stream_const().
Snapshot of the default clock of the stream of the message which indicates the beginning of the discarded events time range.
A discarded events message has a beginning default clock snapshot if:
Within its the message sequence of its message iterator, the beginning default clock snapshot of a discarded events message must be greater than or equal to any clock snapshot of any previous message.
Borrow the beginning default clock snapshot of a discarded events message with bt_message_discarded_events_borrow_beginning_default_clock_snapshot_const().
Snapshot of the default clock of the stream of the message which indicates the end of the discarded events time range.
A discarded events message has an end default clock snapshot if:
If a discarded events message has both a beginning and an end default clock snapshots, then the end default clock snapshot must be greater than or equal to the beginning default clock snapshot.
Within its the message sequence of its message iterator, the end default clock snapshot of a discarded events message must be greater than or equal to any clock snapshot of any previous message.
Borrow the end default clock snapshot of a discarded events message with bt_message_discarded_events_borrow_end_default_clock_snapshot_const().
Exact number of discarded events.
If this property is missing, then the number of discarded events is at least one.
Use bt_message_discarded_events_set_count() and bt_message_discarded_events_get_count().
A discarded packets message indicates that packets were discarded at tracing time. It does not indicate that whole packets were dropped during a trace processing graph run.
A discarded packets message can only exist if the class of its stream supports discarded packets.
Within the message sequence of its stream, a discarded packets message can only occur:
To create a discarded packets message for a given stream, use:
bt_message_discarded_packets_create_with_default_clock_snapshots()
A discarded packets message has the following properties:
Stream into which packets were discarded.
You cannot change the stream once the message is created.
Borrow the stream of a discarded packets message with bt_message_discarded_packets_borrow_stream() and bt_message_discarded_packets_borrow_stream_const().
Snapshot of the default clock of the stream of the message which indicates the beginning of the discarded packets time range.
A discarded packets message has a beginning default clock snapshot if:
Within its the message sequence of its message iterator, the beginning default clock snapshot of a discarded packets message must be greater than or equal to any clock snapshot of any previous message.
Borrow the beginning default clock snapshot of a discarded packets message with bt_message_discarded_packets_borrow_beginning_default_clock_snapshot_const().
Snapshot of the default clock of the stream of the message which indicates the end of the discarded packets time range.
A discarded packets message has an end default clock snapshot if:
If a discarded packets message has both a beginning and an end default clock snapshots, then the end default clock snapshot must be greater than or equal to the beginning default clock snapshot.
Within its the message sequence of its message iterator, the end default clock snapshot of a discarded packets message must be greater than or equal to any clock snapshot of any previous message.
Borrow end default clock snapshot of a discarded packets message with bt_message_discarded_packets_borrow_end_default_clock_snapshot_const().
Exact number of discarded packets.
If this property is missing, then the number of discarded packets is at least one.
Use bt_message_discarded_packets_set_count() and bt_message_discarded_packets_get_count().
A message iterator inactivity message indicates that, within the message sequence of a given message iterator, there's no messages since the last message (if any) until a given point in time.
A message iterator inactivity message is the only type of message that's not related to a stream: it targets the whole message sequence of a message iterator, and can occur at any position within the sequence.
This message is mostly significant for real-time message iterators: if a message iterator A indicates that there's no messages until a given point in time T, then a downstream filter message iterator B which relies on multiple upstream message iterators doesn't have to wait for new messages from A until T.
In other words, a message iterator inactivity message can help downstream message iterators or sink components progress.
Create a message iterator inactivity message with bt_message_message_iterator_inactivity_create(). You must pass a clock class and the value of a fictitious (clock) instance to this function so that it creates a clock snapshot.
A message iterator inactivity message has the following property:
Snapshot of a fictitious instance of the clock class of the message which indicates the point in time until when there's no messages in the message sequence of the message iterator.
Within the message sequence of its message iterator, the clock snapshot of a message iterator inactivity message must be greater than or equal to any clock snapshot of any previous message.
Borrow the clock snapshot of a message iterator inactivity message with bt_message_message_iterator_inactivity_borrow_clock_snapshot_const().
The Message Interchange Protocol (MIP) is the system of rules used by components and message iterators to exchange messages within a trace processing graph.
The MIP covers everything related to messages and what they contain, as well as how they're ordered within the sequence that a message iterator produces.
For example:
The MIP has a version which is a single major number, independent from the version of the Babeltrace 2 project.
If what the MIP covers changes in a breaking or semantical way in the future, then the MIP and Babeltrace 2's minor versions will be bumped.
When you create a trace processing graph with bt_graph_create(), you must pass the effective MIP version to use. Then, the components you add to this graph can access this configured MIP version with bt_self_component_get_graph_mip_version() and behave accordingly. In other words, if the configured MIP version is 0, then a component cannot use features introduced by MIP version 1 (for example, create a BLOB field class).
The bt_graph_add_*_component*() functions have a precondition that the component to add supports the effective MIP version of the trace processing graph. To satisfy said precondition, create a component descriptor set with descriptors of the components you intend to add to a trace processing graph and call bt_get_greatest_operative_mip_version() or bt_get_greatest_operative_mip_version_with_restriction() (available since Babeltrace 2.1) to get the greatest (most recent) MIP version you can use.
To get the latest MIP version of the library, use bt_get_maximal_mip_version().
The ultimate goal of the MIP version feature is for the Babeltrace 2 project to be able to introduce new features or even major breaking changes without breaking existing component classes. This is especially important considering that Babeltrace 2 supports plugins written by different authors. Of course one of the objectives of the project is to bump the MIP version as rarely as possible. When it's required, though, it's a welcome tool to make the project evolve gracefully.
The Message Interchange Protocol has no dedicated documentation as this very message API (and its contained APIs, like Trace IR) documentation is enough. You can consider that all the functions of the message and trace IR objects have an implicit MIP version precondition. When a given function documentation doesn't explicitly document a MIP version precondition, it means that the effective MIP version has no effect on the behaviour of said function.
See Add MIP 1 support to your component class to learn how to add MIP 1 support to a component class written for MIP 0.
The purpose of a message iterator is to iterate a sequence of messages.
Those messages can be related to different streams:
However, for such a message sequence, the current Message Interchange Protocol (version 1) dictates that:
For a given stream:
The rules above can be summarized by the following regular expressions:
With this alphabet:
For a given message iterator, for any message with a clock snapshot, its clock snapshot must be greater than or equal to any clock snapshot of any previous message.
For the scope of this rule, the clock snapshot of a discarded events message or of a discarded packets message is its beginning default clock snapshot.
Topics | |
| Trace IR | |
| Intermediate representation of tracing domain objects and concepts (contents of messages). | |
Type query | |
| enum | bt_message_type { BT_MESSAGE_TYPE_STREAM_BEGINNING , BT_MESSAGE_TYPE_STREAM_END , BT_MESSAGE_TYPE_EVENT , BT_MESSAGE_TYPE_PACKET_BEGINNING , BT_MESSAGE_TYPE_PACKET_END , BT_MESSAGE_TYPE_DISCARDED_EVENTS , BT_MESSAGE_TYPE_DISCARDED_PACKETS , BT_MESSAGE_TYPE_MESSAGE_ITERATOR_INACTIVITY } |
| Message type enumerators. More... | |
| typedef enum bt_message_type | bt_message_type |
| Message type enumerators. | |
| bt_message_type | bt_message_get_type (const bt_message *message) |
| Returns the type enumerator of the message message. | |
Common stream message | |
| enum | bt_message_stream_clock_snapshot_state { BT_MESSAGE_STREAM_CLOCK_SNAPSHOT_STATE_KNOWN , BT_MESSAGE_STREAM_CLOCK_SNAPSHOT_STATE_UNKNOWN } |
| Return type of bt_message_stream_beginning_borrow_default_clock_snapshot_const() and bt_message_stream_end_borrow_default_clock_snapshot_const(). More... | |
| typedef enum bt_message_stream_clock_snapshot_state | bt_message_stream_clock_snapshot_state |
| Return type of bt_message_stream_beginning_borrow_default_clock_snapshot_const() and bt_message_stream_end_borrow_default_clock_snapshot_const(). | |
Type | |
| typedef struct bt_message | bt_message |
| Message. | |
Event message | |
| bt_message * | bt_message_event_create (bt_self_message_iterator *self_message_iterator, const bt_event_class *event_class, const bt_stream *stream) |
| Creates an event message, having an instance of the event class event_class, for the stream stream from the message iterator self_message_iterator. | |
| bt_message * | bt_message_event_create_with_default_clock_snapshot (bt_self_message_iterator *self_message_iterator, const bt_event_class *event_class, const bt_stream *stream, uint64_t clock_snapshot_value) |
| Creates an event message, having an instance of the event class event_class and a default clock snapshot with the value clock_snapshot_value, for the stream stream from the message iterator self_message_iterator. | |
| bt_message * | bt_message_event_create_with_packet (bt_self_message_iterator *self_message_iterator, const bt_event_class *event_class, const bt_packet *packet) |
| Creates an event message, having an instance of the event class event_class, for the packet packet from the message iterator self_message_iterator. | |
| bt_message * | bt_message_event_create_with_packet_and_default_clock_snapshot (bt_self_message_iterator *self_message_iterator, const bt_event_class *event_class, const bt_packet *packet, uint64_t clock_snapshot_value) |
| Creates an event message, having an instance of the event class event_class and a default clock snapshot with the value clock_snapshot_value, for the packet packet from the message iterator self_message_iterator. | |
| bt_event * | bt_message_event_borrow_event (bt_message *message) |
| Borrows the event of the event message message. | |
| const bt_event * | bt_message_event_borrow_event_const (const bt_message *message) |
Borrows the event of the event message message (const version). | |
| const bt_clock_snapshot * | bt_message_event_borrow_default_clock_snapshot_const (const bt_message *message) |
| Borrows the default clock snapshot of the event message message. | |
| const bt_clock_class * | bt_message_event_borrow_stream_class_default_clock_class_const (const bt_message *message) |
| Borrows the default clock class of the stream class of the event message message. | |
Message iterator inactivity message | |
| bt_message * | bt_message_message_iterator_inactivity_create (bt_self_message_iterator *self_message_iterator, const bt_clock_class *clock_class, uint64_t clock_snapshot_value) |
| Creates a message iterator inactivity message having a clock snapshot of a fictitious instance of the clock class clock_class with the value clock_snapshot_value from the message iterator self_message_iterator. | |
| const bt_clock_snapshot * | bt_message_message_iterator_inactivity_borrow_clock_snapshot_const (const bt_message *message) |
| Borrows the clock snapshot of the message iterator inactivity message message. | |
Message reference count | |
| void | bt_message_get_ref (const bt_message *message) |
| Increments the reference count of the message message. | |
| void | bt_message_put_ref (const bt_message *message) |
| Decrements the reference count of the message message. | |
| #define | BT_MESSAGE_PUT_REF_AND_RESET(_message) |
Decrements the reference count of the message _message, and then sets _message to NULL. | |
| #define | BT_MESSAGE_MOVE_REF(_dst, _src) |
Decrements the reference count of the message _dst, sets _dst to _src, and then sets _src to NULL. | |
| enum bt_message_type |
Return type of bt_message_stream_beginning_borrow_default_clock_snapshot_const() and bt_message_stream_end_borrow_default_clock_snapshot_const().
| Enumerator | |
|---|---|
| BT_MESSAGE_STREAM_CLOCK_SNAPSHOT_STATE_KNOWN | Known clock snapshot. |
| BT_MESSAGE_STREAM_CLOCK_SNAPSHOT_STATE_UNKNOWN | Unknown (no) clock snapshot. |
Status codes for bt_get_greatest_operative_mip_version() and bt_get_greatest_operative_mip_version_with_restriction().
| #define BT_MESSAGE_PUT_REF_AND_RESET | ( | _message | ) |
Decrements the reference count of the message _message, and then sets _message to NULL.
| _message | Message of which to decrement the reference count. Can contain |
| #define BT_MESSAGE_MOVE_REF | ( | _dst, | |
| _src ) |
Decrements the reference count of the message _dst, sets _dst to _src, and then sets _src to NULL.
This macro effectively moves a message reference from the expression _src to the expression _dst, putting the existing _dst reference.
| _dst | Destination expression. Can contain |
| _src | Source expression. Can contain |
|
extern |
Returns the type enumerator of the message message.
| [in] | message | Message of which to get the type enumerator |
NULL.
|
extern |
Creates a stream beginning message for the stream stream from the message iterator self_message_iterator.
On success, the returned stream beginning message has the following property values:
| Property | Value |
|---|---|
| Stream | stream |
| Default clock snapshot | None |
| [in] | self_message_iterator | Self message iterator from which to create the stream beginning message. |
| [in] | stream | Stream of which the message to create indicates the beginning. |
NULL on memory error.NULL. NULL.
|
extern |
Borrows the stream of the stream beginning message message.
See the stream property.
| [in] | message | Stream beginning message from which to borrow the stream. |
Borrowed reference of the stream of message.
The returned pointer remains valid as long as message exists.
NULL. const version of this function.
|
extern |
Borrows the stream of the stream beginning message message (const version).
|
extern |
Sets the value, in clock cycles, of the default clock snapshot of the stream beginning message message to value.
See the default clock snapshot property.
| [in] | message | Stream beginning message of which to set the default clock snapshot value to value. |
| [in] | value | New value (clock cycles) of the default clock snapshot of message. |
NULL.
|
extern |
Borrows the default clock snapshot of the stream beginning message message.
See the default clock snapshot property.
| [in] | message | Stream beginning message from which to borrow the default clock snapshot. |
| [out] | clock_snapshot | If this function returns BT_MESSAGE_STREAM_CLOCK_SNAPSHOT_STATE_KNOWN, then *clock_snapshot is a borrowed reference of the default clock snapshot of message. |
| BT_MESSAGE_STREAM_CLOCK_SNAPSHOT_STATE_KNOWN | The default clock snapshot of message is known and returned as *clock_snapshot. |
| BT_MESSAGE_STREAM_CLOCK_SNAPSHOT_STATE_UNKNOWN | message has no default clock snapshot: its time is unknown. |
NULL. NULL.
|
extern |
Borrows the default clock class of the stream class of the stream beginning message message.
See the default clock class property of a stream class.
This is a helper which is equivalent to
| [in] | message | Stream beginning message from which to borrow the default clock class of the class of its stream. |
NULL if none.NULL.
|
extern |
Creates a stream end message for the stream stream from the message iterator self_message_iterator.
On success, the returned stream end message has the following property values:
| Property | Value |
|---|---|
| Stream | stream |
| Default clock snapshot | None |
| [in] | self_message_iterator | Self message iterator from which to create the stream end message. |
| [in] | stream | Stream of which the message to create indicates the end. |
NULL on memory error.NULL. NULL.
|
extern |
Borrows the stream of the stream end message message.
See the stream property.
| [in] | message | Stream end message from which to borrow the stream. |
Borrowed reference of the stream of message.
The returned pointer remains valid as long as message exists.
NULL. const version of this function.
|
extern |
Borrows the stream of the stream end message message (const version).
|
extern |
Sets the value, in clock cycles, of the default clock snapshot of the stream end message message to value.
See the default clock snapshot property.
| [in] | message | Stream end message of which to set the default clock snapshot value to value. |
| [in] | value | New value (clock cycles) of the default clock snapshot of message. |
NULL.
|
extern |
Borrows the default clock snapshot of the stream end message message.
See the default clock snapshot property.
| [in] | message | Stream end message from which to borrow the default clock snapshot. |
| [out] | clock_snapshot | If this function returns BT_MESSAGE_STREAM_CLOCK_SNAPSHOT_STATE_KNOWN, then *clock_snapshot is a borrowed reference of the default clock snapshot of message. |
| BT_MESSAGE_STREAM_CLOCK_SNAPSHOT_STATE_KNOWN | The default clock snapshot of message is known and returned as *clock_snapshot. |
| BT_MESSAGE_STREAM_CLOCK_SNAPSHOT_STATE_UNKNOWN | message has no default clock snapshot: its time is unknown. |
NULL. NULL.
|
extern |
Borrows the default clock class of the stream class of the stream end message message.
See the default clock class property of a stream class.
This is a helper which is equivalent to
| [in] | message | Stream end message from which to borrow the default clock class of the class of its stream. |
NULL if none.NULL.
|
extern |
Creates an event message, having an instance of the event class event_class, for the stream stream from the message iterator self_message_iterator.
Only use this function if
returns BT_FALSE and
returns NULL.
Otherwise, use bt_message_event_create_with_default_clock_snapshot(), bt_message_event_create_with_packet(), or bt_message_event_create_with_packet_and_default_clock_snapshot().
On success, the returned event message has the following property values:
| Property | Value |
|---|---|
| Event | An instance (with fields that aren't set) of event_class. |
| Default clock snapshot | None |
| [in] | self_message_iterator | Self message iterator from which to create the event message. |
| [in] | event_class | Class of the event of the message to create. |
| [in] | stream | Stream conceptually containing the event of the message to create. |
NULL on memory error.NULL. bt_event_class_borrow_stream_class_const(event_class) and bt_stream_borrow_class_const(stream) have the same value. NULL. bt_stream_class_supports_packets(bt_stream_borrow_class_const(stream)) returns BT_FALSE. bt_stream_class_borrow_default_clock_class_const(bt_stream_borrow_class_const(stream)) returns NULL.
|
extern |
Creates an event message, having an instance of the event class event_class and a default clock snapshot with the value clock_snapshot_value, for the stream stream from the message iterator self_message_iterator.
Only use this function if
returns BT_FALSE and
does not return NULL.
Otherwise, use bt_message_event_create(), bt_message_event_create_with_packet(), or bt_message_event_create_with_packet_and_default_clock_snapshot().
On success, the returned event message has the following property values:
| Property | Value |
|---|---|
| Event | An instance (with fields that aren't set) of event_class. |
| Default clock snapshot | Clock snapshot with the value clock_snapshot_value. |
| [in] | self_message_iterator | Self message iterator from which to create the event message. |
| [in] | event_class | Class of the event of the message to create. |
| [in] | stream | Stream conceptually containing the event of the message to create. |
| [in] | clock_snapshot_value | Value (clock cycles) of the default clock snapshot of message. |
NULL on memory error.NULL. bt_event_class_borrow_stream_class_const(event_class) and bt_stream_borrow_class_const(stream) have the same value. NULL. bt_stream_class_supports_packets(bt_stream_borrow_class_const(stream)) returns BT_FALSE. bt_stream_class_borrow_default_clock_class_const(bt_stream_borrow_class_const(stream)) does not return NULL.
|
extern |
Creates an event message, having an instance of the event class event_class, for the packet packet from the message iterator self_message_iterator.
Only use this function if
returns BT_TRUE and
returns NULL.
Otherwise, use bt_message_event_create(), bt_message_event_create_with_default_clock_snapshot(), or bt_message_event_create_with_packet_and_default_clock_snapshot().
On success, the returned event message has the following property values:
| Property | Value |
|---|---|
| Event | An instance (with fields that aren't set) of event_class. |
| Default clock snapshot | None |
| [in] | self_message_iterator | Self message iterator from which to create the event message. |
| [in] | event_class | Class of the event of the message to create. |
| [in] | packet | Packet conceptually containing the event of the message to create. |
NULL on memory error.NULL. bt_event_class_borrow_stream_class_const(event_class) and bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet)) have the same value. NULL. bt_stream_class_supports_packets(bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet))) returns BT_TRUE. bt_stream_class_borrow_default_clock_class_const(bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet))) returns NULL.
|
extern |
Creates an event message, having an instance of the event class event_class and a default clock snapshot with the value clock_snapshot_value, for the packet packet from the message iterator self_message_iterator.
Only use this function if
returns BT_TRUE and
does not return NULL.
Otherwise, use bt_message_event_create(), bt_message_event_create_with_default_clock_snapshot(), or bt_message_event_create_with_packet().
On success, the returned event message has the following property values:
| Property | Value |
|---|---|
| Event | An instance (with fields that aren't set) of event_class. |
| Default clock snapshot | Clock snapshot with the value clock_snapshot_value. |
| [in] | self_message_iterator | Self message iterator from which to create the event message. |
| [in] | event_class | Class of the event of the message to create. |
| [in] | packet | Packet conceptually containing the event of the message to create. |
| [in] | clock_snapshot_value | Value (clock cycles) of the default clock snapshot of message. |
NULL on memory error.NULL. bt_event_class_borrow_stream_class_const(event_class) and bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet)) have the same value. NULL. bt_stream_class_supports_packets(bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet))) returns BT_TRUE. bt_stream_class_borrow_default_clock_class_const(bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet))) does not return NULL.
|
extern |
Borrows the event of the event message message.
See the event property.
| [in] | message | Event message from which to borrow the event. |
Borrowed reference of the event of message.
The returned pointer remains valid as long as message exists.
NULL. const version of this function.
|
extern |
Borrows the event of the event message message (const version).
|
extern |
Borrows the default clock snapshot of the event message message.
See the default clock snapshot property.
| [in] | message | Event message from which to borrow the default clock snapshot. |
NULL.
|
extern |
Borrows the default clock class of the stream class of the event message message.
See the default clock class property of a stream class.
This is a helper which is equivalent to
| [in] | message | Event message from which to borrow the default clock class of the class of its stream. |
NULL if none.NULL.
|
extern |
Creates a packet beginning message for the packet packet from the message iterator self_message_iterator.
Only use this function if
returns BT_FALSE.
Otherwise, use bt_message_packet_beginning_create_with_default_clock_snapshot().
On success, the returned packet beginning message has the following property values:
| Property | Value |
|---|---|
| Packet | packet |
| Default clock snapshot | None |
| [in] | self_message_iterator | Self message iterator from which to create the packet beginning message. |
| [in] | packet | Packet of which the message to create indicates the beginning. |
NULL on memory error.NULL. NULL. bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet)).
|
extern |
Creates a packet beginning message having a default clock snapshot with the value clock_snapshot_value for the packet packet from the message iterator self_message_iterator.
Only use this function if
returns BT_TRUE.
Otherwise, use bt_message_packet_beginning_create().
On success, the returned packet beginning message has the following property values:
| Property | Value |
|---|---|
| Packet | packet |
| Default clock snapshot | Clock snapshot with the value clock_snapshot_value. |
| [in] | self_message_iterator | Self message iterator from which to create the packet beginning message. |
| [in] | packet | Packet of which the message to create indicates the beginning. |
| [in] | clock_snapshot_value | Value (clock cycles) of the default clock snapshot of message. |
NULL on memory error.NULL. NULL. bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet)).
|
extern |
Borrows the packet of the packet beginning message message.
See the packet property.
| [in] | message | Packet beginning message from which to borrow the packet. |
Borrowed reference of the packet of message.
The returned pointer remains valid as long as message exists.
NULL. const version of this function.
|
extern |
Borrows the packet of the packet beginning message message (const version).
|
extern |
Borrows the default clock snapshot of the packet beginning message message.
See the default clock snapshot property.
| [in] | message | Packet beginning message from which to borrow the default clock snapshot. |
NULL.
|
extern |
Borrows the default clock class of the stream class of the packet beginning message message.
See the default clock class property of a stream class.
This is a helper which is equivalent to
| [in] | message | Packet beginning message from which to borrow the default clock class of the class of its stream. |
NULL if none.NULL.
|
extern |
Creates a packet end message for the packet packet from the message iterator self_message_iterator.
Only use this function if
returns BT_FALSE.
Otherwise, use bt_message_packet_end_create_with_default_clock_snapshot().
On success, the returned packet end message has the following property values:
| Property | Value |
|---|---|
| Packet | packet |
| Default clock snapshot | None |
| [in] | self_message_iterator | Self message iterator from which to create the packet end message. |
| [in] | packet | Packet of which the message to create indicates the end. |
NULL on memory error.NULL. NULL. bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet)).
|
extern |
Creates a packet end message having a default clock snapshot with the value clock_snapshot_value for the packet packet from the message iterator self_message_iterator.
Only use this function if
returns BT_TRUE.
Otherwise, use bt_message_packet_end_create().
On success, the returned packet end message has the following property values:
| Property | Value |
|---|---|
| Packet | packet |
| Default clock snapshot | Clock snapshot with the value clock_snapshot_value. |
| [in] | self_message_iterator | Self message iterator from which to create the packet end message. |
| [in] | packet | Packet of which the message to create indicates the end. |
| [in] | clock_snapshot_value | Value (clock cycles) of the default clock snapshot of message. |
NULL on memory error.NULL. NULL. bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet)).
|
extern |
Borrows the packet of the packet end message message.
See the packet property.
| [in] | message | Packet end message from which to borrow the packet. |
Borrowed reference of the packet of message.
The returned pointer remains valid as long as message exists.
NULL. const version of this function.
|
extern |
Borrows the packet of the packet end message message (const version).
|
extern |
Borrows the default clock snapshot of the packet end message message.
See the default clock snapshot property.
| [in] | message | Packet end message from which to borrow the default clock snapshot. |
NULL.
|
extern |
Borrows the default clock class of the stream class of the packet end message message.
See the default clock class property of a stream class.
This is a helper which is equivalent to
| [in] | message | Packet end message from which to borrow the default clock class of the class of its stream. |
NULL if none.NULL.
|
extern |
Creates a discarded events message for the stream stream from the message iterator self_message_iterator.
Only use this function if
returns BT_FALSE.
Otherwise, use bt_message_discarded_events_create_with_default_clock_snapshots().
On success, the returned discarded events message has the following property values:
| Property | Value |
|---|---|
| Stream | stream |
| Beginning default clock snapshot | None |
| End default clock snapshot | None |
| Discarded event count | None |
| [in] | self_message_iterator | Self message iterator from which to create the discarded events message. |
| [in] | stream | Stream from which the events were discarded. |
NULL on memory error.NULL. NULL. bt_stream_class_discarded_events_have_default_clock_snapshots(bt_stream_borrow_class_const(stream)) returns BT_FALSE.
|
extern |
Creates a discarded events message having the beginning and end default clock snapshots with the values beginning_clock_snapshot_value and end_clock_snapshot_value for the stream stream from the message iterator self_message_iterator.
Only use this function if
returns BT_TRUE.
Otherwise, use bt_message_discarded_events_create().
On success, the returned discarded events message has the following property values:
| Property | Value |
|---|---|
| Stream | stream |
| Beginning default clock snapshot | Clock snapshot with the value beginning_clock_snapshot_value. |
| End default clock snapshot | Clock snapshot with the value end_clock_snapshot_value. |
| Discarded event count | None |
| [in] | self_message_iterator | Self message iterator from which to create the discarded events message. |
| [in] | stream | Stream from which the events were discarded. |
| [in] | beginning_clock_snapshot_value | Value (clock cycles) of the beginning default clock snapshot of message. |
| [in] | end_clock_snapshot_value | Value (clock cycles) of the end default clock snapshot of message. |
NULL on memory error.NULL. NULL. bt_stream_class_discarded_events_have_default_clock_snapshots(bt_stream_borrow_class_const(stream)) returns BT_TRUE.
|
extern |
Borrows the stream of the discarded events message message.
See the stream property.
| [in] | message | Discarded events message from which to borrow the stream. |
Borrowed reference of the stream of message.
The returned pointer remains valid as long as message exists.
NULL. const version of this function.
|
extern |
Borrows the stream of the discarded events message message (const version).
|
extern |
Borrows the beginning default clock snapshot of the discarded events message message.
See the beginning default clock snapshot property.
| [in] | message | Discarded events message from which to borrow the beginning default clock snapshot. |
NULL.
|
extern |
Borrows the end default clock snapshot of the discarded events message message.
See the end default clock snapshot property.
| [in] | message | Discarded events message from which to borrow the end default clock snapshot. |
NULL.
|
extern |
Borrows the default clock class of the stream class of the discarded events message message.
See the default clock class property of a stream class.
This is a helper which is equivalent to
| [in] | message | Discarded events message from which to borrow the default clock class of the class of its stream. |
NULL if none.NULL.
|
extern |
Sets the number of discarded events of the discarded events message message to count.
See the discarded event count property.
| [in] | message | Discarded events message of which to set the number of discarded events to count. |
| [in] | count | New number of discarded events of message. |
NULL.
|
extern |
Returns the number of discarded events of the discarded events message message.
See the discarded event count property.
| [in] | message | Discarded events message of which to get the number of discarded events. |
| [out] | count | If this function returns BT_PROPERTY_AVAILABILITY_AVAILABLE, then *count is the number of discarded events of message. |
| BT_PROPERTY_AVAILABILITY_AVAILABLE | The number of discarded events of message is available. |
| BT_PROPERTY_AVAILABILITY_NOT_AVAILABLE | The number of discarded events of message isn't available. |
NULL. NULL.
|
extern |
Creates a discarded packets message for the stream stream from the message iterator self_message_iterator.
Only use this function if
returns BT_FALSE.
Otherwise, use bt_message_discarded_packets_create_with_default_clock_snapshots().
On success, the returned discarded packets message has the following property values:
| Property | Value |
|---|---|
| Stream | stream |
| Beginning default clock snapshot | None |
| End default clock snapshot | None |
| Discarded packet count | None |
| [in] | self_message_iterator | Self message iterator from which to create the discarded packets message. |
| [in] | stream | Stream from which the packets were discarded. |
NULL on memory error.NULL. NULL. bt_stream_class_discarded_packets_have_default_clock_snapshots(bt_stream_borrow_class_const(stream)) returns BT_FALSE.
|
extern |
Creates a discarded packets message having the beginning and end default clock snapshots with the values beginning_clock_snapshot_value and end_clock_snapshot_value for the stream stream from the message iterator self_message_iterator.
Only use this function if
returns BT_TRUE.
Otherwise, use bt_message_discarded_packets_create().
On success, the returned discarded packets message has the following property values:
| Property | Value |
|---|---|
| Stream | stream |
| Beginning default clock snapshot | Clock snapshot with the value beginning_clock_snapshot_value. |
| End default clock snapshot | Clock snapshot with the value end_clock_snapshot_value. |
| Discarded packet count | None |
| [in] | self_message_iterator | Self message iterator from which to create the discarded packets message. |
| [in] | stream | Stream from which the packets were discarded. |
| [in] | beginning_clock_snapshot_value | Value (clock cycles) of the beginning default clock snapshot of message. |
| [in] | end_clock_snapshot_value | Value (clock cycles) of the end default clock snapshot of message. |
NULL on memory error.NULL. NULL. bt_stream_class_discarded_packets_have_default_clock_snapshots(bt_stream_borrow_class_const(stream)) returns BT_TRUE.
|
extern |
Borrows the stream of the discarded packets message message.
See the stream property.
| [in] | message | Discarded packets message from which to borrow the stream. |
Borrowed reference of the stream of message.
The returned pointer remains valid as long as message exists.
NULL. const version of this function.
|
extern |
Borrows the stream of the discarded packets message message (const version).
|
extern |
Borrows the beginning default clock snapshot of the discarded packets message message.
See the beginning default clock snapshot property.
| [in] | message | Discarded packets message from which to borrow the beginning default clock snapshot. |
NULL.
|
extern |
Borrows the end default clock snapshot of the discarded packets message message.
See the end default clock snapshot property.
| [in] | message | Discarded packets message from which to borrow the end default clock snapshot. |
NULL.
|
extern |
Borrows the default clock class of the stream class of the discarded packets message message.
See the default clock class property of a stream class.
This is a helper which is equivalent to
| [in] | message | Discarded packets message from which to borrow the default clock class of the class of its stream. |
NULL if none.NULL.
|
extern |
Sets the number of discarded packets of the discarded packets message message to count.
See the discarded packet count property.
| [in] | message | Discarded packets message of which to set the number of discarded packets to count. |
| [in] | count | New number of discarded packets of message. |
NULL.
|
extern |
Returns the number of discarded packets of the discarded packets message message.
See the discarded packet count property.
| [in] | message | Discarded packets message of which to get the number of discarded packets. |
| [out] | count | If this function returns BT_PROPERTY_AVAILABILITY_AVAILABLE, then *count is the number of discarded packets of message. |
| BT_PROPERTY_AVAILABILITY_AVAILABLE | The number of discarded packets of message is available. |
| BT_PROPERTY_AVAILABILITY_NOT_AVAILABLE | The number of discarded packets of message isn't available. |
NULL. NULL.
|
extern |
Creates a message iterator inactivity message having a clock snapshot of a fictitious instance of the clock class clock_class with the value clock_snapshot_value from the message iterator self_message_iterator.
On success, the returned message iterator inactivity message has the following property values:
| Property | Value |
|---|---|
| Clock snapshot | Clock snapshot (snapshot of a fictitious instance of clock_class) with the value clock_snapshot_value. |
| [in] | self_message_iterator | Self message iterator from which to create the message iterator inactivity message. |
| [in] | clock_class | Class of the fictitious instance of which clock_snapshot_value is the value of its snapshot. |
| [in] | clock_snapshot_value | Value (clock cycles) of the clock snapshot of message. |
NULL on memory error.NULL. NULL.
|
extern |
Borrows the clock snapshot of the message iterator inactivity message message.
See the clock snapshot property.
| [in] | message | Message iterator inactivity message from which to borrow the clock snapshot. |
NULL.
|
extern |
Increments the reference count of the message message.
| [in] | message | Message of which to increment the reference count. Can be |
|
extern |
Decrements the reference count of the message message.
| [in] | message | Message of which to decrement the reference count. Can be |
|
extern |
Computes the greatest Message Interchange Protocol version which you can use to create a trace processing graph to which you intend to add components described by the component descriptors component_descriptors, and sets *mip_version to the result.
This function is equivalent to calling bt_get_greatest_operative_mip_version_with_restriction() with mip_version_restriction set to NULL (no restriction).
| [in] | component_descriptors | Component descriptors for which to get the supported MIP versions to compute the greatest operative MIP version. |
| [in] | logging_level | Logging level to use when calling the "get supported MIP versions" method for each component descriptor in component_descriptors. |
| [out] | mip_version | On success, *mip_version is the greatest operative MIP version of all the component descriptors in component_descriptors. |
| BT_GET_GREATEST_OPERATIVE_MIP_VERSION_STATUS_OK | Success. |
| BT_GET_GREATEST_OPERATIVE_MIP_VERSION_STATUS_NO_MATCH | No operative MIP version exists for the component descriptors of component_descriptors. |
| BT_GET_GREATEST_OPERATIVE_MIP_VERSION_STATUS_MEMORY_ERROR | Out of memory. |
| BT_GET_GREATEST_OPERATIVE_MIP_VERSION_STATUS_ERROR | Other error. |
NULL. NULL.
|
extern |
Computes the greatest Message Interchange Protocol version, restricted to the set of versions mip_version_restriction, which you can use to create a trace processing graph to which you intend to add components described by the component descriptors component_descriptors, and sets *mip_version to the result.
This function calls the "get supported MIP versions" method for each component descriptor in component_descriptors, and then sets *mip_version to the greatest common (operative) MIP version which is part of the set mip_version_restriction, if any. The "get supported MIP versions" method receives logging_level as its logging_level parameter.
For example, if all the components would support both MIP versions 0 and 1, but mip_version_restriction only contains the [0, 0] range, then this function sets *mip_version to 0.
If mip_version_restriction is NULL, then it's equivalent to the single range [0, 1], that is, all the possible MIP versions as of Babeltrace 2.0.
If this function doesn't find an operative MIP version within mip_version_restriction for the component descriptors of component_descriptors, then it returns BT_GET_GREATEST_OPERATIVE_MIP_VERSION_STATUS_NO_MATCH.
| [in] | component_descriptors | Component descriptors for which to get the supported MIP versions to compute the greatest operative MIP version. |
| [in] | logging_level | Logging level to use when calling the "get supported MIP versions" method for each component descriptor in component_descriptors. |
| [in] | mip_version_restriction | Set of MIP versions of which *mip_version must be part of. Can be |
| [out] | mip_version | On success, *mip_version is the greatest operative MIP version, within mip_version_restriction, of all the component descriptors in component_descriptors. |
| BT_GET_GREATEST_OPERATIVE_MIP_VERSION_STATUS_OK | Success. |
| BT_GET_GREATEST_OPERATIVE_MIP_VERSION_STATUS_NO_MATCH | No operative MIP version exists within mip_version_restriction for the component descriptors of component_descriptors. |
| BT_GET_GREATEST_OPERATIVE_MIP_VERSION_STATUS_MEMORY_ERROR | Out of memory. |
| BT_GET_GREATEST_OPERATIVE_MIP_VERSION_STATUS_ERROR | Other error. |
NULL. NULL, then no upper value within the ranges of mip_version_restriction is greater than 1 (the return value of bt_get_maximal_mip_version()). NULL.
|
extern |
Returns the maximal available Message Interchange Protocol version as of Babeltrace 2.0.
As of Babeltrace 2.0, this function returns 1.
1.12.0