2 * SPDX-License-Identifier: MIT
4 * Copyright (C) 2010-2019 EfficiOS Inc. and Linux Foundation
7 #ifndef BABELTRACE2_TRACE_IR_PACKET_H
8 #define BABELTRACE2_TRACE_IR_PACKET_H
10 /* IWYU pragma: private, include <babeltrace2/babeltrace.h> */
12 #ifndef __BT_IN_BABELTRACE_H
13 # error "Please include <babeltrace2/babeltrace.h> instead."
18 #include <babeltrace2/types.h>
25 @defgroup api-tir-pkt Packet
31 A <strong><em>packet</em></strong> is a conceptual container of
32 \bt_p_ev within a \bt_stream.
34 Some trace formats group events together within packets. This is the
35 case, for example, of the
36 <a href="https://diamon.org/ctf/">Common Trace Format</a>.
38 Because a packet could contain millions of events, there are no actual
39 links from a packet to its events. However, there are links from a
40 packet's events to it (see bt_event_borrow_packet() and
41 bt_event_borrow_packet_const()).
43 A packet can contain a context \bt_field which is data associated to
44 all the events of the packet.
46 A packet is a \ref api-tir "trace IR" data object.
48 A packet conceptually belongs to a \bt_stream. Borrow the stream of a
49 packet with bt_packet_borrow_stream() and
50 bt_packet_borrow_stream_const().
52 Before you create a packet for a given stream, the stream's class must
53 \ref api-tir-stream-cls-prop-supports-pkt "support packets".
55 Create a packet with bt_packet_create(). You can then use this packet to
56 create a \bt_pb_msg and a \bt_pe_msg.
58 A packet is a \ref api-fund-shared-object "shared object": get a
59 new reference with bt_packet_get_ref() and put an existing
60 reference with bt_packet_put_ref().
62 Some library functions \ref api-fund-freezing "freeze" packets on
63 success. The documentation of those functions indicate this
66 The type of a packet is #bt_packet.
70 A packet has the following property:
73 <dt>\anchor api-tir-pkt-prop-ctx Context field</dt>
75 Packet's context \bt_field.
77 The context of a packet contains data associated to all its
80 The \ref api-tir-fc "class" of a packet's context field is set
81 at the packet's \bt_stream_cls level. See
82 bt_stream_class_set_packet_context_field_class()
83 bt_stream_class_borrow_packet_context_field_class(),
84 and bt_stream_class_borrow_packet_context_field_class_const()
86 Use bt_packet_borrow_context_field() and
87 bt_packet_borrow_context_field_const().
98 @typedef struct bt_packet bt_packet;
113 Creates a packet for the \bt_stream \bt_p{stream}.
117 Only use this function if
120 bt_stream_class_supports_packets(bt_stream_borrow_class_const(stream))
126 On success, the returned packet has the following property value:
133 <td>\ref api-tir-pkt-prop-ctx "Context field"
135 Unset instance of the
136 \ref api-tir-stream-cls-prop-pc-fc "packet context field class" of
137 the \ref api-tir-stream-cls "class" of \bt_p{stream}.
141 Stream for which to create the packet.
144 New packet reference, or \c NULL on memory error.
147 <code>bt_stream_class_supports_packets(bt_stream_borrow_class_const(stream))</code>
150 extern bt_packet
*bt_packet_create(const bt_stream
*stream
);
161 Borrows the \bt_stream conceptually containing the packet
165 Packet of which to borrow the stream conceptually containing it.
168 \em Borrowed reference of the stream conceptually containing
171 @bt_pre_not_null{packet}
173 @sa bt_packet_borrow_stream_const() —
174 \c const version of this function.
176 extern bt_stream
*bt_packet_borrow_stream(bt_packet
*packet
);
180 Borrows the \bt_stream conceptually containing the packet
181 \bt_p{packet} (\c const version).
183 See bt_packet_borrow_stream().
185 extern const bt_stream
*bt_packet_borrow_stream_const(
186 const bt_packet
*packet
);
197 Borrows the context \bt_field of the packet \bt_p{packet}.
199 See the \ref api-tir-pkt-prop-ctx "context field" property.
202 Packet of which to borrow the context field.
205 \em Borrowed reference of the context field of
206 \bt_p{packet}, or \c NULL if none.
208 @bt_pre_not_null{packet}
210 @sa bt_packet_borrow_context_field_const() —
211 \c const version of this function.
214 bt_field
*bt_packet_borrow_context_field(bt_packet
*packet
);
218 Borrows the context \bt_field of the packet \bt_p{packet}
221 See bt_packet_borrow_context_field().
224 const bt_field
*bt_packet_borrow_context_field_const(
225 const bt_packet
*packet
);
230 @name Reference count
236 Increments the \ref api-fund-shared-object "reference count" of
237 the packet \bt_p{packet}.
241 Packet of which to increment the reference count.
246 @sa bt_packet_put_ref() —
247 Decrements the reference count of a packet.
249 extern void bt_packet_get_ref(const bt_packet
*packet
);
253 Decrements the \ref api-fund-shared-object "reference count" of
254 the packet \bt_p{packet}.
258 Packet of which to decrement the reference count.
263 @sa bt_packet_get_ref() —
264 Increments the reference count of a packet.
266 extern void bt_packet_put_ref(const bt_packet
*packet
);
270 Decrements the reference count of the packet
271 \bt_p{_packet}, and then sets \bt_p{_packet} to \c NULL.
275 Packet of which to decrement the reference count.
280 @bt_pre_assign_expr{_packet}
282 #define BT_PACKET_PUT_REF_AND_RESET(_packet) \
284 bt_packet_put_ref(_packet); \
290 Decrements the reference count of the packet \bt_p{_dst}, sets
291 \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL.
293 This macro effectively moves a packet reference from the expression
294 \bt_p{_src} to the expression \bt_p{_dst}, putting the existing
295 \bt_p{_dst} reference.
299 Destination expression.
310 @bt_pre_assign_expr{_dst}
311 @bt_pre_assign_expr{_src}
313 #define BT_PACKET_MOVE_REF(_dst, _src) \
315 bt_packet_put_ref(_dst); \
328 #endif /* BABELTRACE2_TRACE_IR_PACKET_H */
This page took 0.054692 seconds and 4 git commands to generate.