Detailed Description

Trace packet.

A packet is a conceptual container of events within a stream.

Some trace formats group events together within packets. This is the case, for example, of the Common Trace Format.

Because a packet could contain millions of events, there are no actual links from a packet to its events. However, there are links from the events of a packet to it (see bt_event_borrow_packet() and bt_event_borrow_packet_const()).

A packet can contain a context field which is data associated to all the events of the packet.

A packet is a trace IR data object.

A packet conceptually belongs to a stream. Borrow the stream of a packet with bt_packet_borrow_stream() and bt_packet_borrow_stream_const().

Before you create a packet for a given stream, the class of the stream must support packets.

Create a packet with bt_packet_create(). You can then use this packet to create a packet beginning message and a packet end message.

A packet is a shared object: get a new reference with bt_packet_get_ref() and put an existing reference with bt_packet_put_ref().

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

The type of a packet is bt_packet.

Property

A packet has the following property:

Context field

Context field of the packet.

The context of a packet contains data associated to all its events.

The class of the context field of a packet is set at the level of the stream class of the packet. See bt_stream_class_set_packet_context_field_class() bt_stream_class_borrow_packet_context_field_class(), and bt_stream_class_borrow_packet_context_field_class_const()

Use bt_packet_borrow_context_field() and bt_packet_borrow_context_field_const().

Type
typedef struct bt_packet	bt_packet
	Packet.

Creation
bt_packet *	bt_packet_create (const bt_stream *stream)
	Creates a packet for the stream `stream`. More...

Stream access
bt_stream *	bt_packet_borrow_stream (bt_packet *packet)
	Borrows the stream conceptually containing the packet `packet`. More...

const bt_stream *	bt_packet_borrow_stream_const (const bt_packet *packet)
	Borrows the stream conceptually containing the packet `packet` (`const` version). More...

Property
bt_field *	bt_packet_borrow_context_field (bt_packet *packet)
	Borrows the context field of the packet `packet`. More...

const bt_field *	bt_packet_borrow_context_field_const (const bt_packet *packet)
	Borrows the context field of the packet `packet` (`const` version). More...

Reference count
void	bt_packet_get_ref (const bt_packet *packet)
	Increments the reference count of the packet `packet`. More...

void	bt_packet_put_ref (const bt_packet *packet)
	Decrements the reference count of the packet `packet`. More...

#define	BT_PACKET_PUT_REF_AND_RESET(_packet)
	Decrements the reference count of the packet `_packet`, and then sets `_packet` to `NULL`. More...

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

Macro Definition Documentation

#define BT_PACKET_PUT_REF_AND_RESET ( _packet )

Decrements the reference count of the packet _packet, and then sets _packet to NULL.

Parameters

_packet

Packet of which to decrement the reference count.

Can contain NULL.

Precondition: _packet is an assignable expression.

#define BT_PACKET_MOVE_REF	(	_dst,
		_src
	)

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

This macro effectively moves a packet 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_packet* bt_packet_create ( const bt_stream * stream )

Creates a packet for the stream stream.

Attention

Only use this function if

1 bt_stream_class_supports_packets(bt_stream_borrow_class_const(stream))

returns BT_TRUE.

On success, the returned packet has the following property value:

Property	Value
Context field	Unset instance of the packet context field class of the class of `stream`.

Parameters

[in] stream Stream for which to create the packet.

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

Precondition: bt_stream_class_supports_packets(bt_stream_borrow_class_const(stream)) returns BT_TRUE.

bt_stream* bt_packet_borrow_stream ( bt_packet * packet )

Borrows the stream conceptually containing the packet packet.

Parameters

[in] packet Packet of which to borrow the stream conceptually containing it.

Returns: Borrowed reference of the stream conceptually containing packet.

Precondition: packet is not NULL.

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

const bt_stream* bt_packet_borrow_stream_const ( const bt_packet * packet )

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

See bt_packet_borrow_stream().

bt_field* bt_packet_borrow_context_field ( bt_packet * packet )

Borrows the context field of the packet packet.

See the context field property.

Parameters

[in] packet Packet of which to borrow the context field.

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

Precondition: packet is not NULL.

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

const bt_field* bt_packet_borrow_context_field_const ( const bt_packet * packet )

Borrows the context field of the packet packet (const version).

See bt_packet_borrow_context_field().

void bt_packet_get_ref ( const bt_packet * packet )

Increments the reference count of the packet packet.

Parameters

[in]

packet

Packet of which to increment the reference count.

Can be NULL.

See also: bt_packet_put_ref() — Decrements the reference count of a packet.

void bt_packet_put_ref ( const bt_packet * packet )

Decrements the reference count of the packet packet.

Parameters

[in]

packet

Packet of which to decrement the reference count.

Can be NULL.

See also: bt_packet_get_ref() — Increments the reference count of a packet.

Detailed Description

Property

Type

Creation

Stream access

Property

Reference count

Macro Definition Documentation

Function Documentation