|
Babeltrace 2 C API
2.0.0
Open-source trace manipulation framework
|
|
Babeltrace 2 C API
2.0.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 stream's class 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 a stream beginning message's stream with bt_message_stream_beginning_borrow_stream() and bt_message_stream_beginning_borrow_stream_const().
Snapshot of the message's stream's default clock when the stream begins.
A stream beginning message can only have a default clock snapshot if its stream's class has a default clock class.
When a stream beginning message has no default clock snapshot, then its time is unknown.
Set a stream beginning message's default clock snapshot with bt_message_stream_beginning_set_default_clock_snapshot().
Borrow a stream beginning message's default clock snapshot 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 a stream end message's stream with bt_message_stream_end_borrow_stream() and bt_message_stream_end_borrow_stream_const().
Snapshot of the message's stream's default clock when the stream ends.
A stream end message can only have a default clock snapshot if its stream's class has a default clock class.
When a stream end message has no default clock snapshot, then its time is unknown.
Set a stream end message's default clock snapshot with bt_message_stream_end_set_default_clock_snapshot().
Borrow a stream end message's default clock snapshot with bt_message_stream_end_borrow_default_clock_snapshot_const().
An event message transports an event and has, possibly, a default clock snapshot.
Within its stream's message sequence, 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 message's event. 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 event message's stream.
An event message's event is initially not set: before you emit the event message from a message iterator's "next" method, 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 message's creation function.
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 an event message's event with bt_message_event_borrow_event() and bt_message_event_borrow_event_const().
Snapshot of the message's stream's default clock when the event occurs.
An event message has a default clock snapshot if its stream's class has a default clock class, and has none otherwise.
Within its message iterator's message sequence, the default clock snapshot of an event message must be greater than or equal to any default clock snapshot of any previous message.
Borrow an event message's default clock snapshot 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 its stream's class supports packets.
For a given packet, there can be only one packet beginning message.
Within its stream's message sequence, 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 a packet beginning message's packet with bt_message_packet_beginning_borrow_packet() and bt_message_packet_beginning_borrow_packet_const().
Snapshot of the message's stream's default clock when the packet begins.
A packet beginning message has a default clock snapshot if:
Within its message iterator's message sequence, the default clock snapshot of a packet beginning message must be greater than or equal to any clock snapshot of any previous message.
Borrow a packet beginning message's default clock snapshot 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 its stream's class supports packets.
For a given packet, there can be only one packet end message.
Within its stream's message sequence, 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 a packet end message's packet with bt_message_packet_end_borrow_packet() and bt_message_packet_end_borrow_packet_const().
Snapshot of the message's stream's default clock when the packet ends.
A packet end message has a default clock snapshot if:
Within its message iterator's message sequence, the default clock snapshot of a packet end message must be greater than or equal to any clock snapshot of any previous message.
Borrow a packet end message's default clock snapshot 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 its stream's class supports discarded events.
Within its stream's message sequence, 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 a discarded events message's stream with bt_message_discarded_events_borrow_stream() and bt_message_discarded_events_borrow_stream_const().
Snapshot of the message's stream's default clock which indicates the beginning of the discarded events time range.
A discarded events message has a beginning default clock snapshot if:
Within its message iterator's message sequence, 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 a discarded events message's beginning default clock snapshot with bt_message_discarded_events_borrow_beginning_default_clock_snapshot_const().
Snapshot of the message's stream's default clock 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, the end default clock snapshot must be greater than or equal to the beginning default clock snapshot.
Within its message iterator's message sequence, 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 a discarded events message's end default clock snapshot 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 its stream's class supports discarded packets.
Within its stream's message sequence, 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 a discarded packets message's stream with bt_message_discarded_packets_borrow_stream() and bt_message_discarded_packets_borrow_stream_const().
Snapshot of the message's stream's default clock which indicates the beginning of the discarded packets time range.
A discarded packets message has a beginning default clock snapshot if:
Within its message iterator's message sequence, 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 a discarded packets message's beginning default clock snapshot with bt_message_discarded_packets_borrow_beginning_default_clock_snapshot_const().
Snapshot of the message's stream's default clock 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, the end default clock snapshot must be greater than or equal to the beginning default clock snapshot.
Within its message iterator's message sequence, 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 a discarded packets message's end default clock snapshot 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 does not 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 message's clock class which indicates the point in time until when there's no messages in the message iterator's message sequence.
Within its message iterator's message sequence, the clock snapshot of a message iterator inactivity message must be greater than or equal to any clock snapshot of any previous message.
Borrow a message iterator inactivity message's clock snapshot 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 exchance messages within a trace processing graph.
The MIP covers everything related to messages and what they contain, as well as how they are 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 Babeltrace 2 project's version. As of Babeltrace 2.0, the only available MIP version is 0.
If what the MIP covers changes in a breaking or semantical way in the future, 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, should the project introduce a new type of field class, the MIP version would be bumped.
A component which cannot honor a given MIP can fail at initialization time, making the corresponding bt_graph_add_*_component*() call fail too. To avoid any surprise, you can 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() to get the greatest (most recent) MIP version you can use.
To get the library's latest MIP version, 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 project's objectives is to bump the MIP version as rarely as possible. When it is 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 module (and its submodules, 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 does not explicitly document a MIP version precondition, it means that the effective MIP version has no effect on said function's behaviour.
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 0) 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.
Modules | |
| Trace IR | |
| Intermediate representation of tracing domain objects and concepts (contents of messages). | |
Type | |
| typedef struct bt_message | bt_message |
| Message. | |
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. More... | |
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. More... | |
| 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. More... | |
| 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. More... | |
| 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. More... | |
| bt_event * | bt_message_event_borrow_event (bt_message *message) |
| Borrows the event of the event message message. More... | |
| const bt_event * | bt_message_event_borrow_event_const (const bt_message *message) |
Borrows the event of the event message message (const version). More... | |
| 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. More... | |
| 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. More... | |
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. More... | |
| 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. More... | |
Message reference count | |
| void | bt_message_get_ref (const bt_message *message) |
| Increments the reference count of the message message. More... | |
| void | bt_message_put_ref (const bt_message *message) |
| Decrements the reference count of the message message. More... | |
| #define | BT_MESSAGE_PUT_REF_AND_RESET(_message) |
Decrements the reference count of the message _message, and then sets _message to NULL. More... | |
| #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. More... | |
| 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().
| #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 |
| bt_message_type bt_message_get_type | ( | const bt_message * | message | ) |
Returns the type enumerator of the message message.
| [in] | message | Message of which to get the type enumerator |
NULL. | bt_message* bt_message_stream_beginning_create | ( | bt_self_message_iterator * | self_message_iterator, |
| const bt_stream * | stream | ||
| ) |
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.| bt_stream* bt_message_stream_beginning_borrow_stream | ( | bt_message * | message | ) |
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. | const bt_stream* bt_message_stream_beginning_borrow_stream_const | ( | const bt_message * | message | ) |
Borrows the stream of the stream beginning message message (const version).
| void bt_message_stream_beginning_set_default_clock_snapshot | ( | bt_message * | message, |
| uint64_t | value | ||
| ) |
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. | bt_message_stream_clock_snapshot_state bt_message_stream_beginning_borrow_default_clock_snapshot_const | ( | const bt_message * | message, |
| const bt_clock_snapshot ** | clock_snapshot | ||
| ) |
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, *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.| const bt_clock_class* bt_message_stream_beginning_borrow_stream_class_default_clock_class_const | ( | const bt_message * | message | ) |
Borrows the default clock class of the stream class of the stream beginning message message.
See the stream class's default clock class property.
This is a helper which is equivalent to
| [in] | message | Stream beginning message from which to borrow its stream's class's default clock class. |
NULL if none.NULL. | bt_message* bt_message_stream_end_create | ( | bt_self_message_iterator * | self_message_iterator, |
| const bt_stream * | stream | ||
| ) |
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.| bt_stream* bt_message_stream_end_borrow_stream | ( | bt_message * | message | ) |
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. | const bt_stream* bt_message_stream_end_borrow_stream_const | ( | const bt_message * | message | ) |
Borrows the stream of the stream end message message (const version).
| void bt_message_stream_end_set_default_clock_snapshot | ( | bt_message * | message, |
| uint64_t | value | ||
| ) |
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. | bt_message_stream_clock_snapshot_state bt_message_stream_end_borrow_default_clock_snapshot_const | ( | const bt_message * | message, |
| const bt_clock_snapshot ** | clock_snapshot | ||
| ) |
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, *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.| const bt_clock_class* bt_message_stream_end_borrow_stream_class_default_clock_class_const | ( | const bt_message * | message | ) |
Borrows the default clock class of the stream class of the stream end message message.
See the stream class's default clock class property.
This is a helper which is equivalent to
| [in] | message | Stream end message from which to borrow its stream's class's default clock class. |
NULL if none.NULL. | 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.
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 are not 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.| 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.
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 are not 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.| 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.
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 are not 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. | 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.
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 are not 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. | bt_event* bt_message_event_borrow_event | ( | bt_message * | message | ) |
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. | 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.
See the default clock snapshot property.
| [in] | message | Event message from which to borrow the default clock snapshot. |
NULL. | 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.
See the stream class's default clock class property.
This is a helper which is equivalent to
| [in] | message | Event message from which to borrow its stream's class's default clock class. |
NULL if none.NULL. | bt_message* bt_message_packet_beginning_create | ( | bt_self_message_iterator * | self_message_iterator, |
| const bt_packet * | packet | ||
| ) |
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)). | bt_message* bt_message_packet_beginning_create_with_default_clock_snapshot | ( | bt_self_message_iterator * | self_message_iterator, |
| const bt_packet * | packet, | ||
| uint64_t | clock_snapshot_value | ||
| ) |
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)). | bt_packet* bt_message_packet_beginning_borrow_packet | ( | bt_message * | message | ) |
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. | const bt_packet* bt_message_packet_beginning_borrow_packet_const | ( | const bt_message * | message | ) |
Borrows the packet of the packet beginning message message (const version).
| const bt_clock_snapshot* bt_message_packet_beginning_borrow_default_clock_snapshot_const | ( | const bt_message * | message | ) |
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. | const bt_clock_class* bt_message_packet_beginning_borrow_stream_class_default_clock_class_const | ( | const bt_message * | message | ) |
Borrows the default clock class of the stream class of the packet beginning message message.
See the stream class's default clock class property.
This is a helper which is equivalent to
| [in] | message | Packet beginning message from which to borrow its stream's class's default clock class. |
NULL if none.NULL. | bt_message* bt_message_packet_end_create | ( | bt_self_message_iterator * | self_message_iterator, |
| const bt_packet * | packet | ||
| ) |
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)). | bt_message* bt_message_packet_end_create_with_default_clock_snapshot | ( | bt_self_message_iterator * | self_message_iterator, |
| const bt_packet * | packet, | ||
| uint64_t | clock_snapshot_value | ||
| ) |
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)). | bt_packet* bt_message_packet_end_borrow_packet | ( | bt_message * | message | ) |
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. | const bt_packet* bt_message_packet_end_borrow_packet_const | ( | const bt_message * | message | ) |
Borrows the packet of the packet end message message (const version).
| const bt_clock_snapshot* bt_message_packet_end_borrow_default_clock_snapshot_const | ( | const bt_message * | message | ) |
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. | const bt_clock_class* bt_message_packet_end_borrow_stream_class_default_clock_class_const | ( | const bt_message * | message | ) |
Borrows the default clock class of the stream class of the packet end message message.
See the stream class's default clock class property.
This is a helper which is equivalent to
| [in] | message | Packet end message from which to borrow its stream's class's default clock class. |
NULL if none.NULL. | bt_message* bt_message_discarded_events_create | ( | bt_self_message_iterator * | self_message_iterator, |
| const bt_stream * | stream | ||
| ) |
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.| bt_message* bt_message_discarded_events_create_with_default_clock_snapshots | ( | bt_self_message_iterator * | self_message_iterator, |
| const bt_stream * | stream, | ||
| uint64_t | beginning_clock_snapshot_value, | ||
| uint64_t | end_clock_snapshot_value | ||
| ) |
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.| bt_stream* bt_message_discarded_events_borrow_stream | ( | bt_message * | message | ) |
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. | const bt_stream* bt_message_discarded_events_borrow_stream_const | ( | const bt_message * | message | ) |
Borrows the stream of the discarded events message message (const version).
| const bt_clock_snapshot* bt_message_discarded_events_borrow_beginning_default_clock_snapshot_const | ( | const bt_message * | message | ) |
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. | const bt_clock_snapshot* bt_message_discarded_events_borrow_end_default_clock_snapshot_const | ( | const bt_message * | message | ) |
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. | const bt_clock_class* bt_message_discarded_events_borrow_stream_class_default_clock_class_const | ( | const bt_message * | message | ) |
Borrows the default clock class of the stream class of the discarded events message message.
See the stream class's default clock class property.
This is a helper which is equivalent to
| [in] | message | Discarded events message from which to borrow its stream's class's default clock class. |
NULL if none.NULL. | void bt_message_discarded_events_set_count | ( | bt_message * | message, |
| uint64_t | count | ||
| ) |
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. | bt_property_availability bt_message_discarded_events_get_count | ( | const bt_message * | message, |
| uint64_t * | count | ||
| ) |
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, *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 is not available. |
NULL. NULL.| bt_message* bt_message_discarded_packets_create | ( | bt_self_message_iterator * | self_message_iterator, |
| const bt_stream * | stream | ||
| ) |
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.| bt_message* bt_message_discarded_packets_create_with_default_clock_snapshots | ( | bt_self_message_iterator * | self_message_iterator, |
| const bt_stream * | stream, | ||
| uint64_t | beginning_clock_snapshot_value, | ||
| uint64_t | end_clock_snapshot_value | ||
| ) |
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.| bt_stream* bt_message_discarded_packets_borrow_stream | ( | bt_message * | message | ) |
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. | const bt_stream* bt_message_discarded_packets_borrow_stream_const | ( | const bt_message * | message | ) |
Borrows the stream of the discarded packets message message (const version).
| const bt_clock_snapshot* bt_message_discarded_packets_borrow_beginning_default_clock_snapshot_const | ( | const bt_message * | message | ) |
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. | const bt_clock_snapshot* bt_message_discarded_packets_borrow_end_default_clock_snapshot_const | ( | const bt_message * | message | ) |
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. | const bt_clock_class* bt_message_discarded_packets_borrow_stream_class_default_clock_class_const | ( | const bt_message * | message | ) |
Borrows the default clock class of the stream class of the discarded packets message message.
See the stream class's default clock class property.
This is a helper which is equivalent to
| [in] | message | Discarded packets message from which to borrow its stream's class's default clock class. |
NULL if none.NULL. | void bt_message_discarded_packets_set_count | ( | bt_message * | message, |
| uint64_t | count | ||
| ) |
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. | bt_property_availability bt_message_discarded_packets_get_count | ( | const bt_message * | message, |
| uint64_t * | count | ||
| ) |
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, *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 is not available. |
NULL. NULL.| 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.
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.| 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.
See the clock snapshot property.
| [in] | message | Message iterator inactivity message from which to borrow the clock snapshot. |
NULL. | void bt_message_get_ref | ( | const bt_message * | message | ) |
Increments the reference count of the message message.
| [in] | message | Message of which to increment the reference count. Can be |
| void bt_message_put_ref | ( | const bt_message * | message | ) |
Decrements the reference count of the message message.
| [in] | message | Message of which to decrement the reference count. Can be |
| bt_get_greatest_operative_mip_version_status bt_get_greatest_operative_mip_version | ( | const bt_component_descriptor_set * | component_descriptors, |
| bt_logging_level | logging_level, | ||
| uint64_t * | mip_version | ||
| ) |
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 calls the "get supported MIP versions" method for each component descriptor in component_descriptors, and then returns the greatest common (operative) MIP version, if any. The "get supported MIP versions" method receives logging_level as its logging_level parameter.
If this function does not find an operative MIP version for the component descriptors of component_descriptors, 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. |
| [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. | uint64_t bt_get_maximal_mip_version | ( | void | ) |
Returns the maximal available Message Interchange Protocol version as of Babeltrace 2.0.
As of Babeltrace 2.0, this function returns 0.
1.8.16