Commit | Line | Data |
---|---|---|
bc37ae52 JG |
1 | #ifndef BABELTRACE_CTF_IR_TRACE_H |
2 | #define BABELTRACE_CTF_IR_TRACE_H | |
3 | ||
4 | /* | |
5 | * BabelTrace - CTF IR: Trace | |
6 | * | |
7 | * Copyright 2014 Jérémie Galarneau <jeremie.galarneau@efficios.com> | |
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 | ||
5fe68922 PP |
33 | /* For bt_get() */ |
34 | #include <babeltrace/ref.h> | |
35 | ||
839d52a5 | 36 | /* For bt_visitor */ |
8bf65fbd | 37 | #include <babeltrace/ctf-ir/visitor.h> |
e0831b38 PP |
38 | |
39 | /* For bt_bool */ | |
c55a9f58 | 40 | #include <babeltrace/types.h> |
410d0373 | 41 | #include <stdint.h> |
bc37ae52 JG |
42 | |
43 | #ifdef __cplusplus | |
44 | extern "C" { | |
45 | #endif | |
46 | ||
839d52a5 | 47 | struct bt_field_type; |
e0831b38 PP |
48 | struct bt_value; |
49 | ||
06300316 PP |
50 | /** |
51 | @defgroup ctfirtraceclass CTF IR trace class | |
52 | @ingroup ctfir | |
53 | @brief CTF IR trace class. | |
54 | ||
6dd2bd0c PP |
55 | @code |
56 | #include <babeltrace/ctf-ir/trace.h> | |
57 | @endcode | |
58 | ||
06300316 PP |
59 | A CTF IR <strong><em>trace class</em></strong> is a descriptor of |
60 | traces. | |
61 | ||
62 | You can obtain a trace class in two different modes: | |
63 | ||
839d52a5 | 64 | - <strong>Normal mode</strong>: use bt_trace_create() to create a |
06300316 | 65 | default, empty trace class. |
839d52a5 | 66 | - <strong>CTF writer mode</strong>: use bt_writer_get_trace() to |
dfeca116 | 67 | get the trace class created by a given CTF writer object. |
06300316 PP |
68 | |
69 | A trace class has the following properties: | |
70 | ||
71 | - A \b name. | |
8a716c8d | 72 | - A <strong>native byte order</strong>: all the |
654515f1 | 73 | \link ctfirfieldtypes field types\endlink eventually part of the trace |
839d52a5 | 74 | class with a byte order set to #BT_BYTE_ORDER_NATIVE have this |
06300316 | 75 | "real" byte order. |
4a32fda0 | 76 | - A \b UUID. |
06300316 PP |
77 | - An \b environment, which is a custom key-value mapping. Keys are |
78 | strings and values can be strings or integers. | |
79 | ||
80 | In the Babeltrace CTF IR system, a trace class contains zero or more | |
81 | \link ctfirstreamclass stream classes\endlink, and a stream class | |
82 | contains zero or more \link ctfireventclass event classes\endlink. You | |
83 | can add an event class to a stream class with | |
839d52a5 PP |
84 | bt_stream_class_add_event_class(). You can add a stream class to a |
85 | trace class with bt_trace_add_stream_class(). | |
06300316 | 86 | |
c1e730fe | 87 | You can access the streams of a trace, that is, the streams which were |
839d52a5 PP |
88 | created from the trace's stream classes with bt_stream_create(), |
89 | with bt_trace_get_stream_by_index(). | |
c1e730fe | 90 | |
06300316 PP |
91 | A trace class owns the <strong>trace packet header</strong> |
92 | \link ctfirfieldtypes field type\endlink, which represents the | |
93 | \c trace.packet.header CTF scope. This field type describes the | |
94 | trace packet header fields of the traces that this trace class | |
95 | describes. | |
96 | ||
97 | The trace packet header field type \em must be a structure field type as | |
98 | of Babeltrace \btversion. | |
99 | ||
100 | As per the CTF specification, the trace packet header field type \em | |
101 | must contain a field named \c stream_id if the trace class contains more | |
102 | than one stream class. | |
103 | ||
104 | As a reminder, here's the structure of a CTF packet: | |
105 | ||
106 | @imgpacketstructure | |
107 | ||
108 | A trace class also contains zero or more | |
fe7041b3 | 109 | \link ctfirclockclass CTF IR clock classes\endlink. |
06300316 PP |
110 | |
111 | @todo | |
112 | Elaborate about clock classes irt clock values. | |
113 | ||
2c1c33a4 | 114 | As with any Babeltrace object, CTF IR trace class objects have |
06300316 PP |
115 | <a href="https://en.wikipedia.org/wiki/Reference_counting">reference |
116 | counts</a>. See \ref refs to learn more about the reference counting | |
117 | management of Babeltrace objects. | |
118 | ||
119 | The following functions \em freeze their trace class parameter on | |
120 | success: | |
121 | ||
839d52a5 PP |
122 | - bt_trace_add_stream_class() |
123 | - bt_writer_create_stream() | |
dfeca116 | 124 | (\link ctfwriter CTF writer\endlink mode only) |
06300316 PP |
125 | |
126 | You cannot modify a frozen trace class: it is considered immutable, | |
127 | except for: | |
128 | ||
129 | - Adding a stream class to it with | |
839d52a5 PP |
130 | bt_trace_add_stream_class(). |
131 | - Adding a CTF IR clock class to it with bt_trace_add_clock_class(). | |
06300316 PP |
132 | - \link refs Reference counting\endlink. |
133 | ||
06300316 PP |
134 | @sa ctfirstreamclass |
135 | @sa ctfireventclass | |
136 | @sa ctfirclockclass | |
137 | ||
138 | @file | |
139 | @brief CTF IR trace class type and functions. | |
140 | @sa ctfirtraceclass | |
141 | ||
142 | @addtogroup ctfirtraceclass | |
143 | @{ | |
144 | */ | |
145 | ||
146 | /** | |
839d52a5 | 147 | @struct bt_trace |
06300316 PP |
148 | @brief A CTF IR trace class. |
149 | @sa ctfirtraceclass | |
150 | */ | |
839d52a5 PP |
151 | struct bt_trace; |
152 | struct bt_stream; | |
153 | struct bt_stream_class; | |
154 | struct bt_clock_class; | |
bc37ae52 | 155 | |
3602afb0 PP |
156 | /** |
157 | @brief User function type to use with | |
839d52a5 | 158 | bt_trace_add_is_static_listener(). |
3602afb0 PP |
159 | |
160 | @param[in] trace_class Trace class which is now static. | |
161 | @param[in] data User data as passed to | |
839d52a5 | 162 | bt_trace_add_is_static_listener() when |
3602afb0 PP |
163 | you added the listener. |
164 | ||
165 | @prenotnull{trace_class} | |
166 | */ | |
839d52a5 PP |
167 | typedef void (* bt_trace_is_static_listener)( |
168 | struct bt_trace *trace_class, void *data); | |
3602afb0 | 169 | |
9962ad4b PP |
170 | /** |
171 | @brief User function type to use with | |
839d52a5 | 172 | bt_trace_add_is_static_listener(). |
9962ad4b PP |
173 | |
174 | @param[in] trace_class Trace class to which the listener was added. | |
175 | @param[in] data User data as passed to | |
839d52a5 | 176 | bt_trace_add_is_static_listener() when |
9962ad4b PP |
177 | you added the listener. |
178 | ||
179 | @prenotnull{trace_class} | |
180 | */ | |
839d52a5 PP |
181 | typedef void (* bt_trace_listener_removed)( |
182 | struct bt_trace *trace_class, void *data); | |
9962ad4b | 183 | |
2204c381 | 184 | /** |
06300316 PP |
185 | @name Creation function |
186 | @{ | |
187 | */ | |
2204c381 | 188 | |
06300316 PP |
189 | /** |
190 | @brief Creates a default CTF IR trace class. | |
191 | ||
192 | On success, the trace packet header field type of the created trace | |
488e09a7 PP |
193 | class is an empty structure field type. You can modify this default |
194 | trace packet header field type after the trace class is created with | |
8deee039 PP |
195 | bt_trace_get_packet_header_field_type() and |
196 | bt_trace_set_packet_header_field_type(). | |
06300316 PP |
197 | |
198 | The created trace class has the following initial properties: | |
199 | ||
200 | - <strong>Name</strong>: none. You can set a name | |
839d52a5 | 201 | with bt_trace_set_name(). |
488e09a7 | 202 | - <strong>UUID</strong>: none. You can set a UUID with |
839d52a5 PP |
203 | bt_trace_set_uuid(). |
204 | - <strong>Native byte order</strong>: #BT_BYTE_ORDER_UNSPECIFIED. | |
da1a2e66 | 205 | You can set a native byte order with |
839d52a5 | 206 | bt_trace_set_native_byte_order(). |
06300316 | 207 | - <strong>Environment</strong>: empty. You can add environment entries |
839d52a5 PP |
208 | with bt_trace_set_environment_field(), |
209 | bt_trace_set_environment_field_integer(), and | |
210 | bt_trace_set_environment_field_string(). | |
06300316 PP |
211 | |
212 | @returns Created trace class, or \c NULL on error. | |
213 | ||
214 | @postsuccessrefcountret1 | |
215 | */ | |
839d52a5 | 216 | extern struct bt_trace *bt_trace_create(void); |
bc37ae52 | 217 | |
06300316 | 218 | /** @} */ |
e96045d4 | 219 | |
06300316 PP |
220 | /** |
221 | @name Properties functions | |
222 | @{ | |
223 | */ | |
e96045d4 | 224 | |
06300316 PP |
225 | /** |
226 | @brief Returns the name of the CTF IR trace class \p trace_class. | |
7f800dc7 | 227 | |
06300316 PP |
228 | On success, \p trace_class remains the sole owner of the returned |
229 | string. The returned string is valid as long as \p trace_class exists | |
230 | and is not modified. | |
bc37ae52 | 231 | |
06300316 PP |
232 | @param[in] trace_class Trace class of which to get the name. |
233 | @returns Name of trace class \p trace_class, or | |
234 | \c NULL if \p trace_class is unnamed or | |
235 | on error. | |
3487c9f3 | 236 | |
06300316 PP |
237 | @prenotnull{trace_class} |
238 | @postrefcountsame{trace_class} | |
239 | ||
839d52a5 | 240 | @sa bt_trace_set_name(): Sets the name of a given trace class. |
06300316 | 241 | */ |
839d52a5 | 242 | extern const char *bt_trace_get_name(struct bt_trace *trace_class); |
06300316 PP |
243 | |
244 | /** | |
245 | @brief Sets the name of the CTF IR trace class \p trace_class | |
246 | to \p name. | |
247 | ||
248 | @param[in] trace_class Trace class of which to set the name. | |
249 | @param[in] name Name of the trace class (copied on success). | |
250 | @returns 0 on success, or a negative value on error. | |
251 | ||
252 | @prenotnull{trace_class} | |
253 | @prenotnull{name} | |
254 | @prehot{trace_class} | |
255 | @postrefcountsame{trace_class} | |
256 | ||
839d52a5 | 257 | @sa bt_trace_get_name(): Returns the name of a given trace class. |
06300316 | 258 | */ |
839d52a5 | 259 | extern int bt_trace_set_name(struct bt_trace *trace_class, |
06300316 PP |
260 | const char *name); |
261 | ||
262 | /** | |
8a716c8d | 263 | @brief Returns the native byte order of the CTF IR trace class |
06300316 PP |
264 | \p trace_class. |
265 | ||
266 | @param[in] trace_class Trace class of which to get the default byte | |
267 | order. | |
488e09a7 | 268 | @returns Native byte order of \p trace_class, |
839d52a5 | 269 | or #BT_BYTE_ORDER_UNKNOWN on error. |
06300316 PP |
270 | |
271 | @prenotnull{trace_class} | |
272 | @postrefcountsame{trace_class} | |
273 | ||
839d52a5 | 274 | @sa bt_trace_set_native_byte_order(): Sets the native byte order of |
8a716c8d | 275 | a given trace class. |
06300316 | 276 | */ |
839d52a5 PP |
277 | extern enum bt_byte_order bt_trace_get_native_byte_order( |
278 | struct bt_trace *trace_class); | |
06300316 PP |
279 | |
280 | /** | |
8a716c8d | 281 | @brief Sets the native byte order of the CTF IR trace class |
391c8f0d | 282 | \p trace_class to \p native_byte_order. |
06300316 | 283 | |
391c8f0d | 284 | \p native_byte_order \em must be one of: |
06300316 | 285 | |
839d52a5 PP |
286 | - #BT_BYTE_ORDER_LITTLE_ENDIAN |
287 | - #BT_BYTE_ORDER_BIG_ENDIAN | |
288 | - #BT_BYTE_ORDER_NETWORK | |
d41cff38 | 289 | - <strong>If the trace is not in CTF writer mode<strong>, |
839d52a5 | 290 | #BT_BYTE_ORDER_UNSPECIFIED. |
06300316 | 291 | |
8a716c8d | 292 | @param[in] trace_class Trace class of which to set the native byte |
391c8f0d | 293 | order. |
488e09a7 | 294 | @param[in] native_byte_order Native byte order of the trace class. |
391c8f0d | 295 | @returns 0 on success, or a negative value on error. |
06300316 PP |
296 | |
297 | @prenotnull{trace_class} | |
06300316 | 298 | @prehot{trace_class} |
839d52a5 | 299 | @pre \p native_byte_order is either #BT_BYTE_ORDER_UNSPECIFIED (if the |
d41cff38 | 300 | trace is not in CTF writer mode), |
839d52a5 PP |
301 | #BT_BYTE_ORDER_LITTLE_ENDIAN, #BT_BYTE_ORDER_BIG_ENDIAN, or |
302 | #BT_BYTE_ORDER_NETWORK. | |
06300316 PP |
303 | @postrefcountsame{trace_class} |
304 | ||
839d52a5 | 305 | @sa bt_trace_get_native_byte_order(): Returns the native byte order of a |
8a716c8d | 306 | given trace class. |
06300316 | 307 | */ |
839d52a5 PP |
308 | extern int bt_trace_set_native_byte_order(struct bt_trace *trace_class, |
309 | enum bt_byte_order native_byte_order); | |
06300316 | 310 | |
4a32fda0 PP |
311 | /** |
312 | @brief Returns the UUID of the CTF IR trace class \p trace_class. | |
313 | ||
314 | On success, the return value is an array of 16 bytes. | |
315 | ||
316 | @param[in] trace_class Trace class of which to get the UUID. | |
317 | @returns UUID of trace class \p trace_class, or | |
318 | \c NULL if \p trace_class has no UUID or on error. | |
319 | ||
320 | @prenotnull{trace_class} | |
321 | @postrefcountsame{trace_class} | |
322 | ||
839d52a5 | 323 | @sa bt_trace_set_uuid(): Sets the UUID of a given trace class. |
4a32fda0 | 324 | */ |
839d52a5 PP |
325 | extern const unsigned char *bt_trace_get_uuid( |
326 | struct bt_trace *trace_class); | |
4a32fda0 PP |
327 | |
328 | /** | |
329 | @brief Sets the UUID of the CTF IR trace class \p trace_class to | |
330 | \p uuid. | |
331 | ||
332 | \p uuid \em must be an array of 16 bytes. | |
333 | ||
334 | @param[in] trace_class Trace class of which to set the UUID. | |
335 | @param[in] uuid UUID of the \p trace_class (copied on | |
336 | success). | |
337 | @returns 0 on success, or a negative value on error. | |
338 | ||
339 | @prenotnull{trace_class} | |
340 | @prenotnull{uuid} | |
341 | @prehot{trace_class} | |
342 | @pre \p uuid is an array of 16 bytes. | |
343 | @postrefcountsame{trace_class} | |
344 | ||
839d52a5 | 345 | @sa bt_trace_get_uuid(): Returns the UUID of a given trace class. |
4a32fda0 | 346 | */ |
839d52a5 | 347 | extern int bt_trace_set_uuid(struct bt_trace *trace_class, |
4a32fda0 PP |
348 | const unsigned char *uuid); |
349 | ||
06300316 PP |
350 | /** |
351 | @brief Returns the number of entries contained in the environment of | |
352 | the CTF IR trace class \p trace_class. | |
353 | ||
354 | @param[in] trace_class Trace class of which to get the number | |
355 | of environment entries. | |
356 | @returns Number of environment entries | |
357 | contained in \p trace_class, or | |
358 | a negative value on error. | |
359 | ||
360 | @prenotnull{trace_class} | |
361 | @postrefcountsame{trace_class} | |
362 | */ | |
839d52a5 PP |
363 | extern int64_t bt_trace_get_environment_field_count( |
364 | struct bt_trace *trace_class); | |
e6fa2160 | 365 | |
06300316 PP |
366 | /** |
367 | @brief Returns the field name of the environment entry at index | |
368 | \p index in the CTF IR trace class \p trace_class. | |
369 | ||
370 | On success, the returned string is valid as long as this trace class | |
371 | exists and is \em not modified. \p trace_class remains the sole owner of | |
372 | the returned string. | |
373 | ||
374 | @param[in] trace_class Trace class of which to get the name of the | |
375 | environment entry at index \p index. | |
376 | @param[in] index Index of environment entry to find. | |
377 | @returns Name of the environment entry at index \p index | |
378 | in \p trace_class, or \c NULL on error. | |
379 | ||
380 | @prenotnull{trace_class} | |
381 | @pre \p index is lesser than the number of environment entries in | |
839d52a5 | 382 | \p trace_class (see bt_trace_get_environment_field_count()). |
06300316 PP |
383 | @postrefcountsame{trace_class} |
384 | ||
839d52a5 | 385 | @sa bt_trace_get_environment_field_value_by_index(): Finds a trace class's |
06300316 | 386 | environment entry by index. |
839d52a5 | 387 | @sa bt_trace_get_environment_field_value_by_name(): Finds a trace |
06300316 | 388 | class's environment entry by name. |
839d52a5 | 389 | @sa bt_trace_set_environment_field(): Sets the value of a trace |
06300316 PP |
390 | class's environment entry. |
391 | */ | |
e6fa2160 | 392 | extern const char * |
839d52a5 PP |
393 | bt_trace_get_environment_field_name_by_index( |
394 | struct bt_trace *trace_class, uint64_t index); | |
e6fa2160 | 395 | |
5fe68922 PP |
396 | extern struct bt_value * |
397 | bt_trace_borrow_environment_field_value_by_index(struct bt_trace *trace_class, | |
398 | uint64_t index); | |
399 | ||
06300316 PP |
400 | /** |
401 | @brief Returns the value of the environment entry at index | |
402 | \p index in the CTF IR trace class \p trace_class. | |
403 | ||
404 | @param[in] trace_class Trace class of which to get the value of the | |
405 | environment entry at index \p index. | |
406 | @param[in] index Index of the environment entry to find. | |
407 | @returns Value of the environment entry at index \p index | |
408 | in \p trace_class, or \c NULL on error. | |
409 | ||
410 | @prenotnull{trace_class} | |
411 | @pre \p index is lesser than the number of environment entries in | |
839d52a5 | 412 | \p trace_class (see bt_trace_get_environment_field_count()). |
06300316 PP |
413 | @postrefcountsame{trace_class} |
414 | @postsuccessrefcountretinc | |
415 | ||
839d52a5 | 416 | @sa bt_trace_get_environment_field_value_by_name(): Finds a trace |
06300316 | 417 | class's environment entry by name. |
839d52a5 | 418 | @sa bt_trace_set_environment_field(): Sets the value of a trace |
06300316 PP |
419 | class's environment entry. |
420 | */ | |
5fe68922 PP |
421 | static inline |
422 | struct bt_value *bt_trace_get_environment_field_value_by_index( | |
423 | struct bt_trace *trace_class, uint64_t index) | |
424 | { | |
425 | return bt_get(bt_trace_borrow_environment_field_value_by_index( | |
426 | trace_class, index)); | |
427 | } | |
428 | ||
dac5c838 | 429 | extern struct bt_value * |
5fe68922 PP |
430 | bt_trace_borrow_environment_field_value_by_name( |
431 | struct bt_trace *trace_class, const char *name); | |
e6fa2160 | 432 | |
06300316 PP |
433 | /** |
434 | @brief Returns the value of the environment entry named \p name | |
435 | in the CTF IR trace class \p trace_class. | |
436 | ||
437 | @param[in] trace_class Trace class of which to get the value of the | |
438 | environment entry named \p name. | |
439 | @param[in] name Name of the environment entry to find. | |
440 | @returns Value of the environment entry named \p name | |
441 | in \p trace_class, or \c NULL if there's no such | |
442 | entry or on error. | |
443 | ||
444 | @prenotnull{trace_class} | |
445 | @prenotnull{name} | |
446 | @postrefcountsame{trace_class} | |
447 | @postsuccessrefcountretinc | |
448 | ||
839d52a5 | 449 | @sa bt_trace_get_environment_field_value_by_index(): Finds a trace class's |
06300316 | 450 | environment entry by index. |
839d52a5 | 451 | @sa bt_trace_set_environment_field(): Sets the value of a trace |
06300316 PP |
452 | class's environment entry. |
453 | */ | |
5fe68922 PP |
454 | static inline |
455 | struct bt_value * | |
839d52a5 | 456 | bt_trace_get_environment_field_value_by_name( |
5fe68922 PP |
457 | struct bt_trace *trace_class, const char *name) |
458 | { | |
459 | return bt_get( | |
460 | bt_trace_borrow_environment_field_value_by_name( | |
461 | trace_class, name)); | |
462 | } | |
e6fa2160 | 463 | |
06300316 PP |
464 | /** |
465 | @brief Sets the environment entry named \p name in the | |
466 | CTF IR trace class \p trace_class to \p value. | |
467 | ||
468 | If an environment entry named \p name exists in \p trace_class, its | |
469 | value is first put, and then replaced by \p value. | |
470 | ||
471 | @param[in] trace_class Trace class of which to set the environment | |
472 | entry. | |
473 | @param[in] name Name of the environment entry to set (copied | |
474 | on success). | |
475 | @param[in] value Value of the environment entry named \p name. | |
476 | @returns 0 on success, or a negative value on error. | |
477 | ||
478 | @prenotnull{trace_class} | |
479 | @prenotnull{name} | |
480 | @prenotnull{value} | |
481 | @prehot{trace_class} | |
482 | @pre \p value is an | |
483 | \link bt_value_integer_create() integer value object\endlink | |
484 | or a | |
485 | \link bt_value_string_create() string value object\endlink. | |
486 | @postrefcountsame{trace_class} | |
487 | @postsuccessrefcountinc{value} | |
488 | ||
839d52a5 | 489 | @sa bt_trace_get_environment_field_value_by_index(): Finds a trace class's |
06300316 | 490 | environment entry by index. |
839d52a5 | 491 | @sa bt_trace_get_environment_field_value_by_name(): Finds a trace |
06300316 PP |
492 | class's environment entry by name. |
493 | */ | |
839d52a5 PP |
494 | extern int bt_trace_set_environment_field( |
495 | struct bt_trace *trace_class, const char *name, | |
06300316 | 496 | struct bt_value *value); |
bc37ae52 | 497 | |
06300316 PP |
498 | /** |
499 | @brief Sets the environment entry named \p name in the | |
500 | CTF IR trace class \p trace_class to \p value. | |
501 | ||
502 | If an environment entry named \p name exists in \p trace_class, its | |
503 | value is first put, and then replaced by a new | |
504 | \link bt_value_integer_create() integer value object\endlink | |
505 | containing \p value. | |
506 | ||
507 | @param[in] trace_class Trace class of which to set the environment | |
508 | entry. | |
509 | @param[in] name Name of the environment entry to set (copied | |
510 | on success). | |
511 | @param[in] value Value of the environment entry named \p name. | |
512 | @returns 0 on success, or a negative value on error. | |
513 | ||
514 | @prenotnull{trace_class} | |
515 | @prenotnull{name} | |
516 | @prehot{trace_class} | |
517 | @postrefcountsame{trace_class} | |
518 | ||
839d52a5 | 519 | @sa bt_trace_set_environment_field(): Sets the value of a trace |
06300316 PP |
520 | class's environment entry. |
521 | */ | |
839d52a5 PP |
522 | extern int bt_trace_set_environment_field_integer( |
523 | struct bt_trace *trace_class, const char *name, | |
06300316 | 524 | int64_t value); |
884cd6c3 | 525 | |
06300316 PP |
526 | /** |
527 | @brief Sets the environment entry named \p name in the | |
528 | CTF IR trace class \p trace_class to \p value. | |
529 | ||
530 | If an environment entry named \p name exists in \p trace_class, its | |
531 | value is first put, and then replaced by a new | |
532 | \link bt_value_string_create() string value object\endlink | |
533 | containing \p value. | |
534 | ||
535 | @param[in] trace_class Trace class of which to set the environment | |
536 | entry. | |
537 | @param[in] name Name of the environment entry to set (copied | |
538 | on success). | |
539 | @param[in] value Value of the environment entry named \p name | |
540 | (copied on success). | |
541 | @returns 0 on success, or a negative value on error. | |
542 | ||
543 | @prenotnull{trace_class} | |
544 | @prenotnull{name} | |
545 | @prenotnull{value} | |
546 | @prehot{trace_class} | |
547 | @postrefcountsame{trace_class} | |
548 | ||
839d52a5 | 549 | @sa bt_trace_set_environment_field(): Sets the value of a trace |
06300316 PP |
550 | class's environment entry. |
551 | */ | |
839d52a5 PP |
552 | extern int bt_trace_set_environment_field_string( |
553 | struct bt_trace *trace_class, const char *name, | |
06300316 PP |
554 | const char *value); |
555 | ||
556 | /** @} */ | |
557 | ||
558 | /** | |
559 | @name Contained field types functions | |
560 | @{ | |
561 | */ | |
562 | ||
5fe68922 PP |
563 | extern struct bt_field_type *bt_trace_borrow_packet_header_field_type( |
564 | struct bt_trace *trace_class); | |
565 | ||
06300316 PP |
566 | /** |
567 | @brief Returns the packet header field type of the CTF IR trace class | |
568 | \p trace_class. | |
569 | ||
570 | @param[in] trace_class Trace class of which to get the packet | |
571 | header field type. | |
572 | @returns Packet header field type of \p trace_class, | |
6b783f49 JG |
573 | or \c NULL if \p trace_class has no packet header field |
574 | type or on error. | |
06300316 PP |
575 | |
576 | @prenotnull{trace_class} | |
c2f29fb9 | 577 | @postrefcountsame{trace_class} |
6b783f49 JG |
578 | @post <strong>On success, if the return value is a field type</strong>, its |
579 | reference count is incremented. | |
06300316 | 580 | |
8deee039 | 581 | @sa bt_trace_set_packet_header_field_type(): Sets the packet |
06300316 PP |
582 | header field type of a given trace class. |
583 | */ | |
5fe68922 PP |
584 | static inline |
585 | struct bt_field_type *bt_trace_get_packet_header_field_type( | |
586 | struct bt_trace *trace_class) | |
587 | { | |
588 | return bt_get(bt_trace_borrow_packet_header_field_type(trace_class)); | |
589 | } | |
06300316 PP |
590 | |
591 | /** | |
592 | @brief Sets the packet header field type of the CTF IR trace class | |
6b783f49 JG |
593 | \p trace_class to \p packet_header_type, or unsets the current packet |
594 | header field type from \p trace_class. | |
595 | ||
596 | If \p packet_header_type is \c NULL, then this function unsets the current | |
597 | packet header field type from \p trace_class, effectively making \p trace_class | |
598 | a trace without a packet header field type. | |
06300316 | 599 | |
6b783f49 JG |
600 | As of Babeltrace \btversion, if \p packet_header_type is not \c NULL, |
601 | \p packet_header_type \em must be a CTF IR structure field type object. | |
06300316 PP |
602 | |
603 | @param[in] trace_class Trace class of which to set the packet | |
604 | header field type. | |
6b783f49 JG |
605 | @param[in] packet_header_type Packet header field type, or \c NULL to unset |
606 | the current packet header field type. | |
06300316 PP |
607 | @returns 0 on success, or a negative value on error. |
608 | ||
609 | @prenotnull{trace_class} | |
06300316 | 610 | @prehot{trace_class} |
6b783f49 JG |
611 | @pre <strong>\p packet_header_type, if not \c NULL</strong>, is a CTF IR |
612 | structure field type. | |
06300316 | 613 | @postrefcountsame{trace_class} |
6b783f49 JG |
614 | @post <strong>On success, if \p packet_header_type is not \c NULL</strong>, |
615 | the reference count of \p packet_header_type is incremented. | |
06300316 | 616 | |
8deee039 | 617 | @sa bt_trace_get_packet_header_field_type(): Returns the packet |
06300316 PP |
618 | header field type of a given trace class. |
619 | */ | |
8deee039 | 620 | extern int bt_trace_set_packet_header_field_type(struct bt_trace *trace_class, |
839d52a5 | 621 | struct bt_field_type *packet_header_type); |
06300316 PP |
622 | |
623 | /** @} */ | |
624 | ||
625 | /** | |
fe7041b3 | 626 | @name Contained clock classes functions |
06300316 PP |
627 | @{ |
628 | */ | |
629 | ||
630 | /** | |
fe7041b3 | 631 | @brief Returns the number of CTF IR clock classes contained in the |
06300316 PP |
632 | CTF IR trace class \p trace_class. |
633 | ||
634 | @param[in] trace_class Trace class of which to get the number | |
fe7041b3 PP |
635 | of contained clock classes. |
636 | @returns Number of contained clock classes | |
06300316 PP |
637 | contained in \p trace_class, or a negative |
638 | value on error. | |
639 | ||
640 | @prenotnull{trace_class} | |
641 | @postrefcountsame{trace_class} | |
642 | */ | |
839d52a5 PP |
643 | extern int64_t bt_trace_get_clock_class_count( |
644 | struct bt_trace *trace_class); | |
06300316 | 645 | |
5fe68922 PP |
646 | extern struct bt_clock_class *bt_trace_borrow_clock_class_by_index( |
647 | struct bt_trace *trace_class, uint64_t index); | |
648 | ||
06300316 | 649 | /** |
fe7041b3 PP |
650 | @brief Returns the CTF IR clock class at index \p index in the CTF |
651 | IR trace class \p trace_class. | |
06300316 | 652 | |
fe7041b3 PP |
653 | @param[in] trace_class Trace class of which to get the clock class |
654 | contained at index \p index. | |
655 | @param[in] index Index of the clock class to find in | |
656 | \p trace_class. | |
657 | @returns Clock class at index \p index in \p trace_class, | |
658 | or \c NULL on error. | |
06300316 PP |
659 | |
660 | @prenotnull{trace_class} | |
661 | @pre \p index is lesser than the number of clock classes contained in | |
662 | the trace class \p trace_class (see | |
839d52a5 | 663 | bt_trace_get_clock_class_count()). |
06300316 PP |
664 | @postrefcountsame{trace_class} |
665 | @postsuccessrefcountretinc | |
666 | ||
839d52a5 | 667 | @sa bt_trace_get_clock_class_by_name(): Finds a clock class by name |
fe7041b3 | 668 | in a given trace class. |
839d52a5 | 669 | @sa bt_trace_add_clock_class(): Adds a clock class to a trace class. |
06300316 | 670 | */ |
5fe68922 PP |
671 | static inline |
672 | struct bt_clock_class *bt_trace_get_clock_class_by_index( | |
673 | struct bt_trace *trace_class, uint64_t index) | |
674 | { | |
675 | return bt_get(bt_trace_borrow_clock_class_by_index( | |
676 | trace_class, index)); | |
677 | } | |
678 | ||
679 | extern struct bt_clock_class *bt_trace_borrow_clock_class_by_name( | |
680 | struct bt_trace *trace_class, const char *name); | |
884cd6c3 | 681 | |
06300316 | 682 | /** |
fe7041b3 PP |
683 | @brief Returns the CTF IR clock class named \c name found in the CTF |
684 | IR trace class \p trace_class. | |
06300316 | 685 | |
fe7041b3 PP |
686 | @param[in] trace_class Trace class of which to get the clock class |
687 | named \p name. | |
688 | @param[in] name Name of the clock class to find in \p trace_class. | |
689 | @returns Clock class named \p name in \p trace_class, | |
690 | or \c NULL on error. | |
06300316 PP |
691 | |
692 | @prenotnull{trace_class} | |
693 | @prenotnull{name} | |
694 | @postrefcountsame{trace_class} | |
695 | @postsuccessrefcountretinc | |
696 | ||
839d52a5 | 697 | @sa bt_trace_get_clock_class_by_index(): Returns the clock class contained |
ac0c6bdd | 698 | in a given trace class at a given index. |
839d52a5 | 699 | @sa bt_trace_add_clock_class(): Adds a clock class to a trace class. |
06300316 | 700 | */ |
5fe68922 PP |
701 | static inline |
702 | struct bt_clock_class *bt_trace_get_clock_class_by_name( | |
703 | struct bt_trace *trace_class, const char *name) | |
704 | { | |
705 | return bt_get(bt_trace_borrow_clock_class_by_name(trace_class, name)); | |
706 | } | |
ef0c4a15 | 707 | |
06300316 PP |
708 | /** |
709 | @brief Adds the CTF IR clock class \p clock_class to the CTF IR | |
710 | trace class \p trace_class. | |
ef0c4a15 | 711 | |
fe7041b3 | 712 | On success, \p trace_class contains \p clock_class. |
06300316 | 713 | |
fe7041b3 PP |
714 | You can call this function even if \p trace_class or \p clock_class |
715 | are frozen. | |
06300316 PP |
716 | |
717 | @param[in] trace_class Trace class to which to add \p clock_class. | |
718 | @param[in] clock_class Clock class to add to \p trace_class. | |
719 | @returns 0 on success, or a negative value on error. | |
720 | ||
721 | @prenotnull{trace_class} | |
722 | @prenotnull{clock_class} | |
723 | @postrefcountsame{trace_class} | |
724 | @postsuccessrefcountinc{clock_class} | |
30484384 | 725 | @post <strong>On success, if \p trace_class is frozen</strong>, |
2c1c33a4 | 726 | \p clock_class is frozen. |
06300316 | 727 | |
839d52a5 | 728 | @sa bt_trace_get_clock_class_by_index(): Returns the clock class contained |
ac0c6bdd | 729 | in a given trace class at a given index. |
839d52a5 | 730 | @sa bt_trace_get_clock_class_by_name(): Finds a clock class by name |
fe7041b3 | 731 | in a given trace class. |
06300316 | 732 | */ |
839d52a5 PP |
733 | extern int bt_trace_add_clock_class(struct bt_trace *trace_class, |
734 | struct bt_clock_class *clock_class); | |
06300316 PP |
735 | |
736 | /** @} */ | |
737 | ||
738 | /** | |
739 | @name Stream class children functions | |
740 | @{ | |
741 | */ | |
742 | ||
743 | /** | |
744 | @brief Returns the number of stream classes contained in the | |
745 | CTF IR trace class \p trace_class. | |
746 | ||
747 | @param[in] trace_class Trace class of which to get the number | |
748 | of children stream classes. | |
749 | @returns Number of children stream classes | |
750 | contained in \p trace_class, or a negative | |
751 | value on error. | |
752 | ||
753 | @prenotnull{trace_class} | |
754 | @postrefcountsame{trace_class} | |
755 | */ | |
839d52a5 PP |
756 | extern int64_t bt_trace_get_stream_class_count( |
757 | struct bt_trace *trace_class); | |
06300316 | 758 | |
5fe68922 PP |
759 | extern struct bt_stream_class *bt_trace_borrow_stream_class_by_index( |
760 | struct bt_trace *trace_class, uint64_t index); | |
761 | ||
06300316 PP |
762 | /** |
763 | @brief Returns the stream class at index \p index in the CTF IR trace | |
764 | class \p trace_class. | |
765 | ||
766 | @param[in] trace_class Trace class of which to get the stream class. | |
767 | @param[in] index Index of the stream class to find. | |
768 | @returns Stream class at index \p index, or \c NULL | |
769 | on error. | |
770 | ||
771 | @prenotnull{trace_class} | |
772 | @pre \p index is lesser than the number of stream classes contained in | |
773 | the trace class \p trace_class (see | |
839d52a5 | 774 | bt_trace_get_stream_class_count()). |
06300316 | 775 | @postrefcountsame{trace_class} |
06300316 | 776 | |
839d52a5 PP |
777 | @sa bt_trace_get_stream_class_by_id(): Finds a stream class by ID. |
778 | @sa bt_trace_add_stream_class(): Adds a stream class to a trace class. | |
06300316 | 779 | */ |
5fe68922 PP |
780 | static inline |
781 | struct bt_stream_class *bt_trace_get_stream_class_by_index( | |
782 | struct bt_trace *trace_class, uint64_t index) | |
783 | { | |
784 | return bt_get(bt_trace_borrow_stream_class_by_index( | |
785 | trace_class, index)); | |
786 | } | |
787 | ||
788 | extern struct bt_stream_class *bt_trace_borrow_stream_class_by_id( | |
789 | struct bt_trace *trace_class, uint64_t id); | |
ef0c4a15 | 790 | |
06300316 PP |
791 | /** |
792 | @brief Returns the stream class with ID \c id found in the CTF IR | |
793 | trace class \p trace_class. | |
794 | ||
795 | @param[in] trace_class Trace class of which to get the stream class. | |
796 | @param[in] id ID of the stream class to find. | |
797 | @returns Stream class with ID \p id, or \c NULL | |
798 | on error. | |
799 | ||
800 | @prenotnull{trace_class} | |
801 | @postrefcountsame{trace_class} | |
802 | @postsuccessrefcountretinc | |
803 | ||
839d52a5 | 804 | @sa bt_trace_get_stream_class_by_index(): Returns the stream class contained |
ac0c6bdd | 805 | in a given trace class at a given index. |
839d52a5 | 806 | @sa bt_trace_add_stream_class(): Adds a stream class to a trace class. |
06300316 | 807 | */ |
5fe68922 PP |
808 | static inline |
809 | struct bt_stream_class *bt_trace_get_stream_class_by_id( | |
810 | struct bt_trace *trace_class, uint64_t id) | |
811 | { | |
812 | return bt_get(bt_trace_borrow_stream_class_by_id(trace_class, id)); | |
813 | } | |
4841ccc1 | 814 | |
06300316 PP |
815 | /** |
816 | @brief Adds the CTF IR stream class \p stream_class to the | |
817 | CTF IR trace class \p trace_class. | |
7e4347a3 | 818 | |
06300316 | 819 | On success, \p stream_class becomes the child of \p trace_class. |
bc37ae52 | 820 | |
06300316 | 821 | You can only add a given stream class to one trace class. |
4ed90fb3 | 822 | |
06300316 | 823 | You can call this function even if \p trace_class is frozen. |
bc37ae52 | 824 | |
4cdafd51 PP |
825 | This function tries to resolve the needed |
826 | \link ctfirfieldtypes CTF IR field type\endlink of the dynamic field | |
827 | types that are found anywhere in the root field types of | |
828 | \p stream_class and of all its currently contained | |
829 | \link ctfireventclass CTF IR event classes\endlink. If any automatic | |
830 | resolving fails, then this function fails. | |
831 | ||
06300316 PP |
832 | @param[in] trace_class Trace class to which to add \p stream_class. |
833 | @param[in] stream_class Stream class to add to \p trace_class. | |
834 | @returns 0 on success, or a negative value on error. | |
d246b111 | 835 | |
06300316 PP |
836 | @prenotnull{trace_class} |
837 | @prenotnull{stream_class} | |
838 | @postrefcountsame{trace_class} | |
839 | @postsuccessrefcountinc{stream_class} | |
2c1c33a4 | 840 | @postsuccessfrozen{stream_class} |
d246b111 | 841 | |
839d52a5 | 842 | @sa bt_trace_get_stream_class_by_index(): Returns the stream class contained |
ac0c6bdd | 843 | in a given trace class at a given index. |
839d52a5 | 844 | @sa bt_trace_get_stream_class_by_id(): Finds a stream class by ID. |
06300316 | 845 | */ |
839d52a5 PP |
846 | extern int bt_trace_add_stream_class(struct bt_trace *trace_class, |
847 | struct bt_stream_class *stream_class); | |
06300316 PP |
848 | |
849 | /** @} */ | |
850 | ||
c1e730fe PP |
851 | /** |
852 | @name Stream children functions | |
853 | @{ | |
854 | */ | |
855 | ||
856 | /** | |
857 | @brief Returns the number of streams contained in the CTF IR trace | |
858 | class \p trace_class. | |
859 | ||
860 | @param[in] trace_class Trace class of which to get the number | |
861 | of children streams. | |
862 | @returns Number of children streams | |
863 | contained in \p trace_class, or a negative | |
864 | value on error. | |
865 | ||
866 | @prenotnull{trace_class} | |
867 | @postrefcountsame{trace_class} | |
868 | */ | |
839d52a5 | 869 | extern int64_t bt_trace_get_stream_count(struct bt_trace *trace_class); |
c1e730fe | 870 | |
5fe68922 PP |
871 | extern struct bt_stream *bt_trace_borrow_stream_by_index( |
872 | struct bt_trace *trace_class, uint64_t index); | |
873 | ||
c1e730fe PP |
874 | /** |
875 | @brief Returns the stream at index \p index in the CTF IR trace | |
876 | class \p trace_class. | |
877 | ||
878 | @param[in] trace_class Trace class of which to get the stream. | |
879 | @param[in] index Index of the stream to find. | |
880 | @returns Stream at index \p index, or \c NULL | |
881 | on error. | |
882 | ||
883 | @prenotnull{trace_class} | |
884 | @pre \p index is lesser than the number of streams contained in | |
885 | the trace class \p trace_class (see | |
839d52a5 | 886 | bt_trace_get_stream_count()). |
c1e730fe PP |
887 | @postrefcountsame{trace_class} |
888 | */ | |
5fe68922 PP |
889 | static inline |
890 | struct bt_stream *bt_trace_get_stream_by_index( | |
891 | struct bt_trace *trace_class, uint64_t index) | |
892 | { | |
893 | return bt_get(bt_trace_borrow_stream_by_index(trace_class, index)); | |
894 | } | |
c1e730fe PP |
895 | |
896 | /** @} */ | |
897 | ||
06300316 PP |
898 | /** |
899 | @name Misc. functions | |
900 | @{ | |
901 | */ | |
902 | ||
5acf2ae6 PP |
903 | /** |
904 | @brief Returns whether or not the CTF IR trace class \p trace_class | |
905 | is static. | |
906 | ||
907 | It is guaranteed that a static trace class will never contain new | |
908 | streams, stream classes, or clock classes. A static class is always | |
909 | frozen. | |
910 | ||
839d52a5 | 911 | This function returns #BT_TRUE if bt_trace_set_is_static() was |
5acf2ae6 PP |
912 | previously called on it. |
913 | ||
914 | @param[in] trace_class Trace class to check. | |
c55a9f58 | 915 | @returns #BT_TRUE if \p trace_class is static, |
5acf2ae6 | 916 | |
839d52a5 | 917 | @sa bt_trace_set_is_static(): Makes a trace class static. |
5acf2ae6 | 918 | */ |
839d52a5 | 919 | extern bt_bool bt_trace_is_static(struct bt_trace *trace_class); |
5acf2ae6 PP |
920 | |
921 | /** | |
922 | @brief Makes the CTF IR trace class \p trace_class static. | |
923 | ||
924 | A static trace class is frozen and you cannot call any modifying | |
925 | function on it: | |
926 | ||
839d52a5 PP |
927 | - bt_trace_add_stream_class() |
928 | - bt_trace_add_clock_class() | |
929 | - bt_trace_set_environment_field() | |
930 | - bt_trace_set_environment_field_integer() | |
931 | - bt_trace_set_environment_field_string() | |
932 | - bt_trace_add_is_static_listener() | |
5acf2ae6 | 933 | |
839d52a5 | 934 | You cannot create a stream with bt_stream_create() with any of the |
5acf2ae6 PP |
935 | stream classes of a static trace class. |
936 | ||
937 | @param[in] trace_class Trace class to make static. | |
938 | @returns 0 on success, or a negative value on error. | |
939 | ||
940 | @prenotnull{trace_class} | |
941 | @postrefcountsame{trace_class} | |
942 | @postsuccessfrozen{trace_class} | |
943 | ||
839d52a5 | 944 | @sa bt_trace_is_static(): Checks whether or not a given trace class |
5acf2ae6 | 945 | is static. |
839d52a5 | 946 | @sa bt_trace_add_is_static_listener(): Adds a listener to a trace |
3602afb0 | 947 | class which is called when the trace class is made static. |
5acf2ae6 | 948 | */ |
839d52a5 | 949 | extern int bt_trace_set_is_static(struct bt_trace *trace_class); |
5acf2ae6 | 950 | |
3602afb0 PP |
951 | /** |
952 | @brief Adds the listener \p listener to the CTF IR trace class | |
953 | \p trace_class which is called when the trace is made static. | |
954 | ||
955 | \p listener is called with \p data, the user data, the first time | |
839d52a5 | 956 | bt_trace_set_is_static() is called on \p trace_class. |
3602afb0 | 957 | |
9962ad4b | 958 | When the trace is destroyed, or when you remove the added listener with |
839d52a5 | 959 | bt_trace_remove_is_static_listener(), \p listener_removed is called |
9962ad4b PP |
960 | if it's not \c NULL. You can use \p listener_removed to free any dynamic |
961 | data which exists only for the added listener. You cannot call | |
962 | any function which modifies \p trace_class during the execution of | |
839d52a5 | 963 | \p listener_removed, including bt_trace_remove_is_static_listener(). |
9962ad4b | 964 | |
3602afb0 | 965 | This function fails if \p trace_class is already static: you need to |
839d52a5 | 966 | check the condition first with bt_trace_is_static(). |
3602afb0 PP |
967 | |
968 | On success, this function returns a unique numeric identifier for this | |
969 | listener within \p trace. You can use this identifier to remove the | |
970 | specific listener you added with | |
839d52a5 | 971 | bt_trace_remove_is_static_listener(). |
3602afb0 | 972 | |
9962ad4b PP |
973 | @param[in] trace_class Trace class to which to add the |
974 | listener. | |
975 | @param[in] listener Listener to add to \p trace_class. | |
976 | @param[in] listener_removed Remove listener called when \p listener | |
977 | is removed from \p trace_class, or | |
978 | \c NULL if you don't need a remove | |
979 | listener. | |
980 | @param[in] data User data passed when \p listener or | |
981 | \p listener_removed is called. | |
982 | @returns A unique numeric identifier for this | |
983 | listener on success (0 or greater), or a | |
984 | negative value on error. | |
3602afb0 PP |
985 | |
986 | @prenotnull{trace_class} | |
987 | @prenotnull{listener} | |
988 | @pre \p trace_class is not static. | |
989 | @postrefcountsame{trace_class} | |
990 | ||
839d52a5 | 991 | @sa bt_trace_remove_is_static_listener(): Removes a "trace is |
3602afb0 PP |
992 | static" listener from a trace class previously added with this |
993 | function. | |
839d52a5 | 994 | @sa bt_trace_is_static(): Checks whether or not a given trace class |
3602afb0 | 995 | is static. |
839d52a5 | 996 | @sa bt_trace_set_is_static(): Makes a trace class static. |
3602afb0 | 997 | */ |
839d52a5 PP |
998 | extern int bt_trace_add_is_static_listener( |
999 | struct bt_trace *trace_class, | |
1000 | bt_trace_is_static_listener listener, | |
1001 | bt_trace_listener_removed listener_removed, void *data); | |
3602afb0 PP |
1002 | |
1003 | /** | |
1004 | @brief Removes the "trace is static" listener identified by | |
1005 | \p listener_id from the trace class \p trace_class. | |
1006 | ||
1007 | @param[in] trace_class Trace class from which to remove the listener | |
1008 | identified by \p listener_id. | |
1009 | @param[in] listener_id Identifier of the listener to remove from | |
1010 | \p trace_class. | |
1011 | @returns 0 if this function removed the listener, or | |
1012 | a negative value on error. | |
1013 | ||
1014 | @prenotnull{trace_class} | |
1015 | @pre \p listener_id is the identifier of a listener that you previously | |
839d52a5 | 1016 | added with bt_trace_add_is_static_listener() and did not |
3602afb0 PP |
1017 | already remove with this function. |
1018 | @postrefcountsame{trace_class} | |
1019 | ||
839d52a5 | 1020 | @sa bt_trace_add_is_static_listener(): Adds a listener to a trace |
3602afb0 PP |
1021 | class which is called when the trace class is made static. |
1022 | */ | |
839d52a5 PP |
1023 | extern int bt_trace_remove_is_static_listener( |
1024 | struct bt_trace *trace_class, int listener_id); | |
3602afb0 | 1025 | |
06300316 PP |
1026 | /** |
1027 | @brief Accepts the visitor \p visitor to visit the hierarchy of the | |
1028 | CTF IR trace class \p trace_class. | |
1029 | ||
1030 | This function traverses the hierarchy of \p trace_class in pre-order | |
1031 | and calls \p visitor on each element. | |
1032 | ||
1033 | The trace class itself is visited first, then, for each children stream | |
1034 | class, the stream class itself, and all its children event classes. | |
1035 | ||
1036 | @param[in] trace_class Trace class to visit. | |
1037 | @param[in] visitor Visiting function. | |
1038 | @param[in] data User data. | |
1039 | @returns 0 on success, or a negative value on error. | |
1040 | ||
1041 | @prenotnull{trace_class} | |
1042 | @prenotnull{visitor} | |
1043 | */ | |
839d52a5 PP |
1044 | extern int bt_trace_visit(struct bt_trace *trace_class, |
1045 | bt_visitor visitor, void *data); | |
8bf65fbd | 1046 | |
06300316 PP |
1047 | /** @} */ |
1048 | ||
35827558 PP |
1049 | /** @} */ |
1050 | ||
bc37ae52 JG |
1051 | #ifdef __cplusplus |
1052 | } | |
1053 | #endif | |
1054 | ||
1055 | #endif /* BABELTRACE_CTF_IR_TRACE_H */ |