Detailed Description

Trace stream.

A stream is a conceptual sequence of messages within a trace:

In the illustration above, notice that:

A stream is a conceptual sequence of messages.

The sequence always starts with a stream beginning message and ends with a stream end message.
A stream is an instance of a stream class.
A trace contains one or more streams.

A stream is a trace IR data object.

A stream is said to be a conceptual sequence of messages because the stream object itself does not contain messages: it only represents a common timeline to which messages are associated.

Components exchange messages, within a trace processing graph, which can belong to different streams, as long as the stream clocks are correlatable.

A typical use case for streams is to use one for each traced CPU. Then the messages related to a given stream are the ones which occured on a given CPU. Other schemes are possible: they are completely application-specific, and Babeltrace 2 does not enforce any specific stream arrangement pattern.

A trace contains streams. All the streams of a given trace, for a given stream class, have unique numeric IDs. Borrow the trace which contains a stream with bt_stream_borrow_trace() or bt_stream_borrow_trace_const().

A stream can conceptually contain a default clock if its class has a default clock class. There's no function to access a stream's default clock because it's a stateful object: messages cannot refer to stateful objects because they must not change while being transported from one component to the other. Instead of having a stream default clock object, messages have a default clock snapshot: this is a snapshot of the value of a stream's default clock (a clock class instance):

In the illustration above, notice that:

Streams (horizontal blue rectangles) are instances of a stream class (orange).
A stream class has a default clock class (orange bell alarm clock).
Each stream has a default clock (yellow bell alarm clock): this is an instance of the stream's class's default clock class.
Each message (objects in blue stream rectangles) created for a given stream has a default clock snapshot (yellow star): this is a snapshot of the stream's default clock.

In other words, a default clock snapshot contains the value of the stream's default clock when this message occured.

To create a stream:

If bt_stream_class_assigns_automatic_stream_id() returns BT_TRUE (the default) for the stream class to use

Use bt_stream_create().

If bt_stream_class_assigns_automatic_stream_id() returns BT_FALSE for the stream class to use

Use bt_stream_create_with_id().

A stream is a shared object: get a new reference with bt_stream_get_ref() and put an existing reference with bt_stream_put_ref().

Some library functions freeze streams on success. The documentation of those functions indicate this postcondition.

The type of a stream is bt_stream.

Properties

A stream has the following property:

Numeric ID

Numeric ID, unique amongst the numeric IDs of the stream's trace's streams for a given stream class. In other words, two streams which belong to the same trace can have the same numeric ID if they aren't instances of the same class.

Depending on whether or not the stream's class automatically assigns stream IDs (see bt_stream_class_assigns_automatic_stream_id()), set the stream's numeric ID on creation with bt_stream_create() or bt_stream_create_with_id().

You cannot change the numeric ID once the stream is created.

Get a stream's numeric ID with bt_stream_get_id().

Optional: Name

Name of the stream.

Use bt_stream_set_name() and bt_stream_get_name().

Optional: User attributes

User attributes of the stream.

User attributes are custom attributes attached to a stream.

Use bt_stream_set_user_attributes(), bt_stream_borrow_user_attributes(), and bt_stream_borrow_user_attributes_const().

Type
typedef struct bt_stream	bt_stream
	Stream.

Creation
bt_stream *	bt_stream_create (bt_stream_class stream_class, bt_trace trace)
	Creates a stream from the stream class stream_class and adds it to the trace trace. More...

bt_stream *	bt_stream_create_with_id (bt_stream_class stream_class, bt_trace trace, uint64_t id)
	Creates a stream with the numeric ID id from the stream class stream_class and adds it to the trace trace. More...

Class access
bt_stream_class *	bt_stream_borrow_class (bt_stream *stream)
	Borrows the class of the stream stream. More...

const bt_stream_class *	bt_stream_borrow_class_const (const bt_stream *stream)
	Borrows the class of the stream stream (`const` version). More...

Trace access
bt_trace *	bt_stream_borrow_trace (bt_stream *stream)
	Borrows the trace which contains the stream stream. More...

const bt_trace *	bt_stream_borrow_trace_const (const bt_stream *stream)
	Borrows the trace which contains the stream stream (`const` version). More...

Properties
enum	bt_stream_set_name_status { BT_STREAM_SET_NAME_STATUS_OK, BT_STREAM_SET_NAME_STATUS_MEMORY_ERROR }
	Status codes for bt_stream_set_name(). More...

typedef enum bt_stream_set_name_status	bt_stream_set_name_status
	Status codes for bt_stream_set_name().

uint64_t	bt_stream_get_id (const bt_stream *stream)
	Returns the numeric ID of the stream stream. More...

bt_stream_set_name_status	bt_stream_set_name (bt_stream stream, const char name)
	Sets the name of the stream stream to a copy of name. More...

const char *	bt_stream_get_name (const bt_stream *stream)
	Returns the name of the stream stream. More...

void	bt_stream_set_user_attributes (bt_stream stream, const bt_value user_attributes)
	Sets the user attributes of the stream stream to user_attributes. More...

bt_value *	bt_stream_borrow_user_attributes (bt_stream *stream)
	Borrows the user attributes of the stream stream. More...

const bt_value *	bt_stream_borrow_user_attributes_const (const bt_stream *stream)
	Borrows the user attributes of the stream stream (`const` version). More...

Reference count
void	bt_stream_get_ref (const bt_stream *stream)
	Increments the reference count of the stream stream. More...

void	bt_stream_put_ref (const bt_stream *stream)
	Decrements the reference count of the stream stream. More...

#define	BT_STREAM_PUT_REF_AND_RESET(_stream)
	Decrements the reference count of the stream _stream, and then sets _stream to `NULL`. More...

#define	BT_STREAM_MOVE_REF(_dst, _src)
	Decrements the reference count of the stream _dst, sets _dst to _src, and then sets _src to `NULL`. More...

Enumeration Type Documentation

◆ bt_stream_set_name_status

enum bt_stream_set_name_status

Status codes for bt_stream_set_name().

Enumerator
BT_STREAM_SET_NAME_STATUS_OK	Success.
BT_STREAM_SET_NAME_STATUS_MEMORY_ERROR	Out of memory.

Macro Definition Documentation

◆ BT_STREAM_PUT_REF_AND_RESET

#define BT_STREAM_PUT_REF_AND_RESET ( _stream )

Decrements the reference count of the stream _stream, and then sets _stream to NULL.

Parameters

_stream

Stream of which to decrement the reference count.

Can contain NULL.

Precondition: _stream is an assignable expression.

◆ BT_STREAM_MOVE_REF

#define BT_STREAM_MOVE_REF	(	_dst,
		_src
	)

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

This macro effectively moves a stream 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_stream_create()

bt_stream* bt_stream_create	(	bt_stream_class *	stream_class,
		bt_trace *	trace
	)

Creates a stream from the stream class stream_class and adds it to the trace trace.

This function instantiates stream_class.

Attention

Only use this function if

bt_stream_class_assigns_automatic_stream_id(stream_class)

returns BT_TRUE.

Otherwise, use bt_stream_create_with_id().

On success, the returned stream has the following property values:

Property	Value
Numeric ID	Automatically assigned by stream_class and trace
Name	None
User attributes	Empty map value

Parameters

[in]	stream_class	Stream class from which to create the stream.
[in]	trace	Trace to add the created stream to.

Returns: New stream reference, or NULL on memory error.

Precondition: stream_class is not NULL.; bt_stream_class_assigns_automatic_stream_id(stream_class) returns BT_TRUE.; trace is not NULL.

Postcondition: On success, stream_class is frozen.; On success, trace is frozen.

See also: bt_stream_create_with_id() — Creates a stream with a specific numeric ID and adds it to a trace.

◆ bt_stream_create_with_id()

bt_stream* bt_stream_create_with_id	(	bt_stream_class *	stream_class,
		bt_trace *	trace,
		uint64_t	id
	)

Creates a stream with the numeric ID id from the stream class stream_class and adds it to the trace trace.

This function instantiates stream_class.

Attention

Only use this function if

bt_stream_class_assigns_automatic_stream_id(stream_class)

returns BT_FALSE.

Otherwise, use bt_stream_create().

On success, the returned stream has the following property values:

Property	Value
Numeric ID	id
Name	None
User attributes	Empty map value

Parameters

[in]	stream_class	Stream class from which to create the stream.
[in]	trace	Trace to add the created stream to.
[in]	id	Numeric ID of the stream to create and add to trace.

Returns: New stream reference, or NULL on memory error.

Precondition: stream_class is not NULL.; bt_stream_class_assigns_automatic_stream_id(stream_class) returns BT_FALSE.; trace is not NULL.; trace does not contain an instance of stream_class with the numeric ID id.

Postcondition: On success, stream_class is frozen.; On success, trace is frozen.

See also: bt_stream_create() — Creates a stream with an automatic numeric ID and adds it to a trace.

◆ bt_stream_borrow_class()

bt_stream_class* bt_stream_borrow_class ( bt_stream * stream )

Borrows the class of the stream stream.

Parameters

[in] stream Stream of which to borrow the class.

Returns: Borrowed reference of the class of stream.

Precondition: stream is not NULL.

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

◆ bt_stream_borrow_class_const()

const bt_stream_class* bt_stream_borrow_class_const ( const bt_stream * stream )

Borrows the class of the stream stream (const version).

See bt_stream_borrow_class().

◆ bt_stream_borrow_trace()

bt_trace* bt_stream_borrow_trace ( bt_stream * stream )

Borrows the trace which contains the stream stream.

Parameters

[in] stream Stream of which to borrow the trace containing it.

Returns: Borrowed reference of the trace containing stream.

Precondition: stream is not NULL.

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

◆ bt_stream_borrow_trace_const()

const bt_trace* bt_stream_borrow_trace_const ( const bt_stream * stream )

Borrows the trace which contains the stream stream (const version).

See bt_stream_borrow_trace().

◆ bt_stream_get_id()

uint64_t bt_stream_get_id ( const bt_stream * stream )

Returns the numeric ID of the stream stream.

See the numeric ID property.

Parameters

[in] stream Stream of which to get the numeric ID.

Returns: Numeric ID of stream.

Precondition: stream is not NULL.

See also: bt_stream_create_with_id() — Creates a stream with a specific numeric ID and adds it to a trace.

◆ bt_stream_set_name()

bt_stream_set_name_status bt_stream_set_name	(	bt_stream *	stream,
		const char *	name
	)

Sets the name of the stream stream to a copy of name.

See the name property.

Parameters

[in]	stream	Stream of which to set the name to name.
[in]	name	New name of stream (copied).

Return values

BT_STREAM_CLASS_SET_NAME_STATUS_OK	Success.
BT_STREAM_CLASS_SET_NAME_STATUS_MEMORY_ERROR	Out of memory.

Precondition: stream is not NULL.; stream is not frozen.; name is not NULL.

See also: bt_stream_get_name() — Returns the name of a stream.

◆ bt_stream_get_name()

const char* bt_stream_get_name ( const bt_stream * stream )

Returns the name of the stream stream.

See the name property.

If stream has no name, this function returns NULL.

Parameters

[in] stream Stream of which to get the name.

Returns

Name of stream, or NULL if none.

The returned pointer remains valid as long as stream is not modified.

Precondition: stream is not NULL.

See also: bt_stream_class_set_name() — Sets the name of a stream.

◆ bt_stream_set_user_attributes()

void bt_stream_set_user_attributes	(	bt_stream *	stream,
		const bt_value *	user_attributes
	)

Sets the user attributes of the stream stream to user_attributes.

See the user attributes property.

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

Parameters

[in]	stream	Stream of which to set the user attributes to user_attributes.
[in]	user_attributes	New user attributes of stream.

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

See also: bt_stream_borrow_user_attributes() — Borrows the user attributes of a stream.

◆ bt_stream_borrow_user_attributes()

bt_value* bt_stream_borrow_user_attributes ( bt_stream * stream )

Borrows the user attributes of the stream stream.

See the user attributes property.

Note: When you create a default stream with bt_stream_create() or bt_stream_create_with_id(), the stream's initial user attributes is an empty map value.

Parameters

[in] stream Stream from which to borrow the user attributes.

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

Precondition: stream is not NULL.

See also: bt_stream_set_user_attributes() — Sets the user attributes of a stream.; bt_stream_borrow_user_attributes_const() — const version of this function.

◆ bt_stream_borrow_user_attributes_const()

const bt_value* bt_stream_borrow_user_attributes_const ( const bt_stream * stream )

Borrows the user attributes of the stream stream (const version).

See bt_stream_borrow_user_attributes().

◆ bt_stream_get_ref()

void bt_stream_get_ref ( const bt_stream * stream )

Increments the reference count of the stream stream.

Parameters

[in]

stream

Stream of which to increment the reference count.

Can be NULL.

See also: bt_stream_put_ref() — Decrements the reference count of a stream.

◆ bt_stream_put_ref()

void bt_stream_put_ref ( const bt_stream * stream )

Decrements the reference count of the stream stream.

Parameters

[in]

stream

Stream of which to decrement the reference count.

Can be NULL.

See also: bt_stream_get_ref() — Increments the reference count of a stream.

Detailed Description

Properties

Type

Creation

Class access

Trace access

Properties

Reference count

Enumeration Type Documentation

◆ bt_stream_set_name_status

Macro Definition Documentation

◆ BT_STREAM_PUT_REF_AND_RESET

◆ BT_STREAM_MOVE_REF

Function Documentation

◆ bt_stream_create()

◆ bt_stream_create_with_id()

◆ bt_stream_borrow_class()

◆ bt_stream_borrow_class_const()

◆ bt_stream_borrow_trace()

◆ bt_stream_borrow_trace_const()

◆ bt_stream_get_id()

◆ bt_stream_set_name()

◆ bt_stream_get_name()

◆ bt_stream_set_user_attributes()

◆ bt_stream_borrow_user_attributes()

◆ bt_stream_borrow_user_attributes_const()

◆ bt_stream_get_ref()

◆ bt_stream_put_ref()