Commit | Line | Data |
---|---|---|
adc315b8 JG |
1 | #ifndef BABELTRACE_CTF_IR_STREAM_CLASS_H |
2 | #define BABELTRACE_CTF_IR_STREAM_CLASS_H | |
3 | ||
4 | /* | |
5 | * BabelTrace - CTF IR: Stream Class | |
6 | * | |
de9dd397 | 7 | * Copyright 2014 Jérémie Galarneau <jeremie.galarneau@efficios.com> |
adc315b8 JG |
8 | * |
9 | * Author: Jérémie Galarneau <jeremie.galarneau@efficios.com> | |
10 | * | |
11 | * Permission is hereby granted, free of charge, to any person obtaining a copy | |
12 | * of this software and associated documentation files (the "Software"), to deal | |
13 | * in the Software without restriction, including without limitation the rights | |
14 | * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell | |
15 | * copies of the Software, and to permit persons to whom the Software is | |
16 | * furnished to do so, subject to the following conditions: | |
17 | * | |
18 | * The above copyright notice and this permission notice shall be included in | |
19 | * all copies or substantial portions of the Software. | |
20 | * | |
21 | * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR | |
22 | * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, | |
23 | * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE | |
24 | * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER | |
25 | * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, | |
26 | * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE | |
27 | * SOFTWARE. | |
28 | * | |
29 | * The Common Trace Format (CTF) Specification is available at | |
30 | * http://www.efficios.com/ctf | |
31 | */ | |
32 | ||
48d711a2 | 33 | #include <stdint.h> |
e0831b38 | 34 | |
5fe68922 PP |
35 | /* For bt_get() */ |
36 | #include <babeltrace/ref.h> | |
37 | ||
839d52a5 | 38 | /* For bt_visitor */ |
8bf65fbd | 39 | #include <babeltrace/ctf-ir/visitor.h> |
48d711a2 | 40 | |
adc315b8 JG |
41 | #ifdef __cplusplus |
42 | extern "C" { | |
43 | #endif | |
44 | ||
594a3fb7 PP |
45 | /** |
46 | @defgroup ctfirstreamclass CTF IR stream class | |
47 | @ingroup ctfir | |
48 | @brief CTF IR stream class. | |
49 | ||
6dd2bd0c PP |
50 | @code |
51 | #include <babeltrace/ctf-ir/stream-class.h> | |
52 | @endcode | |
53 | ||
319f672c | 54 | @note |
dfeca116 PP |
55 | See \ref ctfwriterstreamclass which documents additional CTF IR stream |
56 | class functions exclusive to the CTF writer mode. | |
319f672c | 57 | |
594a3fb7 PP |
58 | A CTF IR <strong><em>stream class</em></strong> is a template that you |
59 | can use to create concrete \link ctfirstream CTF IR streams\endlink. | |
60 | ||
61 | A stream class has the following properties, both of which \em must | |
62 | be unique amongst all the stream classes contained in the same | |
63 | \link ctfirtraceclass CTF IR trace class\endlink: | |
64 | ||
65 | - A \b name. | |
66 | - A numeric \b ID. | |
67 | ||
68 | In the Babeltrace CTF IR system, a \link ctfirtraceclass trace class\endlink | |
69 | contains zero or more stream classes, | |
70 | and a stream class contains zero or more | |
71 | \link ctfireventclass event classes\endlink. | |
72 | You can add an event class | |
839d52a5 | 73 | to a stream class with bt_stream_class_add_event_class(). |
594a3fb7 | 74 | You can add a stream class to a trace class with |
839d52a5 | 75 | bt_trace_add_stream_class(). |
594a3fb7 PP |
76 | |
77 | A stream class owns three \link ctfirfieldtypes field types\endlink: | |
78 | ||
79 | - An optional <strong>stream packet context</strong> field type, which | |
80 | represents the \c stream.packet.context CTF scope. | |
81 | - An optional <strong>stream event header</strong> field type, which | |
82 | represents the \c stream.event.header CTF scope. | |
83 | - An optional <strong>stream event context</strong> field type, which | |
84 | represents the \c stream.event.context CTF scope. | |
85 | ||
86 | Those three field types \em must be structure field types as of | |
87 | Babeltrace \btversion. | |
88 | ||
89 | As per the CTF specification, the event header field type \em must | |
90 | contain a field named \c id if the stream class contains more than one | |
91 | event class. | |
92 | ||
93 | As a reminder, here's the structure of a CTF packet: | |
94 | ||
95 | @imgpacketstructure | |
96 | ||
97 | Before you can create a stream from a stream class with | |
839d52a5 PP |
98 | bt_stream_create(), you \em must add the prepared stream class to a |
99 | trace class by calling bt_trace_add_stream_class(). | |
594a3fb7 PP |
100 | |
101 | As with any Babeltrace object, CTF IR stream class objects have | |
102 | <a href="https://en.wikipedia.org/wiki/Reference_counting">reference | |
103 | counts</a>. See \ref refs to learn more about the reference counting | |
104 | management of Babeltrace objects. | |
105 | ||
106 | The following functions \em freeze their stream class parameter on | |
107 | success: | |
108 | ||
839d52a5 PP |
109 | - bt_trace_add_stream_class() |
110 | - bt_event_create() | |
111 | - bt_writer_create_stream() | |
dfeca116 | 112 | (\link ctfwriter CTF writer\endlink mode only) |
594a3fb7 PP |
113 | |
114 | You cannot modify a frozen stream class: it is considered immutable, | |
115 | except for: | |
116 | ||
117 | - Adding an event class to it with | |
839d52a5 | 118 | bt_stream_class_add_event_class(). If the stream class's parent |
e0e2946b | 119 | \link ctfirtraceclass trace class\endlink is static, however, |
839d52a5 PP |
120 | you cannot call bt_stream_class_add_event_class() |
121 | (see bt_trace_is_static() and bt_trace_set_is_static()). | |
594a3fb7 PP |
122 | - \link refs Reference counting\endlink. |
123 | ||
124 | @sa ctfirstream | |
125 | @sa ctfireventclass | |
126 | @sa ctfirtraceclass | |
dfeca116 | 127 | @sa ctfwriterstreamclass |
594a3fb7 PP |
128 | |
129 | @file | |
130 | @brief CTF IR stream class type and functions. | |
131 | @sa ctfirstreamclass | |
132 | ||
133 | @addtogroup ctfirstreamclass | |
134 | @{ | |
135 | */ | |
136 | ||
137 | /** | |
839d52a5 | 138 | @struct bt_stream_class |
594a3fb7 PP |
139 | @brief A CTF IR stream class. |
140 | @sa ctfirstreamclass | |
141 | */ | |
839d52a5 PP |
142 | struct bt_stream_class; |
143 | struct bt_event_class; | |
144 | struct bt_clock; | |
a6918753 PP |
145 | struct bt_event_header_field; |
146 | struct bt_packet_context_field; | |
adc315b8 | 147 | |
594a3fb7 PP |
148 | /** |
149 | @name Creation and parent access functions | |
150 | @{ | |
151 | */ | |
152 | ||
153 | /** | |
154 | @brief Creates a default CTF IR stream class named \p name, or a | |
155 | default unnamed stream class if \p name is \c NULL. | |
156 | ||
157 | On success, the packet context field type of the created stream class | |
158 | has the following fields: | |
159 | ||
160 | - <code>timestamp_begin</code>: a 64-bit unsigned integer field type. | |
161 | - <code>timestamp_end</code>: a 64-bit unsigned integer field type. | |
162 | - <code>content_size</code>: a 64-bit unsigned integer field type. | |
163 | - <code>packet_size</code>: a 64-bit unsigned integer field type. | |
164 | - <code>events_discarded</code>: a 64-bit unsigned integer field type. | |
165 | ||
166 | On success, the event header field type of the created stream class | |
167 | has the following fields: | |
168 | ||
169 | - <code>code</code>: a 32-bit unsigned integer field type. | |
170 | - <code>timestamp</code>: a 64-bit unsigned integer field type. | |
171 | ||
172 | You can modify those default field types after the stream class is | |
8deee039 PP |
173 | created with bt_stream_class_set_packet_context_field_type() and |
174 | bt_stream_class_set_event_header_field_type(). | |
594a3fb7 | 175 | |
e0e2946b PP |
176 | @param[in] name Name of the stream class to create (copied on success), |
177 | or \c NULL to create an unnamed stream class. | |
178 | @returns Created default stream class, or \c NULL on error. | |
594a3fb7 PP |
179 | |
180 | @postsuccessrefcountret1 | |
e0e2946b | 181 | |
839d52a5 | 182 | @sa bt_stream_class_create_empty(): Creates an empty stream class. |
594a3fb7 | 183 | */ |
839d52a5 | 184 | extern struct bt_stream_class *bt_stream_class_create(const char *name); |
adc315b8 | 185 | |
5fe68922 PP |
186 | extern struct bt_trace *bt_stream_class_borrow_trace( |
187 | struct bt_stream_class *stream_class); | |
188 | ||
594a3fb7 PP |
189 | /** |
190 | @brief Returns the parent CTF IR trace class of the CTF IR stream | |
191 | class \p stream_class. | |
192 | ||
193 | It is possible that the stream class was not added to a trace class | |
194 | yet, in which case this function returns \c NULL. You can add a | |
195 | stream class to a trace class with | |
839d52a5 | 196 | bt_trace_add_stream_class(). |
594a3fb7 PP |
197 | |
198 | @param[in] stream_class Stream class of which to get the parent | |
199 | trace class. | |
200 | @returns Parent trace class of \p stream_class, | |
201 | or \c NULL if \p stream_class was not | |
202 | added to a trace class yet or on error. | |
203 | ||
204 | @prenotnull{stream_class} | |
c2f29fb9 | 205 | @postrefcountsame{stream_class} |
594a3fb7 PP |
206 | @postsuccessrefcountretinc |
207 | ||
839d52a5 | 208 | @sa bt_trace_add_stream_class(): Add a stream class to |
594a3fb7 PP |
209 | a trace class. |
210 | */ | |
5fe68922 PP |
211 | static inline |
212 | struct bt_trace *bt_stream_class_get_trace( | |
213 | struct bt_stream_class *stream_class) | |
214 | { | |
215 | return bt_get(bt_stream_class_borrow_trace(stream_class)); | |
216 | } | |
142c5610 | 217 | |
594a3fb7 PP |
218 | /** @} */ |
219 | ||
220 | /** | |
221 | @name Properties functions | |
222 | @{ | |
223 | */ | |
224 | ||
225 | /** | |
226 | @brief Returns the name of the CTF IR stream class \p stream_class. | |
227 | ||
228 | On success, \p stream_class remains the sole owner of the returned | |
229 | string. | |
230 | ||
231 | @param[in] stream_class Stream class of which to get the name. | |
232 | @returns Name of stream class \p stream_class, or | |
233 | \c NULL if \p stream_class is unnamed or | |
234 | on error. | |
235 | ||
236 | @prenotnull{stream_class} | |
237 | @postrefcountsame{stream_class} | |
238 | ||
839d52a5 | 239 | @sa bt_stream_class_set_name(): Sets the name of a given |
594a3fb7 PP |
240 | stream class. |
241 | */ | |
839d52a5 PP |
242 | extern const char *bt_stream_class_get_name( |
243 | struct bt_stream_class *stream_class); | |
69dc4535 | 244 | |
594a3fb7 PP |
245 | /** |
246 | @brief Sets the name of the CTF IR stream class | |
a262eee7 PP |
247 | \p stream_class to \p name, or resets the name of |
248 | \p stream_class. | |
594a3fb7 | 249 | |
a262eee7 PP |
250 | If \p name is not \c NULL, it must be unique amongst the names of all |
251 | the stream classes of the trace class to which you eventually add | |
252 | \p stream_class. | |
594a3fb7 PP |
253 | |
254 | @param[in] stream_class Stream class of which to set the name. | |
a262eee7 PP |
255 | @param[in] name Name of the stream class (copied on success), or |
256 | \c NULL to reset the name of \p stream_class | |
257 | (make it unnamed). | |
594a3fb7 PP |
258 | @returns 0 on success, or a negative value on error. |
259 | ||
260 | @prenotnull{stream_class} | |
594a3fb7 PP |
261 | @prehot{stream_class} |
262 | @postrefcountsame{stream_class} | |
263 | ||
839d52a5 | 264 | @sa bt_stream_class_get_name(): Returns the name of a given |
594a3fb7 PP |
265 | stream class. |
266 | */ | |
839d52a5 PP |
267 | extern int bt_stream_class_set_name( |
268 | struct bt_stream_class *stream_class, const char *name); | |
3ea33115 | 269 | |
594a3fb7 PP |
270 | /** |
271 | @brief Returns the numeric ID of the CTF IR stream class \p stream_class. | |
2f100782 | 272 | |
594a3fb7 PP |
273 | @param[in] stream_class Stream class of which to get the numeric ID. |
274 | @returns ID of stream class \p stream_class, or a | |
275 | negative value on error. | |
276 | ||
277 | @prenotnull{stream_class} | |
278 | @postrefcountsame{stream_class} | |
279 | ||
839d52a5 | 280 | @sa bt_stream_class_set_id(): Sets the numeric ID of a given |
594a3fb7 PP |
281 | stream class. |
282 | */ | |
839d52a5 PP |
283 | extern int64_t bt_stream_class_get_id( |
284 | struct bt_stream_class *stream_class); | |
2f100782 | 285 | |
594a3fb7 PP |
286 | /** |
287 | @brief Sets the numeric ID of the CTF IR stream class | |
288 | \p stream_class to \p id. | |
289 | ||
290 | \p id must be unique amongst the IDs of all the stream classes | |
291 | of the trace class to which you eventually add \p stream_class. | |
292 | ||
293 | @param[in] stream_class Stream class of which to set the numeric ID. | |
294 | @param[in] id ID of the stream class. | |
295 | @returns 0 on success, or a negative value on error. | |
296 | ||
297 | @prenotnull{stream_class} | |
298 | @prehot{stream_class} | |
9ac68eb1 | 299 | @pre \p id is lesser than or equal to 9223372036854775807 (\c INT64_MAX). |
594a3fb7 PP |
300 | @postrefcountsame{stream_class} |
301 | ||
839d52a5 | 302 | @sa bt_stream_class_get_id(): Returns the numeric ID of a given |
594a3fb7 PP |
303 | stream class. |
304 | */ | |
839d52a5 PP |
305 | extern int bt_stream_class_set_id( |
306 | struct bt_stream_class *stream_class, uint64_t id); | |
2f100782 | 307 | |
594a3fb7 | 308 | /** @} */ |
adc315b8 | 309 | |
594a3fb7 PP |
310 | /** |
311 | @name Contained field types functions | |
312 | @{ | |
313 | */ | |
69dc4535 | 314 | |
5fe68922 PP |
315 | extern struct bt_field_type *bt_stream_class_borrow_packet_context_field_type( |
316 | struct bt_stream_class *stream_class); | |
317 | ||
594a3fb7 PP |
318 | /** |
319 | @brief Returns the packet context field type of the CTF IR stream class | |
320 | \p stream_class. | |
69dc4535 | 321 | |
594a3fb7 PP |
322 | @param[in] stream_class Stream class of which to get the packet |
323 | context field type. | |
324 | @returns Packet context field type of \p stream_class, | |
6b783f49 JG |
325 | or \c NULL if \p stream_class has no packet context |
326 | field type or on error. | |
69dc4535 | 327 | |
594a3fb7 | 328 | @prenotnull{stream_class} |
c2f29fb9 | 329 | @postrefcountsame{stream_class} |
6b783f49 JG |
330 | @post <strong>On success, if the return value is a field type</strong>, its |
331 | reference count is incremented. | |
0863f950 | 332 | |
8deee039 | 333 | @sa bt_stream_class_set_packet_context_field_type(): Sets the packet |
594a3fb7 PP |
334 | context field type of a given stream class. |
335 | */ | |
5fe68922 PP |
336 | static inline |
337 | struct bt_field_type *bt_stream_class_get_packet_context_field_type( | |
338 | struct bt_stream_class *stream_class) | |
339 | { | |
340 | return bt_get(bt_stream_class_borrow_packet_context_field_type( | |
341 | stream_class)); | |
342 | } | |
12c8a1a3 | 343 | |
a6918753 PP |
344 | extern |
345 | struct bt_packet_context_field *bt_stream_class_create_packet_context_field( | |
346 | struct bt_stream_class *stream_class); | |
347 | ||
594a3fb7 PP |
348 | /** |
349 | @brief Sets the packet context field type of the CTF IR stream class | |
6b783f49 JG |
350 | \p stream_class to \p packet_context_type, or unsets the current packet |
351 | context field type from \p stream_class. | |
352 | ||
353 | If \p packet_context_type is \c NULL, then this function unsets the current | |
354 | packet context field type from \p stream_class, effectively making | |
355 | \p stream_class a stream class without a packet context field type. | |
594a3fb7 | 356 | |
6b783f49 JG |
357 | As of Babeltrace \btversion, if \p packet_context_type is not \c NULL, |
358 | \p packet_context_type \em must be a CTF IR structure field type object. | |
594a3fb7 PP |
359 | |
360 | @param[in] stream_class Stream class of which to set the packet | |
361 | context field type. | |
6b783f49 JG |
362 | @param[in] packet_context_type Packet context field type, or \c NULL to unset |
363 | the current packet context field type. | |
594a3fb7 PP |
364 | @returns 0 on success, or a negative value on error. |
365 | ||
366 | @prenotnull{stream_class} | |
594a3fb7 | 367 | @prehot{stream_class} |
6b783f49 JG |
368 | @pre <strong>\p packet_context_type, if not \c NULL</strong>, is a CTF IR |
369 | structure field type. | |
594a3fb7 | 370 | @postrefcountsame{stream_class} |
6b783f49 JG |
371 | @post <strong>On success, if \p packet_context_type is not \c NULL</strong>, |
372 | the reference count of \p packet_context_type is incremented. | |
594a3fb7 | 373 | |
8deee039 | 374 | @sa bt_stream_class_get_packet_context_field_type(): Returns the packet |
594a3fb7 PP |
375 | context field type of a given stream class. |
376 | */ | |
8deee039 | 377 | extern int bt_stream_class_set_packet_context_field_type( |
839d52a5 PP |
378 | struct bt_stream_class *stream_class, |
379 | struct bt_field_type *packet_context_type); | |
12c8a1a3 | 380 | |
5fe68922 PP |
381 | extern struct bt_field_type * |
382 | bt_stream_class_borrow_event_header_field_type( | |
383 | struct bt_stream_class *stream_class); | |
384 | ||
594a3fb7 PP |
385 | /** |
386 | @brief Returns the event header field type of the CTF IR stream class | |
387 | \p stream_class. | |
388 | ||
389 | @param[in] stream_class Stream class of which to get the event header | |
390 | field type. | |
391 | @returns Event header field type of \p stream_class, | |
6b783f49 JG |
392 | or \c NULL if \p stream_class has no event header field |
393 | type or on error. | |
594a3fb7 PP |
394 | |
395 | @prenotnull{stream_class} | |
c2f29fb9 | 396 | @postrefcountsame{stream_class} |
6b783f49 JG |
397 | @post <strong>On success, if the return value is a field type</strong>, its |
398 | reference count is incremented. | |
594a3fb7 | 399 | |
8deee039 | 400 | @sa bt_stream_class_set_event_header_field_type(): Sets the event |
594a3fb7 PP |
401 | header field type of a given stream class. |
402 | */ | |
5fe68922 PP |
403 | static inline |
404 | struct bt_field_type *bt_stream_class_get_event_header_field_type( | |
405 | struct bt_stream_class *stream_class) | |
406 | { | |
407 | return bt_get(bt_stream_class_borrow_event_header_field_type( | |
408 | stream_class)); | |
409 | } | |
662e778c | 410 | |
594a3fb7 PP |
411 | /** |
412 | @brief Sets the event header field type of the CTF IR stream class | |
6b783f49 JG |
413 | \p stream_class to \p event_header_type, or unsets the current event |
414 | header field type from \p stream_class. | |
415 | ||
416 | If \p event_header_type is \c NULL, then this function unsets the current | |
417 | event header field type from \p stream_class, effectively making \p stream_class | |
418 | a stream class without a event header field type. | |
594a3fb7 | 419 | |
6b783f49 JG |
420 | As of Babeltrace \btversion, if \p event_header_type is not \c NULL, |
421 | \p event_header_type \em must be a CTF IR structure field type object. | |
594a3fb7 | 422 | |
b2481397 | 423 | @param[in] stream_class Stream class of which to set the event |
594a3fb7 | 424 | header field type. |
6b783f49 JG |
425 | @param[in] event_header_type Event header field type, or \c NULL to unset |
426 | the current event header field type. | |
594a3fb7 PP |
427 | @returns 0 on success, or a negative value on error. |
428 | ||
429 | @prenotnull{stream_class} | |
594a3fb7 | 430 | @prehot{stream_class} |
6b783f49 JG |
431 | @pre <strong>\p event_header_type, if not \c NULL</strong>, is a CTF IR |
432 | structure field type. | |
594a3fb7 | 433 | @postrefcountsame{stream_class} |
6b783f49 JG |
434 | @post <strong>On success, if \p event_header_type is not \c NULL</strong>, |
435 | the reference count of \p event_header_type is incremented. | |
594a3fb7 | 436 | |
8deee039 | 437 | @sa bt_stream_class_get_event_header_field_type(): Returns the event |
b2481397 | 438 | header field type of a given stream class. |
594a3fb7 | 439 | */ |
8deee039 | 440 | extern int bt_stream_class_set_event_header_field_type( |
839d52a5 PP |
441 | struct bt_stream_class *stream_class, |
442 | struct bt_field_type *event_header_type); | |
662e778c | 443 | |
a6918753 PP |
444 | extern struct bt_event_header_field *bt_stream_class_create_event_header_field( |
445 | struct bt_stream_class *stream_class); | |
446 | ||
5fe68922 PP |
447 | extern struct bt_field_type * |
448 | bt_stream_class_borrow_event_context_field_type( | |
449 | struct bt_stream_class *stream_class); | |
450 | ||
594a3fb7 | 451 | /** |
6b783f49 JG |
452 | @brief Returns the event context field type of the CTF IR stream class |
453 | \p stream_class. | |
594a3fb7 | 454 | |
6b783f49 JG |
455 | @param[in] stream_class Stream class of which to get the event context |
456 | field type. | |
457 | @returns Event context field type of \p stream_class, | |
458 | or \c NULL if \p stream_class has no event context field | |
459 | type or on error. | |
594a3fb7 PP |
460 | |
461 | @prenotnull{stream_class} | |
c2f29fb9 | 462 | @postrefcountsame{stream_class} |
6b783f49 JG |
463 | @post <strong>On success, if the return value is a field type</strong>, |
464 | its reference count is incremented. | |
465 | ||
594a3fb7 | 466 | |
8deee039 | 467 | @sa bt_stream_class_set_event_context_field_type(): Sets the event |
6b783f49 | 468 | context field type of a given stream class. |
594a3fb7 | 469 | */ |
5fe68922 PP |
470 | static inline |
471 | struct bt_field_type * | |
8deee039 | 472 | bt_stream_class_get_event_context_field_type( |
5fe68922 PP |
473 | struct bt_stream_class *stream_class) |
474 | { | |
475 | return bt_get(bt_stream_class_borrow_event_context_field_type( | |
476 | stream_class)); | |
477 | } | |
af181248 | 478 | |
594a3fb7 | 479 | /** |
6b783f49 JG |
480 | @brief Sets the event context field type of the CTF IR stream class |
481 | \p stream_class to \p event_context_type, or unsets the current event | |
482 | context field type from \p stream_class. | |
594a3fb7 | 483 | |
6b783f49 JG |
484 | If \p event_context_type is \c NULL, then this function unsets the current |
485 | event context field type from \p stream_class, effectively making \p | |
486 | stream_class a stream class without a event context field type. | |
594a3fb7 | 487 | |
6b783f49 JG |
488 | As of Babeltrace \btversion, if \p event_context_type is not \c NULL, |
489 | \p event_context_type \em must be a CTF IR structure field type object. | |
490 | ||
491 | @param[in] stream_class Stream class of which to set the packet | |
492 | context field type. | |
493 | @param[in] event_context_type Event context field type, or \c NULL to unset | |
494 | the current event context field type. | |
594a3fb7 PP |
495 | @returns 0 on success, or a negative value on error. |
496 | ||
497 | @prenotnull{stream_class} | |
594a3fb7 | 498 | @prehot{stream_class} |
6b783f49 JG |
499 | @pre <strong>\p event_context_type, if not \c NULL</strong>, is a CTF IR |
500 | structure field type. | |
594a3fb7 | 501 | @postrefcountsame{stream_class} |
6b783f49 JG |
502 | @post <strong>On success, if \p event_context_type is not \c NULL</strong>, |
503 | the reference count of \p event_context_type is incremented. | |
594a3fb7 | 504 | |
8deee039 | 505 | @sa bt_stream_class_get_event_context_field_type(): Returns the event context |
6b783f49 | 506 | field type of a given stream class. |
594a3fb7 | 507 | */ |
8deee039 | 508 | extern int bt_stream_class_set_event_context_field_type( |
839d52a5 PP |
509 | struct bt_stream_class *stream_class, |
510 | struct bt_field_type *event_context_type); | |
af181248 | 511 | |
594a3fb7 PP |
512 | /** @} */ |
513 | ||
514 | /** | |
515 | @name Event class children functions | |
516 | @{ | |
517 | */ | |
518 | ||
519 | /** | |
520 | @brief Returns the number of event classes contained in the | |
521 | CTF IR stream class \p stream_class. | |
522 | ||
523 | @param[in] stream_class Stream class of which to get the number | |
524 | of children event classes. | |
525 | @returns Number of children event classes | |
526 | contained in \p stream_class, or | |
527 | a negative value on error. | |
528 | ||
529 | @prenotnull{stream_class} | |
530 | @postrefcountsame{stream_class} | |
531 | */ | |
839d52a5 PP |
532 | extern int64_t bt_stream_class_get_event_class_count( |
533 | struct bt_stream_class *stream_class); | |
594a3fb7 | 534 | |
5fe68922 PP |
535 | extern struct bt_event_class *bt_stream_class_borrow_event_class_by_index( |
536 | struct bt_stream_class *stream_class, uint64_t index); | |
537 | ||
594a3fb7 PP |
538 | /** |
539 | @brief Returns the event class at index \p index in the CTF IR stream | |
540 | class \p stream_class. | |
541 | ||
542 | @param[in] stream_class Stream class of which to get the event class. | |
543 | @param[in] index Index of the event class to find. | |
544 | @returns Event class at index \p index, or \c NULL | |
545 | on error. | |
546 | ||
547 | @prenotnull{stream_class} | |
548 | @pre \p index is lesser than the number of event classes contained in the | |
549 | stream class \p stream_class (see | |
839d52a5 | 550 | bt_stream_class_get_event_class_count()). |
594a3fb7 PP |
551 | @postrefcountsame{stream_class} |
552 | @postsuccessrefcountretinc | |
553 | ||
839d52a5 | 554 | @sa bt_stream_class_get_event_class_by_id(): Finds an event class |
594a3fb7 | 555 | by ID. |
594a3fb7 | 556 | */ |
5fe68922 PP |
557 | static inline |
558 | struct bt_event_class *bt_stream_class_get_event_class_by_index( | |
559 | struct bt_stream_class *stream_class, uint64_t index) | |
560 | { | |
561 | return bt_get(bt_stream_class_borrow_event_class_by_index(stream_class, | |
562 | index)); | |
563 | } | |
564 | ||
565 | extern struct bt_event_class *bt_stream_class_borrow_event_class_by_id( | |
566 | struct bt_stream_class *stream_class, uint64_t id); | |
594a3fb7 | 567 | |
594a3fb7 PP |
568 | /** |
569 | @brief Returns the event class with ID \c id found in the CTF IR stream | |
570 | class \p stream_class. | |
571 | ||
572 | @param[in] stream_class Stream class of which to get the event class. | |
573 | @param[in] id ID of the event class to find. | |
574 | @returns Event class with ID \p id, or \c NULL | |
575 | on error. | |
576 | ||
577 | @prenotnull{stream_class} | |
578 | @postrefcountsame{stream_class} | |
579 | @postsuccessrefcountretinc | |
594a3fb7 | 580 | */ |
5fe68922 PP |
581 | static inline |
582 | struct bt_event_class *bt_stream_class_get_event_class_by_id( | |
583 | struct bt_stream_class *stream_class, uint64_t id) | |
584 | { | |
585 | return bt_get(bt_stream_class_borrow_event_class_by_id(stream_class, | |
586 | id)); | |
587 | } | |
594a3fb7 PP |
588 | |
589 | /** | |
590 | @brief Adds the CTF IR event class \p event_class to the | |
591 | CTF IR stream class \p stream_class. | |
592 | ||
593 | On success, \p event_class becomes the child of \p stream_class. | |
594 | ||
595 | You can only add a given event class to one stream class. | |
596 | ||
597 | You can call this function even if \p stream_class is frozen. Adding | |
598 | event classes is the only operation that is permitted | |
599 | on a frozen stream class. | |
600 | ||
4cdafd51 PP |
601 | This function tries to resolve the needed |
602 | \link ctfirfieldtypes CTF IR field type\endlink of the dynamic field | |
603 | types that are found anywhere in the context or payload field | |
604 | types of \p event_class. If any automatic resolving fails: | |
605 | ||
606 | - If the needed field type should be found in one of the root field | |
607 | types of \p event_class or \p stream_class, this function fails. | |
608 | - If \p stream_class is the child of a | |
609 | \link ctfirtraceclass CTF IR trace class\endlink (it was added | |
839d52a5 | 610 | with bt_trace_add_stream_class()), this function fails. |
4cdafd51 PP |
611 | - If \p stream_class is not the child of a trace class yet, the |
612 | automatic resolving is reported to the next call to | |
839d52a5 | 613 | bt_trace_add_stream_class() with \p stream_class. |
4cdafd51 | 614 | |
594a3fb7 PP |
615 | @param[in] stream_class Stream class to which to add \p event_class. |
616 | @param[in] event_class Event class to add to \p stream_class. | |
617 | @returns 0 on success, or a negative value on error. | |
618 | ||
619 | @prenotnull{stream_class} | |
620 | @prenotnull{event_class} | |
621 | @prehot{event_class} | |
622 | @postrefcountsame{stream_class} | |
623 | @postsuccessrefcountinc{event_class} | |
2fc61597 | 624 | @postsuccessfrozen{event_class} |
594a3fb7 | 625 | */ |
839d52a5 PP |
626 | extern int bt_stream_class_add_event_class( |
627 | struct bt_stream_class *stream_class, | |
628 | struct bt_event_class *event_class); | |
594a3fb7 PP |
629 | |
630 | /** @} */ | |
631 | ||
632 | /** | |
633 | @name Misc. function | |
634 | @{ | |
635 | */ | |
636 | ||
637 | /** | |
638 | @brief Accepts the visitor \p visitor to visit the hierarchy of the | |
639 | CTF IR stream class \p stream_class. | |
640 | ||
641 | This function traverses the hierarchy of \p stream_class in pre-order | |
642 | and calls \p visitor on each element. | |
643 | ||
644 | The stream class itself is visited first, and then all its children | |
645 | event classes. | |
646 | ||
647 | @param[in] stream_class Stream class to visit. | |
648 | @param[in] visitor Visiting function. | |
649 | @param[in] data User data. | |
650 | @returns 0 on success, or a negative value on error. | |
651 | ||
652 | @prenotnull{stream_class} | |
653 | @prenotnull{visitor} | |
654 | */ | |
839d52a5 PP |
655 | extern int bt_stream_class_visit(struct bt_stream_class *stream_class, |
656 | bt_visitor visitor, void *data); | |
8bf65fbd | 657 | |
594a3fb7 PP |
658 | /** @} */ |
659 | ||
660 | /** @} */ | |
661 | ||
adc315b8 JG |
662 | #ifdef __cplusplus |
663 | } | |
664 | #endif | |
665 | ||
666 | #endif /* BABELTRACE_CTF_IR_STREAM_CLASS_H */ |