52d110ee1372d893eb1ee1c91fccc4362771ef09
[babeltrace.git] / include / babeltrace2 / trace-ir / packet.h
1 #ifndef BABELTRACE2_TRACE_IR_PACKET_H
2 #define BABELTRACE2_TRACE_IR_PACKET_H
3
4 /*
5 * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
6 *
7 * Permission is hereby granted, free of charge, to any person obtaining a copy
8 * of this software and associated documentation files (the "Software"), to deal
9 * in the Software without restriction, including without limitation the rights
10 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
11 * copies of the Software, and to permit persons to whom the Software is
12 * furnished to do so, subject to the following conditions:
13 *
14 * The above copyright notice and this permission notice shall be included in
15 * all copies or substantial portions of the Software.
16 *
17 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
18 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
19 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
20 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
21 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
22 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
23 * SOFTWARE.
24 */
25
26 #ifndef __BT_IN_BABELTRACE_H
27 # error "Please include <babeltrace2/babeltrace.h> instead."
28 #endif
29
30 #include <stdint.h>
31
32 #include <babeltrace2/types.h>
33
34 #ifdef __cplusplus
35 extern "C" {
36 #endif
37
38 /*!
39 @defgroup api-tir-pkt Packet
40 @ingroup api-tir
41
42 @brief
43 Trace packet.
44
45 A <strong><em>packet</em></strong> is a conceptual container of
46 \bt_p_ev within a \bt_stream.
47
48 Some trace formats group events together within packets. This is the
49 case, for example, of the
50 <a href="https://diamon.org/ctf/">Common Trace Format</a>.
51
52 Because a packet could contain millions of events, there are no actual
53 links from a packet to its events. However, there are links from a
54 packet's events to it (see bt_event_borrow_packet() and
55 bt_event_borrow_packet_const()).
56
57 A packet can contain a context \bt_field which is data associated to
58 all the events of the packet.
59
60 A packet is a \ref api-tir "trace IR" data object.
61
62 A packet conceptually belongs to a \bt_stream. Borrow the stream of a
63 packet with bt_packet_borrow_stream() and
64 bt_packet_borrow_stream_const().
65
66 Before you create a packet for a given stream, the stream's class must
67 \ref api-tir-stream-cls-prop-supports-pkt "support packets".
68
69 Create a packet with bt_packet_create(). You can then use this packet to
70 create a \bt_pb_msg and a \bt_pe_msg.
71
72 A packet is a \ref api-fund-shared-object "shared object": get a
73 new reference with bt_packet_get_ref() and put an existing
74 reference with bt_packet_put_ref().
75
76 Some library functions \ref api-fund-freezing "freeze" packets on
77 success. The documentation of those functions indicate this
78 postcondition.
79
80 The type of a packet is #bt_packet.
81
82 <h1>Property</h1>
83
84 A packet has the following property:
85
86 <dl>
87 <dt>\anchor api-tir-pkt-prop-ctx Context field</dt>
88 <dd>
89 Packet's context \bt_field.
90
91 The context of a packet contains data associated to all its
92 events.
93
94 The \ref api-tir-fc "class" of a packet's context field is set
95 at the packet's \bt_stream_cls level. See
96 bt_stream_class_set_packet_context_field_class()
97 bt_stream_class_borrow_packet_context_field_class(),
98 and bt_stream_class_borrow_packet_context_field_class_const()
99
100 Use bt_packet_borrow_context_field() and
101 bt_packet_borrow_context_field_const().
102 </dd>
103 </dl>
104 */
105
106 /*! @{ */
107
108 /*!
109 @name Type
110 @{
111
112 @typedef struct bt_packet bt_packet;
113
114 @brief
115 Packet.
116
117 @}
118 */
119
120 /*!
121 @name Creation
122 @{
123 */
124
125 /*!
126 @brief
127 Creates a packet for the \bt_stream \bt_p{stream}.
128
129 @attention
130 @parblock
131 Only use this function if
132
133 @code
134 bt_stream_class_supports_packets(bt_stream_borrow_class_const(stream))
135 @endcode
136
137 returns #BT_TRUE.
138 @endparblock
139
140 On success, the returned packet has the following property value:
141
142 <table>
143 <tr>
144 <th>Property
145 <th>Value
146 <tr>
147 <td>\ref api-tir-pkt-prop-ctx "Context field"
148 <td>
149 Unset instance of the
150 \ref api-tir-stream-cls-prop-pc-fc "packet context field class" of
151 the \ref api-tir-stream-cls "class" of \bt_p{stream}.
152 </table>
153
154 @param[in] stream
155 Stream for which to create the packet.
156
157 @returns
158 New packet reference, or \c NULL on memory error.
159
160 @pre
161 <code>bt_stream_class_supports_packets(bt_stream_borrow_class_const(stream))</code>
162 returns #BT_TRUE.
163 */
164 extern bt_packet *bt_packet_create(const bt_stream *stream);
165
166 /*! @} */
167
168 /*!
169 @name Stream access
170 @{
171 */
172
173 /*!
174 @brief
175 Borrows the \bt_stream conceptually containing the packet
176 \bt_p{packet}.
177
178 @param[in] packet
179 Packet of which to borrow the stream conceptually containing it.
180
181 @returns
182 \em Borrowed reference of the stream conceptually containing
183 \bt_p{packet}.
184
185 @bt_pre_not_null{packet}
186
187 @sa bt_packet_borrow_stream_const() &mdash;
188 \c const version of this function.
189 */
190 extern bt_stream *bt_packet_borrow_stream(bt_packet *packet);
191
192 /*!
193 @brief
194 Borrows the \bt_stream conceptually containing the packet
195 \bt_p{packet} (\c const version).
196
197 See bt_packet_borrow_stream().
198 */
199 extern const bt_stream *bt_packet_borrow_stream_const(
200 const bt_packet *packet);
201
202 /*! @} */
203
204 /*!
205 @name Property
206 @{
207 */
208
209 /*!
210 @brief
211 Borrows the context \bt_field of the packet \bt_p{packet}.
212
213 See the \ref api-tir-pkt-prop-ctx "context field" property.
214
215 @param[in] packet
216 Packet of which to borrow the context field.
217
218 @returns
219 \em Borrowed reference of the context field of
220 \bt_p{packet}, or \c NULL if none.
221
222 @bt_pre_not_null{packet}
223
224 @sa bt_packet_borrow_context_field_const() &mdash;
225 \c const version of this function.
226 */
227 extern
228 bt_field *bt_packet_borrow_context_field(bt_packet *packet);
229
230 /*!
231 @brief
232 Borrows the context \bt_field of the packet \bt_p{packet}
233 (\c const version).
234
235 See bt_packet_borrow_context_field().
236 */
237 extern
238 const bt_field *bt_packet_borrow_context_field_const(
239 const bt_packet *packet);
240
241 /*! @} */
242
243 /*!
244 @name Reference count
245 @{
246 */
247
248 /*!
249 @brief
250 Increments the \ref api-fund-shared-object "reference count" of
251 the packet \bt_p{packet}.
252
253 @param[in] packet
254 @parblock
255 Packet of which to increment the reference count.
256
257 Can be \c NULL.
258 @endparblock
259
260 @sa bt_packet_put_ref() &mdash;
261 Decrements the reference count of a packet.
262 */
263 extern void bt_packet_get_ref(const bt_packet *packet);
264
265 /*!
266 @brief
267 Decrements the \ref api-fund-shared-object "reference count" of
268 the packet \bt_p{packet}.
269
270 @param[in] packet
271 @parblock
272 Packet of which to decrement the reference count.
273
274 Can be \c NULL.
275 @endparblock
276
277 @sa bt_packet_get_ref() &mdash;
278 Increments the reference count of a packet.
279 */
280 extern void bt_packet_put_ref(const bt_packet *packet);
281
282 /*!
283 @brief
284 Decrements the reference count of the packet
285 \bt_p{_packet}, and then sets \bt_p{_packet} to \c NULL.
286
287 @param _packet
288 @parblock
289 Packet of which to decrement the reference count.
290
291 Can contain \c NULL.
292 @endparblock
293
294 @bt_pre_assign_expr{_packet}
295 */
296 #define BT_PACKET_PUT_REF_AND_RESET(_packet) \
297 do { \
298 bt_packet_put_ref(_packet); \
299 (_packet) = NULL; \
300 } while (0)
301
302 /*!
303 @brief
304 Decrements the reference count of the packet \bt_p{_dst}, sets
305 \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL.
306
307 This macro effectively moves a packet reference from the expression
308 \bt_p{_src} to the expression \bt_p{_dst}, putting the existing
309 \bt_p{_dst} reference.
310
311 @param _dst
312 @parblock
313 Destination expression.
314
315 Can contain \c NULL.
316 @endparblock
317 @param _src
318 @parblock
319 Source expression.
320
321 Can contain \c NULL.
322 @endparblock
323
324 @bt_pre_assign_expr{_dst}
325 @bt_pre_assign_expr{_src}
326 */
327 #define BT_PACKET_MOVE_REF(_dst, _src) \
328 do { \
329 bt_packet_put_ref(_dst); \
330 (_dst) = (_src); \
331 (_src) = NULL; \
332 } while (0)
333
334 /*! @} */
335
336 /*! @} */
337
338 #ifdef __cplusplus
339 }
340 #endif
341
342 #endif /* BABELTRACE2_TRACE_IR_PACKET_H */
This page took 0.038052 seconds and 3 git commands to generate.