Babeltrace 2 C API
2.0.0
Open-source trace manipulation framework
|
Trace (set of streams).
A trace is a set of streams with properties:
In the illustration above, notice that a trace is an instance of a trace class and that it contains streams.
Borrow the class of a trace with bt_trace_borrow_class() and bt_trace_borrow_class_const().
A trace is a trace IR data object.
A trace is a shared object: get a new reference with bt_trace_get_ref() and put an existing reference with bt_trace_put_ref().
Some library functions freeze traces on success. The documentation of those functions indicate this postcondition. With a frozen trace, you can still:
The type of a trace is bt_trace.
A trace contains streams. All the streams of a given trace have unique numeric IDs. Get the number of streams in a trace with bt_trace_get_stream_count(). Borrow a specific stream from a trace with bt_trace_borrow_stream_by_index(), bt_trace_borrow_stream_by_index_const(), bt_trace_borrow_stream_by_id(), or bt_trace_borrow_stream_by_id_const().
Create a default trace from a trace class with bt_trace_create().
Add to and remove a destruction listener from a trace with bt_trace_add_destruction_listener() and bt_trace_remove_destruction_listener().
A trace has the following properties:
Name of the trace.
Use bt_trace_set_name() and bt_trace_get_name().
UUID of the trace.
The trace's UUID uniquely identifies the trace.
Use bt_trace_set_uuid() and bt_trace_get_uuid().
Generic key-value store which describes the environment of the trace (for example, the system's hostname, its network address, the tracer's name and version, and the rest).
Trace environment keys are strings while values are signed integers or strings.
Set a trace environment entry's value with bt_trace_set_environment_entry_integer() and bt_trace_set_environment_entry_string().
Get the number of environment entries in a trace with bt_trace_get_environment_entry_count().
Borrow an environment entry from a trace with bt_trace_borrow_environment_entry_value_by_name_const().
User attributes of the trace.
User attributes are custom attributes attached to a trace.
Use bt_trace_set_user_attributes(), bt_trace_borrow_user_attributes(), and bt_trace_borrow_user_attributes_const().
Type | |
typedef struct bt_trace | bt_trace |
Trace. | |
Creation | |
bt_trace * | bt_trace_create (bt_trace_class *trace_class) |
Creates a default trace from the trace class trace_class. More... | |
Class access | |
bt_trace_class * | bt_trace_borrow_class (bt_trace *trace) |
Borrows the class of the trace trace. More... | |
const bt_trace_class * | bt_trace_borrow_class_const (const bt_trace *trace) |
Borrows the class of the trace trace (const version). More... | |
Stream access | |
uint64_t | bt_trace_get_stream_count (const bt_trace *trace) |
Returns the number of streams contained in the trace trace. More... | |
bt_stream * | bt_trace_borrow_stream_by_index (bt_trace *trace, uint64_t index) |
Borrows the stream at index index from the trace trace. More... | |
const bt_stream * | bt_trace_borrow_stream_by_index_const (const bt_trace *trace, uint64_t index) |
Borrows the stream at index index from the trace trace (const version). More... | |
bt_stream * | bt_trace_borrow_stream_by_id (bt_trace *trace, uint64_t id) |
Borrows the stream having the numeric ID id from the trace trace. More... | |
const bt_stream * | bt_trace_borrow_stream_by_id_const (const bt_trace *trace, uint64_t id) |
Borrows the stream having the numeric ID id from the trace trace (const version). More... | |
Properties | |
enum | bt_trace_set_name_status { BT_TRACE_SET_NAME_STATUS_OK, BT_TRACE_SET_NAME_STATUS_MEMORY_ERROR } |
Status codes for bt_trace_set_name(). More... | |
enum | bt_trace_set_environment_entry_status { BT_TRACE_SET_ENVIRONMENT_ENTRY_STATUS_OK, BT_TRACE_SET_ENVIRONMENT_ENTRY_STATUS_MEMORY_ERROR } |
Status codes for bt_trace_set_name(). More... | |
typedef enum bt_trace_set_name_status | bt_trace_set_name_status |
Status codes for bt_trace_set_name(). | |
typedef enum bt_trace_set_environment_entry_status | bt_trace_set_environment_entry_status |
Status codes for bt_trace_set_name(). | |
bt_trace_set_name_status | bt_trace_set_name (bt_trace *trace, const char *name) |
Sets the name of the trace trace to a copy of name. More... | |
const char * | bt_trace_get_name (const bt_trace *trace) |
Returns the name of the trace trace. More... | |
void | bt_trace_set_uuid (bt_trace *trace, bt_uuid uuid) |
Sets the UUID of the trace trace to a copy of uuid. More... | |
bt_uuid | bt_trace_get_uuid (const bt_trace *trace) |
Returns the UUID of the trace trace. More... | |
bt_trace_set_environment_entry_status | bt_trace_set_environment_entry_integer (bt_trace *trace, const char *name, int64_t value) |
Sets the value of the environment entry of the trace trace named name to the signed integer value. More... | |
bt_trace_set_environment_entry_status | bt_trace_set_environment_entry_string (bt_trace *trace, const char *name, const char *value) |
Sets the value of the environment entry of the trace trace named name to the string value. More... | |
uint64_t | bt_trace_get_environment_entry_count (const bt_trace *trace) |
Returns the number of environment entries contained in the trace trace. More... | |
void | bt_trace_borrow_environment_entry_by_index_const (const bt_trace *trace, uint64_t index, const char **name, const bt_value **value) |
Borrows the environment entry at index index from the trace trace, setting *name to its name and *value to its value. More... | |
const bt_value * | bt_trace_borrow_environment_entry_value_by_name_const (const bt_trace *trace, const char *name) |
Borrows the value of the environment entry named name in the trace trace. More... | |
void | bt_trace_set_user_attributes (bt_trace *trace, const bt_value *user_attributes) |
Sets the user attributes of the trace trace to user_attributes. More... | |
bt_value * | bt_trace_borrow_user_attributes (bt_trace *trace) |
Borrows the user attributes of the trace trace. More... | |
const bt_value * | bt_trace_borrow_user_attributes_const (const bt_trace *trace) |
Borrows the user attributes of the trace trace (const version). More... | |
Reference count | |
void | bt_trace_get_ref (const bt_trace *trace) |
Increments the reference count of the trace trace. More... | |
void | bt_trace_put_ref (const bt_trace *trace) |
Decrements the reference count of the trace trace. More... | |
#define | BT_TRACE_PUT_REF_AND_RESET(_trace) |
Decrements the reference count of the trace _trace, and then sets _trace to NULL . More... | |
#define | BT_TRACE_MOVE_REF(_dst, _src) |
Decrements the reference count of the trace _dst, sets _dst to _src, and then sets _src to NULL . More... | |
typedef void(* bt_trace_destruction_listener_func) (const bt_trace *trace, void *user_data) |
User function for bt_trace_add_destruction_listener().
This is the user function type for a trace destruction listener.
[in] | trace | Trace being destroyed (frozen). |
[in] | user_data | User data, as passed as the user_data parameter of bt_trace_add_destruction_listener(). |
NULL
.Status codes for bt_trace_set_name().
Enumerator | |
---|---|
BT_TRACE_SET_NAME_STATUS_OK | Success. |
BT_TRACE_SET_NAME_STATUS_MEMORY_ERROR | Out of memory. |
Status codes for bt_trace_set_name().
Enumerator | |
---|---|
BT_TRACE_SET_ENVIRONMENT_ENTRY_STATUS_OK | Success. |
BT_TRACE_SET_ENVIRONMENT_ENTRY_STATUS_MEMORY_ERROR | Out of memory. |
Status codes for bt_trace_add_destruction_listener().
Enumerator | |
---|---|
BT_TRACE_ADD_LISTENER_STATUS_OK | Success. |
BT_TRACE_ADD_LISTENER_STATUS_MEMORY_ERROR | Out of memory. |
Status codes for bt_trace_remove_destruction_listener().
Enumerator | |
---|---|
BT_TRACE_REMOVE_LISTENER_STATUS_OK | Success. |
BT_TRACE_REMOVE_LISTENER_STATUS_MEMORY_ERROR | Out of memory. |
#define BT_TRACE_PUT_REF_AND_RESET | ( | _trace | ) |
Decrements the reference count of the trace _trace, and then sets _trace to NULL
.
_trace | Trace of which to decrement the reference count. Can contain |
#define BT_TRACE_MOVE_REF | ( | _dst, | |
_src | |||
) |
Decrements the reference count of the trace _dst, sets _dst to _src, and then sets _src to NULL
.
This macro effectively moves a trace 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_trace* bt_trace_create | ( | bt_trace_class * | trace_class | ) |
Creates a default trace from the trace class trace_class.
This function instantiates trace_class.
On success, the returned trace has the following property values:
Property | Value |
---|---|
Name | None |
UUID | None |
Environment | Empty |
User attributes | Empty map value |
[in] | trace_class | Trace class from which to create the default trace. |
NULL
on memory error. bt_trace_class* bt_trace_borrow_class | ( | bt_trace * | trace | ) |
Borrows the class of the trace trace.
[in] | trace | Trace of which to borrow the class. |
NULL
.const
version of this function. const bt_trace_class* bt_trace_borrow_class_const | ( | const bt_trace * | trace | ) |
Borrows the class of the trace trace (const
version).
uint64_t bt_trace_get_stream_count | ( | const bt_trace * | trace | ) |
Returns the number of streams contained in the trace trace.
[in] | trace | Trace of which to get the number of contained streams. |
NULL
. Borrows the stream at index index from the trace trace.
[in] | trace | Trace from which to borrow the stream at index index. |
[in] | index | Index of the stream to borrow from trace. |
Borrowed reference of the stream of trace at index index.
The returned pointer remains valid as long as trace exists.
NULL
. const
version of this function. Borrows the stream at index index from the trace trace (const
version).
Borrows the stream having the numeric ID id from the trace trace.
If there's no stream having the numeric ID id in trace, this function returns NULL
.
[in] | trace | Trace from which to borrow the stream having the numeric ID id. |
[in] | id | ID of the stream to borrow from trace. |
Borrowed reference of the stream of trace having the numeric ID id, or NULL
if none.
The returned pointer remains valid as long as trace exists.
NULL
.const
version of this function. Borrows the stream having the numeric ID id from the trace trace (const
version).
bt_trace_set_name_status bt_trace_set_name | ( | bt_trace * | trace, |
const char * | name | ||
) |
Sets the name of the trace trace to a copy of name.
See the name property.
[in] | trace | Trace of which to set the name to name. |
[in] | name | New name of trace (copied). |
BT_TRACE_SET_NAME_STATUS_OK | Success. |
BT_TRACE_SET_NAME_STATUS_MEMORY_ERROR | Out of memory. |
NULL
. NULL
.const char* bt_trace_get_name | ( | const bt_trace * | trace | ) |
Returns the name of the trace trace.
See the name property.
If trace has no name, this function returns NULL
.
[in] | trace | Trace of which to get the name. |
Name of trace, or NULL
if none.
The returned pointer remains valid as long as trace is not modified.
NULL
.Sets the UUID of the trace trace to a copy of uuid.
See the UUID property.
[in] | trace | Trace of which to set the UUID to uuid. |
[in] | uuid | New UUID of trace (copied). |
NULL
. NULL
.Returns the UUID of the trace trace.
See the UUID property.
If trace has no UUID, this function returns NULL
.
[in] | trace | Trace of which to get the UUID. |
UUID of trace, or NULL
if none.
The returned pointer remains valid as long as trace is not modified.
NULL
.bt_trace_set_environment_entry_status bt_trace_set_environment_entry_integer | ( | bt_trace * | trace, |
const char * | name, | ||
int64_t | value | ||
) |
Sets the value of the environment entry of the trace trace named name to the signed integer value.
See the environment property.
On success, if trace already contains an environment entry named name, this function replaces the existing entry's value with value.
[in] | trace | Trace in which to insert or replace an environment entry named name with the value value. |
[in] | name | Name of the entry to insert or replace in trace (copied). |
[in] | value | Value of the environment entry to insert or replace in trace. |
BT_TRACE_SET_ENVIRONMENT_ENTRY_STATUS_OK | Success. |
BT_TRACE_SET_ENVIRONMENT_ENTRY_STATUS_MEMORY_ERROR | Out of memory. |
NULL
. NULL
.bt_trace_set_environment_entry_status bt_trace_set_environment_entry_string | ( | bt_trace * | trace, |
const char * | name, | ||
const char * | value | ||
) |
Sets the value of the environment entry of the trace trace named name to the string value.
See the environment property.
On success, if trace already contains an environment entry named name, this function replaces the existing entry's value with value.
[in] | trace | Trace in which to insert or replace an environment entry named name with the value value. |
[in] | name | Name of the entry to insert or replace in trace (copied). |
[in] | value | Value of the environment entry to insert or replace in trace. |
BT_TRACE_SET_ENVIRONMENT_ENTRY_STATUS_OK | Success. |
BT_TRACE_SET_ENVIRONMENT_ENTRY_STATUS_MEMORY_ERROR | Out of memory. |
NULL
. NULL
. NULL
.uint64_t bt_trace_get_environment_entry_count | ( | const bt_trace * | trace | ) |
Returns the number of environment entries contained in the trace trace.
See the environment property.
[in] | trace | Trace of which to get the number of environment entries. |
NULL
. void bt_trace_borrow_environment_entry_by_index_const | ( | const bt_trace * | trace, |
uint64_t | index, | ||
const char ** | name, | ||
const bt_value ** | value | ||
) |
Borrows the environment entry at index index from the trace trace, setting *name to its name and *value to its value.
See the environment property.
[in] | trace | Trace from which to borrow the environment entry at index index. |
[in] | index | Index of the environment entry to borrow from trace. |
[in] | name | On success, *name is the name of the environment entry at index index in trace. The returned pointer remains valid as long as trace is not modified. |
[in] | value | On success, *value is a borrowed reference of the environment entry at index index in trace. *value is either a signed integer value (BT_VALUE_TYPE_SIGNED_INTEGER) or a string value (BT_VALUE_TYPE_STRING). The returned pointer remains valid as long as trace is not modified. |
NULL
. NULL
. NULL
.const bt_value* bt_trace_borrow_environment_entry_value_by_name_const | ( | const bt_trace * | trace, |
const char * | name | ||
) |
Borrows the value of the environment entry named name in the trace trace.
See the environment property.
If there's no environment entry named name in trace, this function returns NULL
.
[in] | trace | Trace from which to borrow the value of the environment entry named name. |
[in] | name | Name of the environment entry to borrow from trace. |
Borrowed reference of the value of the environment entry named name in trace.
The returned value is either a signed integer value (BT_VALUE_TYPE_SIGNED_INTEGER) or a string value (BT_VALUE_TYPE_STRING).
The returned pointer remains valid as long as trace is not modified.
NULL
. NULL
. Sets the user attributes of the trace trace to user_attributes.
See the user attributes property.
[in] | trace | Trace of which to set the user attributes to user_attributes. |
[in] | user_attributes | New user attributes of trace. |
NULL
. NULL
. Borrows the user attributes of the trace trace.
See the user attributes property.
[in] | trace | Trace from which to borrow the user attributes. |
NULL
.const
version of this function. Borrows the user attributes of the trace trace (const
version).
bt_trace_add_listener_status bt_trace_add_destruction_listener | ( | const bt_trace * | trace, |
bt_trace_destruction_listener_func | user_func, | ||
void * | user_data, | ||
bt_listener_id * | listener_id | ||
) |
Adds a destruction listener having the function user_func to the trace trace.
All the destruction listener user functions of a trace are called when it's being destroyed.
If listener_id is not NULL
, then this function, on success, sets *listener_id to the ID of the added destruction listener within trace. You can then use this ID to remove the added destruction listener with bt_trace_remove_destruction_listener().
[in] | trace | Trace to add the destruction listener to. |
[in] | user_func | User function of the destruction listener to add to trace. |
[in] | user_data | User data to pass as the user_data parameter of user_func. |
[out] | listener_id | On success and if not NULL , *listener_id is the ID of the added destruction listener within trace. |
BT_TRACE_ADD_LISTENER_STATUS_OK | Success. |
BT_TRACE_ADD_LISTENER_STATUS_MEMORY_ERROR | Out of memory. |
NULL
. NULL
.bt_trace_remove_listener_status bt_trace_remove_destruction_listener | ( | const bt_trace * | trace, |
bt_listener_id | listener_id | ||
) |
Removes the destruction listener having the ID listener_id from the trace trace.
The destruction listener to remove from trace was previously added with bt_trace_add_destruction_listener().
You can call this function when trace is frozen.
[in] | trace | Trace from which to remove the destruction listener having the ID listener_id. |
[in] | listener_id | ID of the destruction listener to remove from trace. |
BT_TRACE_REMOVE_LISTENER_STATUS_OK | Success. |
BT_TRACE_REMOVE_LISTENER_STATUS_MEMORY_ERROR | Out of memory. |
NULL
. void bt_trace_get_ref | ( | const bt_trace * | trace | ) |
Increments the reference count of the trace trace.
[in] | trace | Trace of which to increment the reference count. Can be |
void bt_trace_put_ref | ( | const bt_trace * | trace | ) |
Decrements the reference count of the trace trace.
[in] | trace | Trace of which to decrement the reference count. Can be |