Commit | Line | Data |
---|---|---|
924dc299 PP |
1 | #ifndef BABELTRACE2_TRACE_IR_PACKET_H |
2 | #define BABELTRACE2_TRACE_IR_PACKET_H | |
f79cf0f0 PP |
3 | |
4 | /* | |
bbb7b5f0 | 5 | * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation |
f79cf0f0 PP |
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. | |
f79cf0f0 PP |
24 | */ |
25 | ||
4fa90f32 PP |
26 | #ifndef __BT_IN_BABELTRACE_H |
27 | # error "Please include <babeltrace2/babeltrace.h> instead." | |
28 | #endif | |
29 | ||
d24d5663 PP |
30 | #include <stdint.h> |
31 | ||
3fadfbc0 | 32 | #include <babeltrace2/types.h> |
b19ff26f | 33 | |
f79cf0f0 PP |
34 | #ifdef __cplusplus |
35 | extern "C" { | |
36 | #endif | |
37 | ||
43c59509 PP |
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 | */ | |
58085ca4 | 164 | extern bt_packet *bt_packet_create(const bt_stream *stream); |
f79cf0f0 | 165 | |
43c59509 PP |
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() — | |
188 | \c const version of this function. | |
189 | */ | |
b19ff26f | 190 | extern bt_stream *bt_packet_borrow_stream(bt_packet *packet); |
f5efa812 | 191 | |
43c59509 PP |
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() — | |
225 | \c const version of this function. | |
226 | */ | |
312c056a | 227 | extern |
b19ff26f | 228 | bt_field *bt_packet_borrow_context_field(bt_packet *packet); |
f5efa812 | 229 | |
43c59509 PP |
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() — | |
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() — | |
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 | ||
f79cf0f0 PP |
338 | #ifdef __cplusplus |
339 | } | |
340 | #endif | |
341 | ||
924dc299 | 342 | #endif /* BABELTRACE2_TRACE_IR_PACKET_H */ |