Commit | Line | Data |
---|---|---|
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 |
21 | extern "C" { | |
22 | #endif | |
23 | ||
43c59509 PP |
24 | /*! |
25 | @defgroup api-tir-pkt Packet | |
26 | @ingroup api-tir | |
27 | ||
28 | @brief | |
29 | Trace packet. | |
30 | ||
31 | A <strong><em>packet</em></strong> is a conceptual container of | |
32 | \bt_p_ev within a \bt_stream. | |
33 | ||
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>. | |
37 | ||
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()). | |
42 | ||
43 | A packet can contain a context \bt_field which is data associated to | |
44 | all the events of the packet. | |
45 | ||
46 | A packet is a \ref api-tir "trace IR" data object. | |
47 | ||
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(). | |
51 | ||
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". | |
54 | ||
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. | |
57 | ||
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(). | |
61 | ||
62 | Some library functions \ref api-fund-freezing "freeze" packets on | |
63 | success. The documentation of those functions indicate this | |
64 | postcondition. | |
65 | ||
66 | The type of a packet is #bt_packet. | |
67 | ||
68 | <h1>Property</h1> | |
69 | ||
70 | A 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 | ||
126 | On 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 | 150 | extern 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() — | |
174 | \c const version of this function. | |
175 | */ | |
b19ff26f | 176 | extern 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 | ||
183 | See bt_packet_borrow_stream(). | |
184 | */ | |
185 | extern 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 | ||
199 | See 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() — | |
211 | \c const version of this function. | |
212 | */ | |
312c056a | 213 | extern |
b19ff26f | 214 | bt_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 | ||
221 | See bt_packet_borrow_context_field(). | |
222 | */ | |
223 | extern | |
224 | const 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() — | |
247 | Decrements the reference count of a packet. | |
248 | */ | |
249 | extern 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() — | |
264 | Increments the reference count of a packet. | |
265 | */ | |
266 | extern 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 | ||
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. | |
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 */ |