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