Detailed Description

Trace event.

An event represents a trace event record.

An event is an instance of an event class:

In the illustration above, notice that:

A stream is a conceptual sequence of messages, some of which are event messages.
An event message contains an event.
An event is an instance of an event class.
The payload field of an event is an instance of the payload field class which an event class contains.

Borrow the class of an event with bt_event_borrow_class() and bt_event_borrow_class_const().

An event is a trace IR data object.

You cannot directly create an event: there's no bt_event_create() function. The Babeltrace 2 library creates an event within an event message from an event class. Therefore, to fill the fields of an event, you must first borrow the event from an event message with bt_message_event_borrow_event().

An event is a unique object: it belongs to an event message.

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

The type of an event is bt_event.

An event conceptually belongs to a stream. Borrow the stream of an event with bt_event_borrow_stream() and bt_event_borrow_stream_const().

If the event's stream's class supports packets, the event also belongs to a packet. In that case, borrow the packet of an event with bt_event_borrow_packet() and bt_event_borrow_packet_const().

Because a stream or a packet could contain millions of events, there are no actual links from a stream or from a packet to its events.

Properties

An event has the following properties:

Payload field

Event's payload field.

The payload of an event contains its main trace data.

The class of an event's payload field is set at the event's class level. See bt_event_class_set_payload_field_class(), bt_event_class_borrow_payload_field_class(), and bt_event_class_borrow_payload_field_class_const().

Use bt_event_borrow_payload_field() and bt_event_borrow_payload_field_const().

Specific context field

Event's specific context field.

The specific context of an event contains any contextual data of which the layout is specific to the event's class and which does not belong to the payload.

The class of an event's specific context field is set at the event's class level. See 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()

Use bt_event_borrow_specific_context_field() and bt_event_borrow_specific_context_field_const().

Common context field

Event's common context field.

The common context of an event contains contextual data of which the layout is common to all the event classes of the event's stream's class.

The class of an event's common context field is set at the event's stream class level. See bt_stream_class_set_event_common_context_field_class() bt_stream_class_borrow_event_common_context_field_class(), and bt_stream_class_borrow_event_common_context_field_class_const().

Use bt_event_borrow_common_context_field() and bt_event_borrow_common_context_field_const().

Type
typedef struct bt_event	bt_event
	Event.

Class access
bt_event_class *	bt_event_borrow_class (bt_event *event)
	Borrows the class of the event event. More...

const bt_event_class *	bt_event_borrow_class_const (const bt_event *event)
	Borrows the class of the event event (`const` version). More...

Stream access
bt_stream *	bt_event_borrow_stream (bt_event *event)
	Borrows the stream conceptually containing the event event. More...

const bt_stream *	bt_event_borrow_stream_const (const bt_event *event)
	Borrows the stream conceptually containing the event event (`const` version). More...

Packet access
bt_packet *	bt_event_borrow_packet (bt_event *event)
	Borrows the packet conceptually containing the event event. More...

const bt_packet *	bt_event_borrow_packet_const (const bt_event *event)
	Borrows the packet conceptually containing the event event (`const` version). More...

Properties
bt_field *	bt_event_borrow_payload_field (bt_event *event)
	Borrows the payload field of the event event. More...

const bt_field *	bt_event_borrow_payload_field_const (const bt_event *event)
	Borrows the payload field of the event event (`const` version). More...

bt_field *	bt_event_borrow_specific_context_field (bt_event *event)
	Borrows the specific context field of the event event. More...

const bt_field *	bt_event_borrow_specific_context_field_const (const bt_event *event)
	Borrows the specific context field of the event event (`const` version). More...

bt_field *	bt_event_borrow_common_context_field (bt_event *event)
	Borrows the common context field of the event event. More...

const bt_field *	bt_event_borrow_common_context_field_const (const bt_event *event)
	Borrows the common context field of the event event (`const` version). More...

Function Documentation

◆ bt_event_borrow_class()

bt_event_class* bt_event_borrow_class ( bt_event * event )

Borrows the class of the event event.

Parameters

[in] event Event of which to borrow the class.

Returns: Borrowed reference of the class of event.

Precondition: event is not NULL.

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

◆ bt_event_borrow_class_const()

const bt_event_class* bt_event_borrow_class_const ( const bt_event * event )

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

See bt_event_borrow_class().

◆ bt_event_borrow_stream()

bt_stream* bt_event_borrow_stream ( bt_event * event )

Borrows the stream conceptually containing the event event.

Parameters

[in] event Event of which to borrow the stream conceptually containing it.

Returns: Borrowed reference of the stream conceptually containing event.

Precondition: event is not NULL.

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

◆ bt_event_borrow_stream_const()

const bt_stream* bt_event_borrow_stream_const ( const bt_event * event )

Borrows the stream conceptually containing the event event (const version).

See bt_event_borrow_stream().

◆ bt_event_borrow_packet()

bt_packet* bt_event_borrow_packet ( bt_event * event )

Borrows the packet conceptually containing the event event.

Attention: Only call this function if bt_stream_class_supports_packets() returns BT_TRUE for the stream class of event.

Parameters

[in] event Event of which to borrow the packet conceptually containing it.

Returns: Borrowed reference of the packet conceptually containing event.

Precondition: event is not NULL.

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

◆ bt_event_borrow_packet_const()

const bt_packet* bt_event_borrow_packet_const ( const bt_event * event )

Borrows the packet conceptually containing the event event (const version).

See bt_event_borrow_packet().

◆ bt_event_borrow_payload_field()

bt_field* bt_event_borrow_payload_field ( bt_event * event )

Borrows the payload field of the event event.

See the payload field property.

Parameters

[in] event Event of which to borrow the payload field.

Returns: Borrowed reference of the payload field of event, or NULL if none.

Precondition: event is not NULL.

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

◆ bt_event_borrow_payload_field_const()

const bt_field* bt_event_borrow_payload_field_const ( const bt_event * event )

Borrows the payload field of the event event (const version).

See bt_event_borrow_payload_field().

◆ bt_event_borrow_specific_context_field()

bt_field* bt_event_borrow_specific_context_field ( bt_event * event )

Borrows the specific context field of the event event.

See the specific context field property.

Parameters

[in] event Event of which to borrow the specific context field.

Returns: Borrowed reference of the specific context field of event, or NULL if none.

Precondition: event is not NULL.

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

◆ bt_event_borrow_specific_context_field_const()

const bt_field* bt_event_borrow_specific_context_field_const ( const bt_event * event )

Borrows the specific context field of the event event (const version).

See bt_event_borrow_specific_context_field().

◆ bt_event_borrow_common_context_field()

bt_field* bt_event_borrow_common_context_field ( bt_event * event )

Borrows the common context field of the event event.

See the common context field property.

Parameters

[in] event Event of which to borrow the common context field.

Returns: Borrowed reference of the common context field of event, or NULL if none.

Precondition: event is not NULL.

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

◆ bt_event_borrow_common_context_field_const()

const bt_field* bt_event_borrow_common_context_field_const ( const bt_event * event )

Borrows the common context field of the event event (const version).

See bt_event_borrow_common_context_field().

Detailed Description

Properties

Type

Class access

Stream access

Packet access

Properties

Function Documentation

◆ bt_event_borrow_class()

◆ bt_event_borrow_class_const()

◆ bt_event_borrow_stream()

◆ bt_event_borrow_stream_const()

◆ bt_event_borrow_packet()

◆ bt_event_borrow_packet_const()

◆ bt_event_borrow_payload_field()

◆ bt_event_borrow_payload_field_const()

◆ bt_event_borrow_specific_context_field()

◆ bt_event_borrow_specific_context_field_const()

◆ bt_event_borrow_common_context_field()

◆ bt_event_borrow_common_context_field_const()