Babeltrace 2 C API
2.1.1
Open-source trace manipulation framework
|
Class of events.
An event class is the class of events, which event messages contain:
In the illustration above, notice that:
An event class is a trace IR metadata object.
An event class is a shared object: get a new reference with bt_event_class_get_ref() and put an existing reference with bt_event_class_put_ref().
Some library functions freeze event classes on success. The documentation of those functions indicate this postcondition.
The type of an event class is bt_event_class.
A stream class contains event classes. All the event classes of a given stream class have unique numeric IDs. Borrow the stream class which contains an event class with bt_event_class_borrow_stream_class() or bt_event_class_borrow_stream_class_const().
To create a default event class:
An event class has the following properties:
Numeric ID, unique amongst the numeric IDs of the event classes of the parent stream class.
Depending on whether or not the stream class of the event class automatically assigns event class IDs (see bt_stream_class_assigns_automatic_event_class_id()), set the numeric ID of the event class on creation with bt_event_class_create() or bt_event_class_create_with_id().
You cannot change the numeric ID once the event class is created.
Get the numeric ID of an event class with bt_event_class_get_id().
Namespace of the event class.
Use bt_event_class_set_namespace() and bt_event_class_get_namespace().
Name of the event class.
Use bt_event_class_set_name() and bt_event_class_get_name().
Unique identifier (UID) of the event class.
Log level of the event class.
The log level of the event class corresponds to the log level of the original instrumentation point of the tracer.
Use bt_event_class_set_log_level() and bt_event_class_get_log_level().
EMF URI of the event class.
Use bt_event_class_set_emf_uri() and bt_event_class_get_emf_uri().
Payload field class of the event class.
The payload of an event class instance (event) contains the main data of the event.
Use bt_event_class_set_payload_field_class() bt_event_class_borrow_payload_field_class(), and bt_event_class_borrow_payload_field_class_const().
Specific context field class of the event class.
The specific context of an event class instance (event) contains any contextual data of which the layout is specific to the class of the event and which doesn't belong to the payload.
Use bt_event_class_set_specific_context_field_class() bt_event_class_borrow_specific_context_field_class(), and bt_event_class_borrow_specific_context_field_class_const().
User attributes of the event class.
User attributes are custom attributes attached to an event class.
Use bt_event_class_set_user_attributes(), bt_event_class_borrow_user_attributes(), and bt_event_class_borrow_user_attributes_const().
Type | |
typedef struct bt_event_class | bt_event_class |
Event class. | |
Creation | |
bt_event_class * | bt_event_class_create (bt_stream_class *stream_class) |
Creates a default event class and adds it to the stream class stream_class . More... | |
bt_event_class * | bt_event_class_create_with_id (bt_stream_class *stream_class, uint64_t id) |
Creates a default event class with the numeric ID id and adds it to the stream class stream_class . More... | |
Stream class access | |
bt_stream_class * | bt_event_class_borrow_stream_class (bt_event_class *event_class) |
Borrows the stream class which contains the event class event_class . More... | |
const bt_stream_class * | bt_event_class_borrow_stream_class_const (const bt_event_class *event_class) |
Borrows the stream class which contains the event class event_class (const version). More... | |
Reference count | |
void | bt_event_class_get_ref (const bt_event_class *event_class) |
Increments the reference count of the event class event_class . More... | |
void | bt_event_class_put_ref (const bt_event_class *event_class) |
Decrements the reference count of the event class event_class . More... | |
#define | BT_EVENT_CLASS_PUT_REF_AND_RESET(_event_class) |
Decrements the reference count of the event class _event_class , and then sets _event_class to NULL . More... | |
#define | BT_EVENT_CLASS_MOVE_REF(_dst, _src) |
Decrements the reference count of the event class _dst , sets _dst to _src , and then sets _src to NULL . More... | |
Status codes for bt_event_class_set_namespace().
Status codes for bt_event_class_set_uid().
Status codes for bt_event_class_set_namespace().
Enumerator | |
---|---|
BT_EVENT_CLASS_SET_NAMESPACE_STATUS_OK |
Success. |
BT_EVENT_CLASS_SET_NAMESPACE_STATUS_MEMORY_ERROR |
Out of memory. |
Status codes for bt_event_class_set_name().
Enumerator | |
---|---|
BT_EVENT_CLASS_SET_NAME_STATUS_OK |
Success. |
BT_EVENT_CLASS_SET_NAME_STATUS_MEMORY_ERROR |
Out of memory. |
Status codes for bt_event_class_set_uid().
Enumerator | |
---|---|
BT_EVENT_CLASS_SET_UID_STATUS_OK |
Success. |
BT_EVENT_CLASS_SET_UID_STATUS_MEMORY_ERROR |
Out of memory. |
Event class log level enumerators.
Status codes for bt_event_class_set_emf_uri().
Enumerator | |
---|---|
BT_EVENT_CLASS_SET_EMF_URI_STATUS_OK |
Success. |
BT_EVENT_CLASS_SET_EMF_URI_STATUS_MEMORY_ERROR |
Out of memory. |
Status codes for bt_event_class_set_payload_field_class() and bt_event_class_set_specific_context_field_class().
Enumerator | |
---|---|
BT_EVENT_CLASS_SET_FIELD_CLASS_STATUS_OK |
Success. |
BT_EVENT_CLASS_SET_FIELD_CLASS_STATUS_MEMORY_ERROR |
Out of memory. |
#define BT_EVENT_CLASS_PUT_REF_AND_RESET | ( | _event_class | ) |
Decrements the reference count of the event class _event_class
, and then sets _event_class
to NULL
.
_event_class | Event class of which to decrement the reference count. Can contain |
_event_class
is an assignable expression. #define BT_EVENT_CLASS_MOVE_REF | ( | _dst, | |
_src | |||
) |
Decrements the reference count of the event class _dst
, sets _dst
to _src
, and then sets _src
to NULL
.
This macro effectively moves an event class reference from the expression _src
to the expression _dst
, putting the existing _dst
reference.
_dst | Destination expression. Can contain |
_src | Source expression. Can contain |
_dst
is an assignable expression. _src
is an assignable expression. bt_event_class* bt_event_class_create | ( | bt_stream_class * | stream_class | ) |
Creates a default event class and adds it to the stream class stream_class
.
Only use this function if
returns BT_TRUE.
Otherwise, use bt_event_class_create_with_id().
On success, the returned event class has the following property values:
Property | Value |
---|---|
Numeric ID | Automatically assigned by stream_class |
Message Interchange Protocol version 1: namespace (available since Babeltrace 2.1) | None |
Name | None |
MIP 1: UID (available since Babeltrace 2.1) | None |
Log level | None |
EMF URI | None |
Payload field class | None |
Specific context field class | None |
User attributes | Empty map value |
[in] | stream_class | Stream class to add the created event class to. |
NULL
on memory error.stream_class
is not NULL
. bt_stream_class_assigns_automatic_event_class_id(stream_class)
returns BT_TRUE.stream_class
is frozen.bt_event_class* bt_event_class_create_with_id | ( | bt_stream_class * | stream_class, |
uint64_t | id | ||
) |
Creates a default event class with the numeric ID id
and adds it to the stream class stream_class
.
Only use this function if
returns BT_FALSE.
Otherwise, use bt_event_class_create().
On success, the returned event class has the following property values:
Property | Value |
---|---|
Numeric ID | id |
Message Interchange Protocol version 1: namespace (available since Babeltrace 2.1) | None |
Name | None |
MIP 1: UID (available since Babeltrace 2.1) | None |
Log level | None |
EMF URI | None |
Payload field class | None |
Specific context field class | None |
User attributes | Empty map value |
[in] | stream_class | Stream class to add the created event class to. |
[in] | id | Numeric ID of the event class to create and add to stream_class . |
NULL
on memory error.stream_class
is not NULL
. bt_stream_class_assigns_automatic_event_class_id(stream_class)
returns BT_FALSE. stream_class
doesn't contain an event class with the numeric ID id
.stream_class
is frozen.bt_stream_class* bt_event_class_borrow_stream_class | ( | bt_event_class * | event_class | ) |
Borrows the stream class which contains the event class event_class
.
[in] | event_class | Event class from which to borrow the stream class which contains it. |
event_class
.event_class
is not NULL
.const
version of this function. const bt_stream_class* bt_event_class_borrow_stream_class_const | ( | const bt_event_class * | event_class | ) |
Borrows the stream class which contains the event class event_class
(const
version).
uint64_t bt_event_class_get_id | ( | const bt_event_class * | event_class | ) |
Returns the numeric ID of the event class event_class
.
See the numeric ID property.
[in] | event_class | Event class of which to get the numeric ID. |
event_class
.event_class
is not NULL
.bt_event_class_set_namespace_status bt_event_class_set_namespace | ( | bt_event_class * | event_class, |
const char * | ns | ||
) |
Sets the namespace of the event class event_class
to a copy of ns
.
See the namespace property.
[in] | event_class | Event class of which to set the namespace to ns . |
[in] | ns | New namespace of event_class (copied). |
BT_EVENT_CLASS_SET_NAMESPACE_STATUS_OK | Success. |
BT_EVENT_CLASS_SET_NAMESPACE_STATUS_MEMORY_ERROR | Out of memory. |
event_class
is not NULL
. event_class
is not frozen. event_class
was created from a component which belongs to a trace processing graph with the effective Message Interchange Protocol version 1. ns
is not NULL
.const char* bt_event_class_get_namespace | ( | const bt_event_class * | event_class | ) |
Returns the namespace of the event class event_class
.
See the namespace property.
If event_class
has no namespace, then this function returns NULL
.
[in] | event_class | Event class of which to get the namespace. |
Namespace of event_class
, or NULL
if none.
The returned pointer remains valid as long as event_class
isn't modified.
event_class
is not NULL
. event_class
was created from a component which belongs to a trace processing graph with the effective Message Interchange Protocol version 1.bt_event_class_set_name_status bt_event_class_set_name | ( | bt_event_class * | event_class, |
const char * | name | ||
) |
Sets the name of the event class event_class
to a copy of name
.
See the name property.
[in] | event_class | Event class of which to set the name to name . |
[in] | name | New name of event_class (copied). |
BT_EVENT_CLASS_SET_NAME_STATUS_OK | Success. |
BT_EVENT_CLASS_SET_NAME_STATUS_MEMORY_ERROR | Out of memory. |
event_class
is not NULL
. event_class
is not frozen. name
is not NULL
.bt_event_class_set_uid_status bt_event_class_set_uid | ( | bt_event_class * | event_class, |
const char * | uid | ||
) |
Sets the unique identifier (UID) of the stream class event_class
to a copy of uid
.
See the UID property.
[in] | event_class | Event class of which to set the UID to uid . |
[in] | uid | New UID of event_class (copied). |
BT_EVENT_CLASS_SET_UID_STATUS_OK | Success. |
BT_EVENT_CLASS_SET_UID_STATUS_MEMORY_ERROR | Out of memory. |
event_class
is not NULL
. event_class
is not frozen. event_class
was created from a component which belongs to a trace processing graph with the effective Message Interchange Protocol version 1. uid
is not NULL
.const char* bt_event_class_get_uid | ( | const bt_event_class * | event_class | ) |
Returns the UID of the event class event_class
.
See the UID property.
If event_class
has no UID, then this function returns NULL
.
[in] | event_class | Event class of which to get the UID. |
UID of event_class
, or NULL
if none.
The returned pointer remains valid as long as event_class
isn't modified.
event_class
is not NULL
. event_class
was created from a component which belongs to a trace processing graph with the effective Message Interchange Protocol version 1.const char* bt_event_class_get_name | ( | const bt_event_class * | event_class | ) |
Returns the name of the event class event_class
.
See the name property.
If event_class
has no name, then this function returns NULL
.
[in] | event_class | Event class of which to get the name. |
Name of event_class
, or NULL
if none.
The returned pointer remains valid as long as event_class
isn't modified.
event_class
is not NULL
.void bt_event_class_set_log_level | ( | bt_event_class * | event_class, |
bt_event_class_log_level | log_level | ||
) |
Sets the log level of the event class event_class
to log_level
.
See the log level property.
[in] | event_class | Event class of which to set the log level to log_level . |
[in] | log_level | New log level of event_class . |
event_class
is not NULL
. event_class
is not frozen.bt_property_availability bt_event_class_get_log_level | ( | const bt_event_class * | event_class, |
bt_event_class_log_level * | log_level | ||
) |
Returns the log level of the event class event_class
.
See the log level property.
[in] | event_class | Event class of which to get the log level. |
[out] | log_level | If this function returns BT_PROPERTY_AVAILABILITY_AVAILABLE, then *log_level is the log level of event_class . |
BT_PROPERTY_AVAILABILITY_AVAILABLE | The log level of event_class is available. |
BT_PROPERTY_AVAILABILITY_NOT_AVAILABLE | The log level of event_class isn't available. |
event_class
is not NULL
. log_level
is not NULL
.bt_event_class_set_emf_uri_status bt_event_class_set_emf_uri | ( | bt_event_class * | event_class, |
const char * | emf_uri | ||
) |
Sets the Eclipse Modeling Framework (EMF) URI of the event class event_class
to a copy of emf_uri
.
See the EMF URI property.
[in] | event_class | Event class of which to set the EMF URI to emf_uri . |
[in] | emf_uri | New EMF URI of event_class (copied). |
BT_EVENT_CLASS_SET_EMF_URI_STATUS_OK | Success. |
BT_EVENT_CLASS_SET_EMF_URI_STATUS_MEMORY_ERROR | Out of memory. |
event_class
is not NULL
. event_class
is not frozen. emf_uri
is not NULL
.const char* bt_event_class_get_emf_uri | ( | const bt_event_class * | event_class | ) |
Returns the Eclipse Modeling Framework (EMF) URI of the event class event_class
.
See the EMF URI property.
If event_class
has no EMF URI, then this function returns NULL
.
[in] | event_class | Event class of which to get the EMF URI. |
EMF URI of event_class
, or NULL
if none.
The returned pointer remains valid as long as event_class
isn't modified.
event_class
is not NULL
.bt_event_class_set_field_class_status bt_event_class_set_payload_field_class | ( | bt_event_class * | event_class, |
bt_field_class * | field_class | ||
) |
Sets the payload field class of the event class event_class
to field_class
.
See the payload field class property.
[in] | event_class | Event class of which to set the payload field class to field_class . |
[in] | field_class | New payload field class of event_class . |
BT_EVENT_CLASS_SET_FIELD_CLASS_STATUS_OK | Success. |
BT_EVENT_CLASS_SET_FIELD_CLASS_STATUS_MEMORY_ERROR | Out of memory. |
event_class
is not NULL
. event_class
is not frozen. field_class
is not NULL
. field_class
is a structure field class. field_class
, or any of its contained field classes, isn't already part of a stream class or of an event class. field_class
has a link to another field class, then it must honor the field class link rules.field_class
is frozen.const
version). bt_field_class* bt_event_class_borrow_payload_field_class | ( | bt_event_class * | event_class | ) |
Borrows the payload field class from the event class event_class
.
See the payload field class property.
If event_class
has no payload field class, then this function returns NULL
.
[in] | event_class | Event class from which to borrow the payload field class. |
event_class
, or NULL
if none.event_class
is not NULL
.const
version of this function. const bt_field_class* bt_event_class_borrow_payload_field_class_const | ( | const bt_event_class * | event_class | ) |
Borrows the payload field class from the event class event_class
(const
version).
bt_event_class_set_field_class_status bt_event_class_set_specific_context_field_class | ( | bt_event_class * | event_class, |
bt_field_class * | field_class | ||
) |
Sets the specific context field class of the event class event_class
to field_class
.
See the specific context field class property.
[in] | event_class | Event class of which to set the specific context field class to field_class . |
[in] | field_class | New specific context field class of event_class . |
BT_EVENT_CLASS_SET_FIELD_CLASS_STATUS_OK | Success. |
BT_EVENT_CLASS_SET_FIELD_CLASS_STATUS_MEMORY_ERROR | Out of memory. |
event_class
is not NULL
. event_class
is not frozen. field_class
is not NULL
. field_class
is a structure field class. field_class
, or any of its contained field classes, isn't already part of a stream class or of an event class. field_class
has a link to another field class, then it must honor the field class link rules.field_class
is frozen.const
version). bt_field_class* bt_event_class_borrow_specific_context_field_class | ( | bt_event_class * | event_class | ) |
Borrows the specific context field class from the event class event_class
.
See the specific context field class property.
If event_class
has no specific context field class, then this function returns NULL
.
[in] | event_class | Event class from which to borrow the specific context field class. |
event_class
, or NULL
if none.event_class
is not NULL
.const
version of this function. const bt_field_class* bt_event_class_borrow_specific_context_field_class_const | ( | const bt_event_class * | event_class | ) |
Borrows the specific context field class from the event class event_class
(const
version).
void bt_event_class_set_user_attributes | ( | bt_event_class * | event_class, |
const bt_value * | user_attributes | ||
) |
Sets the user attributes of the event class event_class
to user_attributes
.
See the user attributes property.
[in] | event_class | Event class of which to set the user attributes to user_attributes . |
[in] | user_attributes | New user attributes of event_class . |
event_class
is not NULL
. event_class
is not frozen. user_attributes
is not NULL
. user_attributes
is a map value (bt_value_is_map() returns BT_TRUE).bt_value* bt_event_class_borrow_user_attributes | ( | bt_event_class * | event_class | ) |
Borrows the user attributes of the event class event_class
.
See the user attributes property.
[in] | event_class | Event class from which to borrow the user attributes. |
event_class
(a map value).event_class
is not NULL
.const
version of this function. const bt_value* bt_event_class_borrow_user_attributes_const | ( | const bt_event_class * | event_class | ) |
Borrows the user attributes of the event class event_class
(const
version).
void bt_event_class_get_ref | ( | const bt_event_class * | event_class | ) |
Increments the reference count of the event class event_class
.
[in] | event_class | Event class of which to increment the reference count. Can be |
void bt_event_class_put_ref | ( | const bt_event_class * | event_class | ) |
Decrements the reference count of the event class event_class
.
[in] | event_class | Event class of which to decrement the reference count. Can be |