include: add IWYU pragmas in private header files
[babeltrace.git] / include / babeltrace2 / trace-ir / packet.h
CommitLineData
f79cf0f0 1/*
0235b0db 2 * SPDX-License-Identifier: MIT
f79cf0f0 3 *
0235b0db 4 * Copyright (C) 2010-2019 EfficiOS Inc. and Linux Foundation
f79cf0f0
PP
5 */
6
0235b0db
MJ
7#ifndef BABELTRACE2_TRACE_IR_PACKET_H
8#define BABELTRACE2_TRACE_IR_PACKET_H
9
f38da6ca
SM
10/* IWYU pragma: private, include <babeltrace2/babeltrace.h> */
11
4fa90f32
PP
12#ifndef __BT_IN_BABELTRACE_H
13# error "Please include <babeltrace2/babeltrace.h> instead."
14#endif
15
d24d5663
PP
16#include <stdint.h>
17
3fadfbc0 18#include <babeltrace2/types.h>
b19ff26f 19
f79cf0f0
PP
20#ifdef __cplusplus
21extern "C" {
22#endif
23
43c59509
PP
24/*!
25@defgroup api-tir-pkt Packet
26@ingroup api-tir
27
28@brief
29 Trace packet.
30
31A <strong><em>packet</em></strong> is a conceptual container of
32\bt_p_ev within a \bt_stream.
33
34Some trace formats group events together within packets. This is the
35case, for example, of the
36<a href="https://diamon.org/ctf/">Common Trace Format</a>.
37
38Because a packet could contain millions of events, there are no actual
39links from a packet to its events. However, there are links from a
40packet's events to it (see bt_event_borrow_packet() and
41bt_event_borrow_packet_const()).
42
43A packet can contain a context \bt_field which is data associated to
44all the events of the packet.
45
46A packet is a \ref api-tir "trace IR" data object.
47
48A packet conceptually belongs to a \bt_stream. Borrow the stream of a
49packet with bt_packet_borrow_stream() and
50bt_packet_borrow_stream_const().
51
52Before you create a packet for a given stream, the stream's class must
53\ref api-tir-stream-cls-prop-supports-pkt "support packets".
54
55Create a packet with bt_packet_create(). You can then use this packet to
56create a \bt_pb_msg and a \bt_pe_msg.
57
58A packet is a \ref api-fund-shared-object "shared object": get a
59new reference with bt_packet_get_ref() and put an existing
60reference with bt_packet_put_ref().
61
62Some library functions \ref api-fund-freezing "freeze" packets on
63success. The documentation of those functions indicate this
64postcondition.
65
66The type of a packet is #bt_packet.
67
68<h1>Property</h1>
69
70A packet has the following property:
71
72<dl>
73 <dt>\anchor api-tir-pkt-prop-ctx Context field</dt>
74 <dd>
75 Packet's context \bt_field.
76
77 The context of a packet contains data associated to all its
78 events.
79
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()
85
86 Use bt_packet_borrow_context_field() and
87 bt_packet_borrow_context_field_const().
88 </dd>
89</dl>
90*/
91
92/*! @{ */
93
94/*!
95@name Type
96@{
97
98@typedef struct bt_packet bt_packet;
99
100@brief
101 Packet.
102
103@}
104*/
105
106/*!
107@name Creation
108@{
109*/
110
111/*!
112@brief
113 Creates a packet for the \bt_stream \bt_p{stream}.
114
115@attention
116 @parblock
117 Only use this function if
118
119 @code
120 bt_stream_class_supports_packets(bt_stream_borrow_class_const(stream))
121 @endcode
122
123 returns #BT_TRUE.
124 @endparblock
125
126On success, the returned packet has the following property value:
127
128<table>
129 <tr>
130 <th>Property
131 <th>Value
132 <tr>
133 <td>\ref api-tir-pkt-prop-ctx "Context field"
134 <td>
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}.
138</table>
139
140@param[in] stream
141 Stream for which to create the packet.
142
143@returns
144 New packet reference, or \c NULL on memory error.
145
146@pre
147 <code>bt_stream_class_supports_packets(bt_stream_borrow_class_const(stream))</code>
148 returns #BT_TRUE.
149*/
58085ca4 150extern bt_packet *bt_packet_create(const bt_stream *stream);
f79cf0f0 151
43c59509
PP
152/*! @} */
153
154/*!
155@name Stream access
156@{
157*/
158
159/*!
160@brief
161 Borrows the \bt_stream conceptually containing the packet
162 \bt_p{packet}.
163
164@param[in] packet
165 Packet of which to borrow the stream conceptually containing it.
166
167@returns
168 \em Borrowed reference of the stream conceptually containing
169 \bt_p{packet}.
170
171@bt_pre_not_null{packet}
172
173@sa bt_packet_borrow_stream_const() &mdash;
174 \c const version of this function.
175*/
b19ff26f 176extern bt_stream *bt_packet_borrow_stream(bt_packet *packet);
f5efa812 177
43c59509
PP
178/*!
179@brief
180 Borrows the \bt_stream conceptually containing the packet
181 \bt_p{packet} (\c const version).
182
183See bt_packet_borrow_stream().
184*/
185extern const bt_stream *bt_packet_borrow_stream_const(
186 const bt_packet *packet);
187
188/*! @} */
189
190/*!
191@name Property
192@{
193*/
194
195/*!
196@brief
197 Borrows the context \bt_field of the packet \bt_p{packet}.
198
199See the \ref api-tir-pkt-prop-ctx "context field" property.
200
201@param[in] packet
202 Packet of which to borrow the context field.
203
204@returns
205 \em Borrowed reference of the context field of
206 \bt_p{packet}, or \c NULL if none.
207
208@bt_pre_not_null{packet}
209
210@sa bt_packet_borrow_context_field_const() &mdash;
211 \c const version of this function.
212*/
312c056a 213extern
b19ff26f 214bt_field *bt_packet_borrow_context_field(bt_packet *packet);
f5efa812 215
43c59509
PP
216/*!
217@brief
218 Borrows the context \bt_field of the packet \bt_p{packet}
219 (\c const version).
220
221See bt_packet_borrow_context_field().
222*/
223extern
224const bt_field *bt_packet_borrow_context_field_const(
225 const bt_packet *packet);
226
227/*! @} */
228
229/*!
230@name Reference count
231@{
232*/
233
234/*!
235@brief
236 Increments the \ref api-fund-shared-object "reference count" of
237 the packet \bt_p{packet}.
238
239@param[in] packet
240 @parblock
241 Packet of which to increment the reference count.
242
243 Can be \c NULL.
244 @endparblock
245
246@sa bt_packet_put_ref() &mdash;
247 Decrements the reference count of a packet.
248*/
249extern void bt_packet_get_ref(const bt_packet *packet);
250
251/*!
252@brief
253 Decrements the \ref api-fund-shared-object "reference count" of
254 the packet \bt_p{packet}.
255
256@param[in] packet
257 @parblock
258 Packet of which to decrement the reference count.
259
260 Can be \c NULL.
261 @endparblock
262
263@sa bt_packet_get_ref() &mdash;
264 Increments the reference count of a packet.
265*/
266extern void bt_packet_put_ref(const bt_packet *packet);
267
268/*!
269@brief
270 Decrements the reference count of the packet
271 \bt_p{_packet}, and then sets \bt_p{_packet} to \c NULL.
272
273@param _packet
274 @parblock
275 Packet of which to decrement the reference count.
276
277 Can contain \c NULL.
278 @endparblock
279
280@bt_pre_assign_expr{_packet}
281*/
282#define BT_PACKET_PUT_REF_AND_RESET(_packet) \
283 do { \
284 bt_packet_put_ref(_packet); \
285 (_packet) = NULL; \
286 } while (0)
287
288/*!
289@brief
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.
292
293This 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.
296
297@param _dst
298 @parblock
299 Destination expression.
300
301 Can contain \c NULL.
302 @endparblock
303@param _src
304 @parblock
305 Source expression.
306
307 Can contain \c NULL.
308 @endparblock
309
310@bt_pre_assign_expr{_dst}
311@bt_pre_assign_expr{_src}
312*/
313#define BT_PACKET_MOVE_REF(_dst, _src) \
314 do { \
315 bt_packet_put_ref(_dst); \
316 (_dst) = (_src); \
317 (_src) = NULL; \
318 } while (0)
319
320/*! @} */
321
322/*! @} */
323
f79cf0f0
PP
324#ifdef __cplusplus
325}
326#endif
327
924dc299 328#endif /* BABELTRACE2_TRACE_IR_PACKET_H */
This page took 0.093532 seconds and 4 git commands to generate.