Packet

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 a packet's events 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 stream's class 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

Packet's context field.

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

The class of a packet's context field is set at the packet's stream class level. 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().

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

Stream access
bt_stream *	bt_packet_borrow_stream (bt_packet *packet)
	Borrows the stream conceptually containing the packet packet.
const bt_stream *	bt_packet_borrow_stream_const (const bt_packet *packet)
	Borrows the stream conceptually containing the packet packet (const version).

Property
bt_field *	bt_packet_borrow_context_field (bt_packet *packet)
	Borrows the context field of the packet packet.
const bt_field *	bt_packet_borrow_context_field_const (const bt_packet *packet)
	Borrows the context field of the packet packet (const version).

Reference count
void	bt_packet_get_ref (const bt_packet *packet)
	Increments the reference count of the packet packet.
void	bt_packet_put_ref (const bt_packet *packet)
	Decrements the reference count of the packet packet.
#define	BT_PACKET_PUT_REF_AND_RESET(_packet)
	Decrements the reference count of the packet _packet, and then sets _packet to NULL.
#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.

Type
typedef struct bt_packet	bt_packet
	Packet.

Macro Definition Documentation

BT_PACKET_PUT_REF_AND_RESET

#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.

BT_PACKET_MOVE_REF

#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_create()

bt_packet * bt_packet_create ( const bt_stream * stream )

extern

Creates a packet for the stream stream.

Attention

Only use this function if

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_packet_borrow_stream()

bt_stream * bt_packet_borrow_stream ( bt_packet * packet )

extern

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.

bt_packet_borrow_stream_const()

const bt_stream * bt_packet_borrow_stream_const ( const bt_packet * packet )

extern

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

See bt_packet_borrow_stream().

bt_packet_borrow_context_field()

bt_field * bt_packet_borrow_context_field ( bt_packet * packet )

extern

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.

bt_packet_borrow_context_field_const()

const bt_field * bt_packet_borrow_context_field_const ( const bt_packet * packet )

extern

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

See bt_packet_borrow_context_field().

bt_packet_get_ref()

void bt_packet_get_ref ( const bt_packet * packet )

extern

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.

bt_packet_put_ref()

void bt_packet_put_ref ( const bt_packet * packet )

extern

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.