Detailed Description

Class of traces.

A trace class is the class of traces:

In the illustration above, notice that a trace is an instance of a trace class.

A trace class is a trace IR metadata object.

A trace class is a shared object: get a new reference with bt_trace_class_get_ref() and put an existing reference with bt_trace_class_put_ref().

Some library functions freeze trace classes on success. The documentation of those functions indicate this postcondition. With a frozen trace class, you can still:

Create and add a stream classes to it with bt_stream_class_create() or bt_stream_class_create_with_id().
Add a destruction listener to it with bt_trace_class_add_destruction_listener().

The type of a trace class is bt_trace_class.

A trace class contains stream classes. All the stream classes of a given trace class have unique numeric IDs. Get the number of stream classes in a trace class with bt_trace_class_get_stream_class_count(). Borrow a specific stream class from a trace class with bt_trace_class_borrow_stream_class_by_index(), bt_trace_class_borrow_stream_class_by_index_const(), bt_trace_class_borrow_stream_class_by_id(), or bt_trace_class_borrow_stream_class_by_id_const().

Set whether or not the stream classes you create for a trace class get automatic numeric IDs with bt_trace_class_set_assigns_automatic_stream_class_id().

Create a default trace class from a self component with bt_trace_class_create().

Add to and remove a destruction listener from a trace class with bt_trace_class_add_destruction_listener() and bt_trace_class_remove_destruction_listener().

Properties

A trace class has the following properties:

Assigns automatic stream class IDs?

Whether or not the stream classes you create and add to the trace class get numeric IDs automatically.

Depending on the value of this property, to create a stream class and add it to the trace class:

BT_TRUE

Use bt_stream_class_create().

BT_FALSE

Use bt_stream_class_create_with_id().

Use bt_trace_class_set_assigns_automatic_stream_class_id() and bt_trace_class_assigns_automatic_stream_class_id().

Optional: User attributes

User attributes of the trace class.

User attributes are custom attributes attached to a trace class.

Use bt_trace_class_set_user_attributes(), bt_trace_class_borrow_user_attributes(), and bt_trace_class_borrow_user_attributes_const().

Listeners
enum	bt_trace_class_add_listener_status { BT_TRACE_CLASS_ADD_LISTENER_STATUS_OK , BT_TRACE_CLASS_ADD_LISTENER_STATUS_MEMORY_ERROR }
	Status codes for bt_trace_class_add_destruction_listener(). More...

enum	bt_trace_class_remove_listener_status { BT_TRACE_CLASS_REMOVE_LISTENER_STATUS_OK , BT_TRACE_CLASS_REMOVE_LISTENER_STATUS_MEMORY_ERROR }
	Status codes for bt_trace_class_remove_destruction_listener(). More...

typedef void(*	bt_trace_class_destruction_listener_func) (const bt_trace_class trace_class, void user_data)
	User function for bt_trace_class_add_destruction_listener().

typedef enum bt_trace_class_add_listener_status	bt_trace_class_add_listener_status
	Status codes for bt_trace_class_add_destruction_listener().

typedef enum bt_trace_class_remove_listener_status	bt_trace_class_remove_listener_status
	Status codes for bt_trace_class_remove_destruction_listener().

bt_trace_class_add_listener_status	bt_trace_class_add_destruction_listener (const bt_trace_class trace_class, bt_trace_class_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 class trace_class.

bt_trace_class_remove_listener_status	bt_trace_class_remove_destruction_listener (const bt_trace_class *trace_class, bt_listener_id listener_id)
	Removes the destruction listener having the ID listener_id from the trace class trace_class.

Type
typedef struct bt_trace_class	bt_trace_class
	Trace class.

Creation
bt_trace_class *	bt_trace_class_create (bt_self_component *self_component)
	Creates a default trace class from the self component self_component.

Stream class access
uint64_t	bt_trace_class_get_stream_class_count (const bt_trace_class *trace_class)
	Returns the number of stream classes contained in the trace class trace_class.

bt_stream_class *	bt_trace_class_borrow_stream_class_by_index (bt_trace_class *trace_class, uint64_t index)
	Borrows the stream class at index index from the trace class trace_class.

const bt_stream_class *	bt_trace_class_borrow_stream_class_by_index_const (const bt_trace_class *trace_class, uint64_t index)
	Borrows the stream class at index index from the trace class trace_class (`const` version).

bt_stream_class *	bt_trace_class_borrow_stream_class_by_id (bt_trace_class *trace_class, uint64_t id)
	Borrows the stream class having the numeric ID id from the trace class trace_class.

const bt_stream_class *	bt_trace_class_borrow_stream_class_by_id_const (const bt_trace_class *trace_class, uint64_t id)
	Borrows the stream class having the numeric ID id from the trace class trace_class (`const` version).

Properties
void	bt_trace_class_set_assigns_automatic_stream_class_id (bt_trace_class *trace_class, bt_bool assigns_automatic_stream_class_id)
	Sets whether or not the trace class trace_class automatically assigns a numeric ID to a stream class you create and add to it.

bt_bool	bt_trace_class_assigns_automatic_stream_class_id (const bt_trace_class *trace_class)
	Returns whether or not the trace class trace_class automatically assigns a numeric ID to a stream class you create and add to it.

void	bt_trace_class_set_user_attributes (bt_trace_class trace_class, const bt_value user_attributes)
	Sets the user attributes of the trace class trace_class to user_attributes.

bt_value *	bt_trace_class_borrow_user_attributes (bt_trace_class *trace_class)
	Borrows the user attributes of the trace class trace_class.

const bt_value *	bt_trace_class_borrow_user_attributes_const (const bt_trace_class *trace_class)
	Borrows the user attributes of the trace class trace_class (`const` version).

Reference count
void	bt_trace_class_get_ref (const bt_trace_class *trace_class)
	Increments the reference count of the trace class trace_class.

void	bt_trace_class_put_ref (const bt_trace_class *trace_class)
	Decrements the reference count of the trace class trace_class.

#define	BT_TRACE_CLASS_PUT_REF_AND_RESET(_trace_class)
	Decrements the reference count of the trace class _trace_class, and then sets _trace_class to `NULL`.

#define	BT_TRACE_CLASS_MOVE_REF(_dst, _src)
	Decrements the reference count of the trace class _dst, sets _dst to _src, and then sets _src to `NULL`.

Typedef Documentation

◆ bt_trace_class_destruction_listener_func

typedef void(* bt_trace_class_destruction_listener_func) (const bt_trace_class *trace_class, void *user_data)

User function for bt_trace_class_add_destruction_listener().

This is the user function type for a trace class destruction listener.

Parameters

[in]	trace_class	Trace class being destroyed (frozen).
[in]	user_data	User data, as passed as the user_data parameter of bt_trace_class_add_destruction_listener().

Precondition: trace_class is not NULL.

Postcondition: The reference count of trace_class is not changed.; The current thread has no error.

See also: bt_trace_class_add_destruction_listener() — Adds a destruction listener to a trace class.

Enumeration Type Documentation

◆ bt_trace_class_add_listener_status

enum bt_trace_class_add_listener_status

Status codes for bt_trace_class_add_destruction_listener().

Enumerator
BT_TRACE_CLASS_ADD_LISTENER_STATUS_OK	Success.
BT_TRACE_CLASS_ADD_LISTENER_STATUS_MEMORY_ERROR	Out of memory.

◆ bt_trace_class_remove_listener_status

enum bt_trace_class_remove_listener_status

Status codes for bt_trace_class_remove_destruction_listener().

Enumerator
BT_TRACE_CLASS_REMOVE_LISTENER_STATUS_OK	Success.
BT_TRACE_CLASS_REMOVE_LISTENER_STATUS_MEMORY_ERROR	Out of memory.

Macro Definition Documentation

◆ BT_TRACE_CLASS_PUT_REF_AND_RESET

#define BT_TRACE_CLASS_PUT_REF_AND_RESET ( _trace_class )

Decrements the reference count of the trace class _trace_class, and then sets _trace_class to NULL.

Parameters

_trace_class

Trace class of which to decrement the reference count.

Can contain NULL.

Precondition: _trace_class is an assignable expression.

◆ BT_TRACE_CLASS_MOVE_REF

#define BT_TRACE_CLASS_MOVE_REF	(		_dst,
			_src )

Decrements the reference count of the trace class _dst, sets _dst to _src, and then sets _src to NULL.

This macro effectively moves a trace class reference from the expression _src to the expression _dst, putting the existing _dst reference.

Parameters

_dst

Destination expression.

Can contain NULL.

_src

Source expression.

Can contain NULL.

Precondition: _dst is an assignable expression.; _src is an assignable expression.

Function Documentation

◆ bt_trace_class_create()

bt_trace_class * bt_trace_class_create ( bt_self_component * self_component )

extern

Creates a default trace class from the self component self_component.

On success, the returned trace class has the following property values:

Property	Value
Assigns automatic stream class IDs?	Yes
User attributes	Empty map value

Parameters

[in] self_component Self component from which to create the default trace class.

Returns: New trace class reference, or NULL on memory error.

◆ bt_trace_class_get_stream_class_count()

uint64_t bt_trace_class_get_stream_class_count ( const bt_trace_class * trace_class )

extern

Returns the number of stream classes contained in the trace class trace_class.

Parameters

[in] trace_class Trace class of which to get the number of contained stream classes.

Returns: Number of contained stream classes in trace_class.

Precondition: trace_class is not NULL.

◆ bt_trace_class_borrow_stream_class_by_index()

bt_stream_class * bt_trace_class_borrow_stream_class_by_index	(	bt_trace_class *	trace_class,
		uint64_t	index )

extern

Borrows the stream class at index index from the trace class trace_class.

Parameters

[in]	trace_class	Trace class from which to borrow the stream class at index index.
[in]	index	Index of the stream class to borrow from trace_class.

Returns

Borrowed reference of the stream class of trace_class at index index.

The returned pointer remains valid as long as trace_class exists.

Precondition: trace_class is not NULL.; index is less than the number of stream classes in trace_class (as returned by bt_trace_class_get_stream_class_count()).

See also: bt_trace_class_get_stream_class_count() — Returns the number of stream classes contained in a trace class.; bt_trace_class_borrow_stream_class_by_index_const() — const version of this function.

◆ bt_trace_class_borrow_stream_class_by_index_const()

const bt_stream_class * bt_trace_class_borrow_stream_class_by_index_const	(	const bt_trace_class *	trace_class,
		uint64_t	index )

extern

Borrows the stream class at index index from the trace class trace_class (const version).

See bt_trace_class_borrow_stream_class_by_index().

◆ bt_trace_class_borrow_stream_class_by_id()

bt_stream_class * bt_trace_class_borrow_stream_class_by_id	(	bt_trace_class *	trace_class,
		uint64_t	id )

extern

Borrows the stream class having the numeric ID id from the trace class trace_class.

If there's no stream class having the numeric ID id in trace_class, this function returns NULL.

Parameters

[in]	trace_class	Trace class from which to borrow the stream class having the numeric ID id.
[in]	id	ID of the stream class to borrow from trace_class.

Returns

Borrowed reference of the stream class of trace_class having the numeric ID id, or NULL if none.

The returned pointer remains valid as long as trace_class exists.

Precondition: trace_class is not NULL.

See also: bt_trace_class_borrow_stream_class_by_id_const() — const version of this function.

◆ bt_trace_class_borrow_stream_class_by_id_const()

const bt_stream_class * bt_trace_class_borrow_stream_class_by_id_const	(	const bt_trace_class *	trace_class,
		uint64_t	id )

extern

Borrows the stream class having the numeric ID id from the trace class trace_class (const version).

See bt_trace_class_borrow_stream_class_by_id().

◆ bt_trace_class_set_assigns_automatic_stream_class_id()

void bt_trace_class_set_assigns_automatic_stream_class_id	(	bt_trace_class *	trace_class,
		bt_bool	assigns_automatic_stream_class_id )

extern

Sets whether or not the trace class trace_class automatically assigns a numeric ID to a stream class you create and add to it.

See the assigns automatic stream class IDs? property.

Parameters

[in]	trace_class	Trace class of which to set whether or not it assigns automatic stream class IDs.
[in]	assigns_automatic_stream_class_id	BT_TRUE to make trace_class assign automatic stream class IDs.

Precondition: trace_class is not NULL.; trace_class is not frozen.

See also: bt_trace_class_assigns_automatic_stream_class_id() — Returns whether or not a trace class automatically assigns stream class IDs.

◆ bt_trace_class_assigns_automatic_stream_class_id()

bt_bool bt_trace_class_assigns_automatic_stream_class_id ( const bt_trace_class * trace_class )

extern

Returns whether or not the trace class trace_class automatically assigns a numeric ID to a stream class you create and add to it.

See the assigns automatic stream class IDs? property.

Parameters

[in] trace_class Trace class of which to get whether or not it assigns automatic stream class IDs.

Returns: BT_TRUE if trace_class automatically assigns stream class IDs.

Precondition: trace_class is not NULL.

See also: bt_trace_class_set_assigns_automatic_stream_class_id() — Sets whether or not a trace class automatically assigns stream class IDs.

◆ bt_trace_class_set_user_attributes()

void bt_trace_class_set_user_attributes	(	bt_trace_class *	trace_class,
		const bt_value *	user_attributes )

extern

Sets the user attributes of the trace class trace_class to user_attributes.

See the user attributes property.

Note: When you create a default trace class with bt_trace_class_create() or bt_trace_class_create_with_id(), the trace class's initial user attributes is an empty map value. Therefore you can borrow it with bt_trace_class_borrow_user_attributes() and fill it directly instead of setting a new one with this function.

Parameters

[in]	trace_class	Trace class of which to set the user attributes to user_attributes.
[in]	user_attributes	New user attributes of trace_class.

Precondition: trace_class is not NULL.; trace_class is not frozen.; user_attributes is not NULL.; user_attributes is a map value (bt_value_is_map() returns BT_TRUE).

See also: bt_trace_class_borrow_user_attributes() — Borrows the user attributes of a trace class.

◆ bt_trace_class_borrow_user_attributes()

bt_value * bt_trace_class_borrow_user_attributes ( bt_trace_class * trace_class )

extern

Borrows the user attributes of the trace class trace_class.

See the user attributes property.

Note: When you create a default trace class with bt_trace_class_create() or bt_trace_class_create_with_id(), the trace class's initial user attributes is an empty map value.

Parameters

[in] trace_class Trace class from which to borrow the user attributes.

Returns: User attributes of trace_class (a map value).

Precondition: trace_class is not NULL.

See also: bt_trace_class_set_user_attributes() — Sets the user attributes of a trace class.; bt_trace_class_borrow_user_attributes_const() — const version of this function.

◆ bt_trace_class_borrow_user_attributes_const()

const bt_value * bt_trace_class_borrow_user_attributes_const ( const bt_trace_class * trace_class )

extern

Borrows the user attributes of the trace class trace_class (const version).

See bt_trace_class_borrow_user_attributes().

◆ bt_trace_class_add_destruction_listener()

bt_trace_class_add_listener_status bt_trace_class_add_destruction_listener	(	const bt_trace_class *	trace_class,
		bt_trace_class_destruction_listener_func	user_func,
		void *	user_data,
		bt_listener_id *	listener_id )

extern

Adds a destruction listener having the function user_func to the trace class trace_class.

All the destruction listener user functions of a trace class 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_class. You can then use this ID to remove the added destruction listener with bt_trace_class_remove_destruction_listener().

Parameters

[in]	trace_class	Trace class to add the destruction listener to.
[in]	user_func	User function of the destruction listener to add to trace_class.
[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_class.

Return values

BT_TRACE_CLASS_ADD_LISTENER_STATUS_OK	Success.
BT_TRACE_CLASS_ADD_LISTENER_STATUS_MEMORY_ERROR	Out of memory.

Precondition: trace_class is not NULL.; user_func is not NULL.

See also: bt_trace_class_remove_destruction_listener() — Removes a destruction listener from a trace class.

◆ bt_trace_class_remove_destruction_listener()

bt_trace_class_remove_listener_status bt_trace_class_remove_destruction_listener	(	const bt_trace_class *	trace_class,
		bt_listener_id	listener_id )

extern

Removes the destruction listener having the ID listener_id from the trace class trace_class.

The destruction listener to remove from trace_class was previously added with bt_trace_class_add_destruction_listener().

You can call this function when trace_class is frozen.

Parameters

[in]	trace_class	Trace class from which to remove the destruction listener having the ID listener_id.
[in]	listener_id	ID of the destruction listener to remove from trace_class.

Return values

BT_TRACE_CLASS_REMOVE_LISTENER_STATUS_OK	Success.
BT_TRACE_CLASS_REMOVE_LISTENER_STATUS_MEMORY_ERROR	Out of memory.

Precondition: trace_class is not NULL.; listener_id is the ID of an existing destruction listener in trace_class.

See also: bt_trace_class_add_destruction_listener() — Adds a destruction listener to a trace class.

◆ bt_trace_class_get_ref()

void bt_trace_class_get_ref ( const bt_trace_class * trace_class )

extern

Increments the reference count of the trace class trace_class.

Parameters

[in]

trace_class

Trace class of which to increment the reference count.

Can be NULL.

See also: bt_trace_class_put_ref() — Decrements the reference count of a trace class.

◆ bt_trace_class_put_ref()

void bt_trace_class_put_ref ( const bt_trace_class * trace_class )

extern

Decrements the reference count of the trace class trace_class.

Parameters

[in]

trace_class

Trace class of which to decrement the reference count.

Can be NULL.

See also: bt_trace_class_get_ref() — Increments the reference count of a trace class.

Detailed Description

Properties

Listeners

Type

Creation

Stream class access

Properties

Reference count

Typedef Documentation

◆ bt_trace_class_destruction_listener_func

Enumeration Type Documentation

◆ bt_trace_class_add_listener_status

◆ bt_trace_class_remove_listener_status

Macro Definition Documentation

◆ BT_TRACE_CLASS_PUT_REF_AND_RESET

◆ BT_TRACE_CLASS_MOVE_REF

Function Documentation

◆ bt_trace_class_create()

◆ bt_trace_class_get_stream_class_count()

◆ bt_trace_class_borrow_stream_class_by_index()

◆ bt_trace_class_borrow_stream_class_by_index_const()

◆ bt_trace_class_borrow_stream_class_by_id()

◆ bt_trace_class_borrow_stream_class_by_id_const()

◆ bt_trace_class_set_assigns_automatic_stream_class_id()

◆ bt_trace_class_assigns_automatic_stream_class_id()

◆ bt_trace_class_set_user_attributes()

◆ bt_trace_class_borrow_user_attributes()

◆ bt_trace_class_borrow_user_attributes_const()

◆ bt_trace_class_add_destruction_listener()

◆ bt_trace_class_remove_destruction_listener()

◆ bt_trace_class_get_ref()

◆ bt_trace_class_put_ref()