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 #ifndef __BT_IN_BABELTRACE_H
11 # error "Please include <babeltrace2/babeltrace.h> instead."
16 #include <babeltrace2/types.h>
23 @defgroup api-tir-pkt Packet
29 A <strong><em>packet</em></strong> is a conceptual container of
30 \bt_p_ev within a \bt_stream.
32 Some trace formats group events together within packets. This is the
33 case, for example, of the
34 <a href="https://diamon.org/ctf/">Common Trace Format</a>.
36 Because a packet could contain millions of events, there are no actual
37 links from a packet to its events. However, there are links from a
38 packet's events to it (see bt_event_borrow_packet() and
39 bt_event_borrow_packet_const()).
41 A packet can contain a context \bt_field which is data associated to
42 all the events of the packet.
44 A packet is a \ref api-tir "trace IR" data object.
46 A packet conceptually belongs to a \bt_stream. Borrow the stream of a
47 packet with bt_packet_borrow_stream() and
48 bt_packet_borrow_stream_const().
50 Before you create a packet for a given stream, the stream's class must
51 \ref api-tir-stream-cls-prop-supports-pkt "support packets".
53 Create a packet with bt_packet_create(). You can then use this packet to
54 create a \bt_pb_msg and a \bt_pe_msg.
56 A packet is a \ref api-fund-shared-object "shared object": get a
57 new reference with bt_packet_get_ref() and put an existing
58 reference with bt_packet_put_ref().
60 Some library functions \ref api-fund-freezing "freeze" packets on
61 success. The documentation of those functions indicate this
64 The type of a packet is #bt_packet.
68 A packet has the following property:
71 <dt>\anchor api-tir-pkt-prop-ctx Context field</dt>
73 Packet's context \bt_field.
75 The context of a packet contains data associated to all its
78 The \ref api-tir-fc "class" of a packet's context field is set
79 at the packet's \bt_stream_cls level. See
80 bt_stream_class_set_packet_context_field_class()
81 bt_stream_class_borrow_packet_context_field_class(),
82 and bt_stream_class_borrow_packet_context_field_class_const()
84 Use bt_packet_borrow_context_field() and
85 bt_packet_borrow_context_field_const().
96 @typedef struct bt_packet bt_packet;
111 Creates a packet for the \bt_stream \bt_p{stream}.
115 Only use this function if
118 bt_stream_class_supports_packets(bt_stream_borrow_class_const(stream))
124 On success, the returned packet has the following property value:
131 <td>\ref api-tir-pkt-prop-ctx "Context field"
133 Unset instance of the
134 \ref api-tir-stream-cls-prop-pc-fc "packet context field class" of
135 the \ref api-tir-stream-cls "class" of \bt_p{stream}.
139 Stream for which to create the packet.
142 New packet reference, or \c NULL on memory error.
145 <code>bt_stream_class_supports_packets(bt_stream_borrow_class_const(stream))</code>
148 extern bt_packet
*bt_packet_create(const bt_stream
*stream
);
159 Borrows the \bt_stream conceptually containing the packet
163 Packet of which to borrow the stream conceptually containing it.
166 \em Borrowed reference of the stream conceptually containing
169 @bt_pre_not_null{packet}
171 @sa bt_packet_borrow_stream_const() —
172 \c const version of this function.
174 extern bt_stream
*bt_packet_borrow_stream(bt_packet
*packet
);
178 Borrows the \bt_stream conceptually containing the packet
179 \bt_p{packet} (\c const version).
181 See bt_packet_borrow_stream().
183 extern const bt_stream
*bt_packet_borrow_stream_const(
184 const bt_packet
*packet
);
195 Borrows the context \bt_field of the packet \bt_p{packet}.
197 See the \ref api-tir-pkt-prop-ctx "context field" property.
200 Packet of which to borrow the context field.
203 \em Borrowed reference of the context field of
204 \bt_p{packet}, or \c NULL if none.
206 @bt_pre_not_null{packet}
208 @sa bt_packet_borrow_context_field_const() —
209 \c const version of this function.
212 bt_field
*bt_packet_borrow_context_field(bt_packet
*packet
);
216 Borrows the context \bt_field of the packet \bt_p{packet}
219 See bt_packet_borrow_context_field().
222 const bt_field
*bt_packet_borrow_context_field_const(
223 const bt_packet
*packet
);
228 @name Reference count
234 Increments the \ref api-fund-shared-object "reference count" of
235 the packet \bt_p{packet}.
239 Packet of which to increment the reference count.
244 @sa bt_packet_put_ref() —
245 Decrements the reference count of a packet.
247 extern void bt_packet_get_ref(const bt_packet
*packet
);
251 Decrements the \ref api-fund-shared-object "reference count" of
252 the packet \bt_p{packet}.
256 Packet of which to decrement the reference count.
261 @sa bt_packet_get_ref() —
262 Increments the reference count of a packet.
264 extern void bt_packet_put_ref(const bt_packet
*packet
);
268 Decrements the reference count of the packet
269 \bt_p{_packet}, and then sets \bt_p{_packet} to \c NULL.
273 Packet of which to decrement the reference count.
278 @bt_pre_assign_expr{_packet}
280 #define BT_PACKET_PUT_REF_AND_RESET(_packet) \
282 bt_packet_put_ref(_packet); \
288 Decrements the reference count of the packet \bt_p{_dst}, sets
289 \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL.
291 This macro effectively moves a packet reference from the expression
292 \bt_p{_src} to the expression \bt_p{_dst}, putting the existing
293 \bt_p{_dst} reference.
297 Destination expression.
308 @bt_pre_assign_expr{_dst}
309 @bt_pre_assign_expr{_src}
311 #define BT_PACKET_MOVE_REF(_dst, _src) \
313 bt_packet_put_ref(_dst); \
326 #endif /* BABELTRACE2_TRACE_IR_PACKET_H */
This page took 0.03817 seconds and 4 git commands to generate.