1 #ifndef BABELTRACE_CTF_IR_TRACE_H
2 #define BABELTRACE_CTF_IR_TRACE_H
5 * BabelTrace - CTF IR: Trace
7 * Copyright 2014 Jérémie Galarneau <jeremie.galarneau@efficios.com>
9 * Author: Jérémie Galarneau <jeremie.galarneau@efficios.com>
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:
18 * The above copyright notice and this permission notice shall be included in
19 * all copies or substantial portions of the Software.
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
29 * The Common Trace Format (CTF) Specification is available at
30 * http://www.efficios.com/ctf
33 #include <babeltrace/ctf-ir/field-types.h>
34 #include <babeltrace/ctf-ir/visitor.h>
35 #include <babeltrace/values.h>
36 #include <babeltrace/graph/notification.h>
37 #include <babeltrace/types.h>
45 @defgroup ctfirtraceclass CTF IR trace class
47 @brief CTF IR trace class.
50 #include <babeltrace/ctf-ir/trace.h>
53 A CTF IR <strong><em>trace class</em></strong> is a descriptor of
56 You can obtain a trace class in two different modes:
58 - <strong>Normal mode</strong>: use bt_ctf_trace_create() to create a
59 default, empty trace class.
60 - <strong>CTF writer mode</strong>: use bt_ctf_writer_get_trace() to
61 get the trace class created by a given CTF writer object.
63 A trace class has the following properties:
66 - A <strong>native byte order</strong>: all the
67 \link ctfirfieldtypes field types\endlink eventually part of the trace
68 class with a byte order set to #BT_CTF_BYTE_ORDER_NATIVE have this
71 - An \b environment, which is a custom key-value mapping. Keys are
72 strings and values can be strings or integers.
74 In the Babeltrace CTF IR system, a trace class contains zero or more
75 \link ctfirstreamclass stream classes\endlink, and a stream class
76 contains zero or more \link ctfireventclass event classes\endlink. You
77 can add an event class to a stream class with
78 bt_ctf_stream_class_add_event_class(). You can add a stream class to a
79 trace class with bt_ctf_trace_add_stream_class().
81 You can access the streams of a trace, that is, the streams which were
82 created from the trace's stream classes with bt_ctf_stream_create(),
83 with bt_ctf_trace_get_stream_by_index().
85 A trace class owns the <strong>trace packet header</strong>
86 \link ctfirfieldtypes field type\endlink, which represents the
87 \c trace.packet.header CTF scope. This field type describes the
88 trace packet header fields of the traces that this trace class
91 The trace packet header field type \em must be a structure field type as
92 of Babeltrace \btversion.
94 As per the CTF specification, the trace packet header field type \em
95 must contain a field named \c stream_id if the trace class contains more
96 than one stream class.
98 As a reminder, here's the structure of a CTF packet:
102 A trace class also contains zero or more
103 \link ctfirclockclass CTF IR clock classes\endlink.
106 Elaborate about clock classes irt clock values.
108 As with any Babeltrace object, CTF IR trace class objects have
109 <a href="https://en.wikipedia.org/wiki/Reference_counting">reference
110 counts</a>. See \ref refs to learn more about the reference counting
111 management of Babeltrace objects.
113 The following functions \em freeze their trace class parameter on
116 - bt_ctf_trace_add_stream_class()
117 - bt_ctf_writer_create_stream()
118 (\link ctfwriter CTF writer\endlink mode only)
120 You cannot modify a frozen trace class: it is considered immutable,
123 - Adding a stream class to it with
124 bt_ctf_trace_add_stream_class().
125 - Adding a CTF IR clock class to it with bt_ctf_trace_add_clock_class().
126 - \link refs Reference counting\endlink.
133 @brief CTF IR trace class type and functions.
136 @addtogroup ctfirtraceclass
142 @brief A CTF IR trace class.
146 struct bt_ctf_stream
;
147 struct bt_ctf_stream_class
;
148 struct bt_ctf_clock_class
;
151 @brief User function type to use with
152 bt_ctf_trace_add_is_static_listener().
154 @param[in] trace_class Trace class which is now static.
155 @param[in] data User data as passed to
156 bt_ctf_trace_add_is_static_listener() when
157 you added the listener.
159 @prenotnull{trace_class}
161 typedef void (* bt_ctf_trace_is_static_listener
)(
162 struct bt_ctf_trace
*trace_class
, void *data
);
165 @brief User function type to use with
166 bt_ctf_trace_add_is_static_listener().
168 @param[in] trace_class Trace class to which the listener was added.
169 @param[in] data User data as passed to
170 bt_ctf_trace_add_is_static_listener() when
171 you added the listener.
173 @prenotnull{trace_class}
175 typedef void (* bt_ctf_trace_listener_removed
)(
176 struct bt_ctf_trace
*trace_class
, void *data
);
179 @name Creation function
184 @brief Creates a default CTF IR trace class.
186 On success, the trace packet header field type of the created trace
187 class is an empty structure field type. You can modify this default
188 trace packet header field type after the trace class is created with
189 bt_ctf_trace_get_packet_header_type() and
190 bt_ctf_trace_set_packet_header_type().
192 The created trace class has the following initial properties:
194 - <strong>Name</strong>: none. You can set a name
195 with bt_ctf_trace_set_name().
196 - <strong>UUID</strong>: none. You can set a UUID with
197 bt_ctf_trace_set_uuid().
198 - <strong>Native byte order</strong>: #BT_CTF_BYTE_ORDER_UNSPECIFIED.
199 You can set a native byte order with
200 bt_ctf_trace_set_native_byte_order().
201 - <strong>Environment</strong>: empty. You can add environment entries
202 with bt_ctf_trace_set_environment_field(),
203 bt_ctf_trace_set_environment_field_integer(), and
204 bt_ctf_trace_set_environment_field_string().
206 @returns Created trace class, or \c NULL on error.
208 @postsuccessrefcountret1
210 extern struct bt_ctf_trace
*bt_ctf_trace_create(void);
215 @name Properties functions
220 @brief Returns the name of the CTF IR trace class \p trace_class.
222 On success, \p trace_class remains the sole owner of the returned
223 string. The returned string is valid as long as \p trace_class exists
226 @param[in] trace_class Trace class of which to get the name.
227 @returns Name of trace class \p trace_class, or
228 \c NULL if \p trace_class is unnamed or
231 @prenotnull{trace_class}
232 @postrefcountsame{trace_class}
234 @sa bt_ctf_trace_set_name(): Sets the name of a given trace class.
236 extern const char *bt_ctf_trace_get_name(struct bt_ctf_trace
*trace_class
);
239 @brief Sets the name of the CTF IR trace class \p trace_class
242 @param[in] trace_class Trace class of which to set the name.
243 @param[in] name Name of the trace class (copied on success).
244 @returns 0 on success, or a negative value on error.
246 @prenotnull{trace_class}
249 @postrefcountsame{trace_class}
251 @sa bt_ctf_trace_get_name(): Returns the name of a given trace class.
253 extern int bt_ctf_trace_set_name(struct bt_ctf_trace
*trace_class
,
257 @brief Returns the native byte order of the CTF IR trace class
260 @param[in] trace_class Trace class of which to get the default byte
262 @returns Native byte order of \p trace_class,
263 or #BT_CTF_BYTE_ORDER_UNKNOWN on error.
265 @prenotnull{trace_class}
266 @postrefcountsame{trace_class}
268 @sa bt_ctf_trace_set_native_byte_order(): Sets the native byte order of
271 extern enum bt_ctf_byte_order
bt_ctf_trace_get_native_byte_order(
272 struct bt_ctf_trace
*trace_class
);
275 @brief Sets the native byte order of the CTF IR trace class
276 \p trace_class to \p native_byte_order.
278 \p native_byte_order \em must be one of:
280 - #BT_CTF_BYTE_ORDER_LITTLE_ENDIAN
281 - #BT_CTF_BYTE_ORDER_BIG_ENDIAN
282 - #BT_CTF_BYTE_ORDER_NETWORK
283 - <strong>If the trace is not in CTF writer mode<strong>,
284 #BT_CTF_BYTE_ORDER_UNSPECIFIED.
286 @param[in] trace_class Trace class of which to set the native byte
288 @param[in] native_byte_order Native byte order of the trace class.
289 @returns 0 on success, or a negative value on error.
291 @prenotnull{trace_class}
293 @pre \p native_byte_order is either #BT_CTF_BYTE_ORDER_UNSPECIFIED (if the
294 trace is not in CTF writer mode),
295 #BT_CTF_BYTE_ORDER_LITTLE_ENDIAN, #BT_CTF_BYTE_ORDER_BIG_ENDIAN, or
296 #BT_CTF_BYTE_ORDER_NETWORK.
297 @postrefcountsame{trace_class}
299 @sa bt_ctf_trace_get_native_byte_order(): Returns the native byte order of a
302 extern int bt_ctf_trace_set_native_byte_order(struct bt_ctf_trace
*trace_class
,
303 enum bt_ctf_byte_order native_byte_order
);
306 @brief Returns the UUID of the CTF IR trace class \p trace_class.
308 On success, the return value is an array of 16 bytes.
310 @param[in] trace_class Trace class of which to get the UUID.
311 @returns UUID of trace class \p trace_class, or
312 \c NULL if \p trace_class has no UUID or on error.
314 @prenotnull{trace_class}
315 @postrefcountsame{trace_class}
317 @sa bt_ctf_trace_set_uuid(): Sets the UUID of a given trace class.
319 extern const unsigned char *bt_ctf_trace_get_uuid(
320 struct bt_ctf_trace
*trace_class
);
323 @brief Sets the UUID of the CTF IR trace class \p trace_class to
326 \p uuid \em must be an array of 16 bytes.
328 @param[in] trace_class Trace class of which to set the UUID.
329 @param[in] uuid UUID of the \p trace_class (copied on
331 @returns 0 on success, or a negative value on error.
333 @prenotnull{trace_class}
336 @pre \p uuid is an array of 16 bytes.
337 @postrefcountsame{trace_class}
339 @sa bt_ctf_trace_get_uuid(): Returns the UUID of a given trace class.
341 extern int bt_ctf_trace_set_uuid(struct bt_ctf_trace
*trace_class
,
342 const unsigned char *uuid
);
345 @brief Returns the number of entries contained in the environment of
346 the CTF IR trace class \p trace_class.
348 @param[in] trace_class Trace class of which to get the number
349 of environment entries.
350 @returns Number of environment entries
351 contained in \p trace_class, or
352 a negative value on error.
354 @prenotnull{trace_class}
355 @postrefcountsame{trace_class}
357 extern int64_t bt_ctf_trace_get_environment_field_count(
358 struct bt_ctf_trace
*trace_class
);
361 @brief Returns the field name of the environment entry at index
362 \p index in the CTF IR trace class \p trace_class.
364 On success, the returned string is valid as long as this trace class
365 exists and is \em not modified. \p trace_class remains the sole owner of
368 @param[in] trace_class Trace class of which to get the name of the
369 environment entry at index \p index.
370 @param[in] index Index of environment entry to find.
371 @returns Name of the environment entry at index \p index
372 in \p trace_class, or \c NULL on error.
374 @prenotnull{trace_class}
375 @pre \p index is lesser than the number of environment entries in
376 \p trace_class (see bt_ctf_trace_get_environment_field_count()).
377 @postrefcountsame{trace_class}
379 @sa bt_ctf_trace_get_environment_field_value_by_index(): Finds a trace class's
380 environment entry by index.
381 @sa bt_ctf_trace_get_environment_field_value_by_name(): Finds a trace
382 class's environment entry by name.
383 @sa bt_ctf_trace_set_environment_field(): Sets the value of a trace
384 class's environment entry.
387 bt_ctf_trace_get_environment_field_name_by_index(
388 struct bt_ctf_trace
*trace_class
, uint64_t index
);
391 @brief Returns the value of the environment entry at index
392 \p index in the CTF IR trace class \p trace_class.
394 @param[in] trace_class Trace class of which to get the value of the
395 environment entry at index \p index.
396 @param[in] index Index of the environment entry to find.
397 @returns Value of the environment entry at index \p index
398 in \p trace_class, or \c NULL on error.
400 @prenotnull{trace_class}
401 @pre \p index is lesser than the number of environment entries in
402 \p trace_class (see bt_ctf_trace_get_environment_field_count()).
403 @postrefcountsame{trace_class}
404 @postsuccessrefcountretinc
406 @sa bt_ctf_trace_get_environment_field_value_by_name(): Finds a trace
407 class's environment entry by name.
408 @sa bt_ctf_trace_set_environment_field(): Sets the value of a trace
409 class's environment entry.
411 extern struct bt_value
*
412 bt_ctf_trace_get_environment_field_value_by_index(struct bt_ctf_trace
*trace_class
,
416 @brief Returns the value of the environment entry named \p name
417 in the CTF IR trace class \p trace_class.
419 @param[in] trace_class Trace class of which to get the value of the
420 environment entry named \p name.
421 @param[in] name Name of the environment entry to find.
422 @returns Value of the environment entry named \p name
423 in \p trace_class, or \c NULL if there's no such
426 @prenotnull{trace_class}
428 @postrefcountsame{trace_class}
429 @postsuccessrefcountretinc
431 @sa bt_ctf_trace_get_environment_field_value_by_index(): Finds a trace class's
432 environment entry by index.
433 @sa bt_ctf_trace_set_environment_field(): Sets the value of a trace
434 class's environment entry.
436 extern struct bt_value
*
437 bt_ctf_trace_get_environment_field_value_by_name(
438 struct bt_ctf_trace
*trace_class
, const char *name
);
441 @brief Sets the environment entry named \p name in the
442 CTF IR trace class \p trace_class to \p value.
444 If an environment entry named \p name exists in \p trace_class, its
445 value is first put, and then replaced by \p value.
447 @param[in] trace_class Trace class of which to set the environment
449 @param[in] name Name of the environment entry to set (copied
451 @param[in] value Value of the environment entry named \p name.
452 @returns 0 on success, or a negative value on error.
454 @prenotnull{trace_class}
459 \link bt_value_integer_create() integer value object\endlink
461 \link bt_value_string_create() string value object\endlink.
462 @postrefcountsame{trace_class}
463 @postsuccessrefcountinc{value}
465 @sa bt_ctf_trace_get_environment_field_value_by_index(): Finds a trace class's
466 environment entry by index.
467 @sa bt_ctf_trace_get_environment_field_value_by_name(): Finds a trace
468 class's environment entry by name.
470 extern int bt_ctf_trace_set_environment_field(
471 struct bt_ctf_trace
*trace_class
, const char *name
,
472 struct bt_value
*value
);
475 @brief Sets the environment entry named \p name in the
476 CTF IR trace class \p trace_class to \p value.
478 If an environment entry named \p name exists in \p trace_class, its
479 value is first put, and then replaced by a new
480 \link bt_value_integer_create() integer value object\endlink
483 @param[in] trace_class Trace class of which to set the environment
485 @param[in] name Name of the environment entry to set (copied
487 @param[in] value Value of the environment entry named \p name.
488 @returns 0 on success, or a negative value on error.
490 @prenotnull{trace_class}
493 @postrefcountsame{trace_class}
495 @sa bt_ctf_trace_set_environment_field(): Sets the value of a trace
496 class's environment entry.
498 extern int bt_ctf_trace_set_environment_field_integer(
499 struct bt_ctf_trace
*trace_class
, const char *name
,
503 @brief Sets the environment entry named \p name in the
504 CTF IR trace class \p trace_class to \p value.
506 If an environment entry named \p name exists in \p trace_class, its
507 value is first put, and then replaced by a new
508 \link bt_value_string_create() string value object\endlink
511 @param[in] trace_class Trace class of which to set the environment
513 @param[in] name Name of the environment entry to set (copied
515 @param[in] value Value of the environment entry named \p name
517 @returns 0 on success, or a negative value on error.
519 @prenotnull{trace_class}
523 @postrefcountsame{trace_class}
525 @sa bt_ctf_trace_set_environment_field(): Sets the value of a trace
526 class's environment entry.
528 extern int bt_ctf_trace_set_environment_field_string(
529 struct bt_ctf_trace
*trace_class
, const char *name
,
535 @name Contained field types functions
540 @brief Returns the packet header field type of the CTF IR trace class
543 @param[in] trace_class Trace class of which to get the packet
545 @returns Packet header field type of \p trace_class,
546 or \c NULL if \p trace_class has no packet header field
549 @prenotnull{trace_class}
550 @postrefcountsame{trace_class}
551 @post <strong>On success, if the return value is a field type</strong>, its
552 reference count is incremented.
554 @sa bt_ctf_trace_set_packet_header_type(): Sets the packet
555 header field type of a given trace class.
557 extern struct bt_ctf_field_type
*bt_ctf_trace_get_packet_header_type(
558 struct bt_ctf_trace
*trace_class
);
561 @brief Sets the packet header field type of the CTF IR trace class
562 \p trace_class to \p packet_header_type, or unsets the current packet
563 header field type from \p trace_class.
565 If \p packet_header_type is \c NULL, then this function unsets the current
566 packet header field type from \p trace_class, effectively making \p trace_class
567 a trace without a packet header field type.
569 As of Babeltrace \btversion, if \p packet_header_type is not \c NULL,
570 \p packet_header_type \em must be a CTF IR structure field type object.
572 @param[in] trace_class Trace class of which to set the packet
574 @param[in] packet_header_type Packet header field type, or \c NULL to unset
575 the current packet header field type.
576 @returns 0 on success, or a negative value on error.
578 @prenotnull{trace_class}
580 @pre <strong>\p packet_header_type, if not \c NULL</strong>, is a CTF IR
581 structure field type.
582 @postrefcountsame{trace_class}
583 @post <strong>On success, if \p packet_header_type is not \c NULL</strong>,
584 the reference count of \p packet_header_type is incremented.
586 @sa bt_ctf_trace_get_packet_header_type(): Returns the packet
587 header field type of a given trace class.
589 extern int bt_ctf_trace_set_packet_header_type(struct bt_ctf_trace
*trace_class
,
590 struct bt_ctf_field_type
*packet_header_type
);
595 @name Contained clock classes functions
600 @brief Returns the number of CTF IR clock classes contained in the
601 CTF IR trace class \p trace_class.
603 @param[in] trace_class Trace class of which to get the number
604 of contained clock classes.
605 @returns Number of contained clock classes
606 contained in \p trace_class, or a negative
609 @prenotnull{trace_class}
610 @postrefcountsame{trace_class}
612 extern int64_t bt_ctf_trace_get_clock_class_count(
613 struct bt_ctf_trace
*trace_class
);
616 @brief Returns the CTF IR clock class at index \p index in the CTF
617 IR trace class \p trace_class.
619 @param[in] trace_class Trace class of which to get the clock class
620 contained at index \p index.
621 @param[in] index Index of the clock class to find in
623 @returns Clock class at index \p index in \p trace_class,
626 @prenotnull{trace_class}
627 @pre \p index is lesser than the number of clock classes contained in
628 the trace class \p trace_class (see
629 bt_ctf_trace_get_clock_class_count()).
630 @postrefcountsame{trace_class}
631 @postsuccessrefcountretinc
633 @sa bt_ctf_trace_get_clock_class_by_name(): Finds a clock class by name
634 in a given trace class.
635 @sa bt_ctf_trace_add_clock_class(): Adds a clock class to a trace class.
637 extern struct bt_ctf_clock_class
*bt_ctf_trace_get_clock_class_by_index(
638 struct bt_ctf_trace
*trace_class
, uint64_t index
);
641 @brief Returns the CTF IR clock class named \c name found in the CTF
642 IR trace class \p trace_class.
644 @param[in] trace_class Trace class of which to get the clock class
646 @param[in] name Name of the clock class to find in \p trace_class.
647 @returns Clock class named \p name in \p trace_class,
650 @prenotnull{trace_class}
652 @postrefcountsame{trace_class}
653 @postsuccessrefcountretinc
655 @sa bt_ctf_trace_get_clock_class_by_index(): Returns the clock class contained
656 in a given trace class at a given index.
657 @sa bt_ctf_trace_add_clock_class(): Adds a clock class to a trace class.
659 extern struct bt_ctf_clock_class
*bt_ctf_trace_get_clock_class_by_name(
660 struct bt_ctf_trace
*trace_class
, const char *name
);
663 @brief Adds the CTF IR clock class \p clock_class to the CTF IR
664 trace class \p trace_class.
666 On success, \p trace_class contains \p clock_class.
668 You can call this function even if \p trace_class or \p clock_class
671 @param[in] trace_class Trace class to which to add \p clock_class.
672 @param[in] clock_class Clock class to add to \p trace_class.
673 @returns 0 on success, or a negative value on error.
675 @prenotnull{trace_class}
676 @prenotnull{clock_class}
677 @postrefcountsame{trace_class}
678 @postsuccessrefcountinc{clock_class}
679 @post <strong>On success, if \p trace_class is frozen</strong>,
680 \p clock_class is frozen.
682 @sa bt_ctf_trace_get_clock_class_by_index(): Returns the clock class contained
683 in a given trace class at a given index.
684 @sa bt_ctf_trace_get_clock_class_by_name(): Finds a clock class by name
685 in a given trace class.
687 extern int bt_ctf_trace_add_clock_class(struct bt_ctf_trace
*trace_class
,
688 struct bt_ctf_clock_class
*clock_class
);
693 @name Stream class children functions
698 @brief Returns the number of stream classes contained in the
699 CTF IR trace class \p trace_class.
701 @param[in] trace_class Trace class of which to get the number
702 of children stream classes.
703 @returns Number of children stream classes
704 contained in \p trace_class, or a negative
707 @prenotnull{trace_class}
708 @postrefcountsame{trace_class}
710 extern int64_t bt_ctf_trace_get_stream_class_count(
711 struct bt_ctf_trace
*trace_class
);
714 @brief Returns the stream class at index \p index in the CTF IR trace
715 class \p trace_class.
717 @param[in] trace_class Trace class of which to get the stream class.
718 @param[in] index Index of the stream class to find.
719 @returns Stream class at index \p index, or \c NULL
722 @prenotnull{trace_class}
723 @pre \p index is lesser than the number of stream classes contained in
724 the trace class \p trace_class (see
725 bt_ctf_trace_get_stream_class_count()).
726 @postrefcountsame{trace_class}
728 @sa bt_ctf_trace_get_stream_class_by_id(): Finds a stream class by ID.
729 @sa bt_ctf_trace_add_stream_class(): Adds a stream class to a trace class.
731 extern struct bt_ctf_stream_class
*bt_ctf_trace_get_stream_class_by_index(
732 struct bt_ctf_trace
*trace_class
, uint64_t index
);
735 @brief Returns the stream class with ID \c id found in the CTF IR
736 trace class \p trace_class.
738 @param[in] trace_class Trace class of which to get the stream class.
739 @param[in] id ID of the stream class to find.
740 @returns Stream class with ID \p id, or \c NULL
743 @prenotnull{trace_class}
744 @postrefcountsame{trace_class}
745 @postsuccessrefcountretinc
747 @sa bt_ctf_trace_get_stream_class_by_index(): Returns the stream class contained
748 in a given trace class at a given index.
749 @sa bt_ctf_trace_add_stream_class(): Adds a stream class to a trace class.
751 extern struct bt_ctf_stream_class
*bt_ctf_trace_get_stream_class_by_id(
752 struct bt_ctf_trace
*trace_class
, uint64_t id
);
755 @brief Adds the CTF IR stream class \p stream_class to the
756 CTF IR trace class \p trace_class.
758 On success, \p stream_class becomes the child of \p trace_class.
760 You can only add a given stream class to one trace class.
762 You can call this function even if \p trace_class is frozen.
764 This function tries to resolve the needed
765 \link ctfirfieldtypes CTF IR field type\endlink of the dynamic field
766 types that are found anywhere in the root field types of
767 \p stream_class and of all its currently contained
768 \link ctfireventclass CTF IR event classes\endlink. If any automatic
769 resolving fails, then this function fails.
771 @param[in] trace_class Trace class to which to add \p stream_class.
772 @param[in] stream_class Stream class to add to \p trace_class.
773 @returns 0 on success, or a negative value on error.
775 @prenotnull{trace_class}
776 @prenotnull{stream_class}
777 @postrefcountsame{trace_class}
778 @postsuccessrefcountinc{stream_class}
779 @postsuccessfrozen{stream_class}
781 @sa bt_ctf_trace_get_stream_class_by_index(): Returns the stream class contained
782 in a given trace class at a given index.
783 @sa bt_ctf_trace_get_stream_class_by_id(): Finds a stream class by ID.
785 extern int bt_ctf_trace_add_stream_class(struct bt_ctf_trace
*trace_class
,
786 struct bt_ctf_stream_class
*stream_class
);
791 @name Stream children functions
796 @brief Returns the number of streams contained in the CTF IR trace
797 class \p trace_class.
799 @param[in] trace_class Trace class of which to get the number
801 @returns Number of children streams
802 contained in \p trace_class, or a negative
805 @prenotnull{trace_class}
806 @postrefcountsame{trace_class}
808 extern int64_t bt_ctf_trace_get_stream_count(struct bt_ctf_trace
*trace_class
);
811 @brief Returns the stream at index \p index in the CTF IR trace
812 class \p trace_class.
814 @param[in] trace_class Trace class of which to get the stream.
815 @param[in] index Index of the stream to find.
816 @returns Stream at index \p index, or \c NULL
819 @prenotnull{trace_class}
820 @pre \p index is lesser than the number of streams contained in
821 the trace class \p trace_class (see
822 bt_ctf_trace_get_stream_count()).
823 @postrefcountsame{trace_class}
825 extern struct bt_ctf_stream
*bt_ctf_trace_get_stream_by_index(
826 struct bt_ctf_trace
*trace_class
, uint64_t index
);
831 @name Misc. functions
836 @brief Returns whether or not the CTF IR trace class \p trace_class
839 It is guaranteed that a static trace class will never contain new
840 streams, stream classes, or clock classes. A static class is always
843 This function returns #BT_TRUE if bt_ctf_trace_set_is_static() was
844 previously called on it.
846 @param[in] trace_class Trace class to check.
847 @returns #BT_TRUE if \p trace_class is static,
849 @sa bt_ctf_trace_set_is_static(): Makes a trace class static.
851 extern bt_bool
bt_ctf_trace_is_static(struct bt_ctf_trace
*trace_class
);
854 @brief Makes the CTF IR trace class \p trace_class static.
856 A static trace class is frozen and you cannot call any modifying
859 - bt_ctf_trace_add_stream_class()
860 - bt_ctf_trace_add_clock_class()
861 - bt_ctf_trace_set_environment_field()
862 - bt_ctf_trace_set_environment_field_integer()
863 - bt_ctf_trace_set_environment_field_string()
864 - bt_ctf_trace_add_is_static_listener()
866 You cannot create a stream with bt_ctf_stream_create() with any of the
867 stream classes of a static trace class.
869 @param[in] trace_class Trace class to make static.
870 @returns 0 on success, or a negative value on error.
872 @prenotnull{trace_class}
873 @postrefcountsame{trace_class}
874 @postsuccessfrozen{trace_class}
876 @sa bt_ctf_trace_is_static(): Checks whether or not a given trace class
878 @sa bt_ctf_trace_add_is_static_listener(): Adds a listener to a trace
879 class which is called when the trace class is made static.
881 extern int bt_ctf_trace_set_is_static(struct bt_ctf_trace
*trace_class
);
884 @brief Adds the listener \p listener to the CTF IR trace class
885 \p trace_class which is called when the trace is made static.
887 \p listener is called with \p data, the user data, the first time
888 bt_ctf_trace_set_is_static() is called on \p trace_class.
890 When the trace is destroyed, or when you remove the added listener with
891 bt_ctf_trace_remove_is_static_listener(), \p listener_removed is called
892 if it's not \c NULL. You can use \p listener_removed to free any dynamic
893 data which exists only for the added listener. You cannot call
894 any function which modifies \p trace_class during the execution of
895 \p listener_removed, including bt_ctf_trace_remove_is_static_listener().
897 This function fails if \p trace_class is already static: you need to
898 check the condition first with bt_ctf_trace_is_static().
900 On success, this function returns a unique numeric identifier for this
901 listener within \p trace. You can use this identifier to remove the
902 specific listener you added with
903 bt_ctf_trace_remove_is_static_listener().
905 @param[in] trace_class Trace class to which to add the
907 @param[in] listener Listener to add to \p trace_class.
908 @param[in] listener_removed Remove listener called when \p listener
909 is removed from \p trace_class, or
910 \c NULL if you don't need a remove
912 @param[in] data User data passed when \p listener or
913 \p listener_removed is called.
914 @returns A unique numeric identifier for this
915 listener on success (0 or greater), or a
916 negative value on error.
918 @prenotnull{trace_class}
919 @prenotnull{listener}
920 @pre \p trace_class is not static.
921 @postrefcountsame{trace_class}
923 @sa bt_ctf_trace_remove_is_static_listener(): Removes a "trace is
924 static" listener from a trace class previously added with this
926 @sa bt_ctf_trace_is_static(): Checks whether or not a given trace class
928 @sa bt_ctf_trace_set_is_static(): Makes a trace class static.
930 extern int bt_ctf_trace_add_is_static_listener(
931 struct bt_ctf_trace
*trace_class
,
932 bt_ctf_trace_is_static_listener listener
,
933 bt_ctf_trace_listener_removed listener_removed
, void *data
);
936 @brief Removes the "trace is static" listener identified by
937 \p listener_id from the trace class \p trace_class.
939 @param[in] trace_class Trace class from which to remove the listener
940 identified by \p listener_id.
941 @param[in] listener_id Identifier of the listener to remove from
943 @returns 0 if this function removed the listener, or
944 a negative value on error.
946 @prenotnull{trace_class}
947 @pre \p listener_id is the identifier of a listener that you previously
948 added with bt_ctf_trace_add_is_static_listener() and did not
949 already remove with this function.
950 @postrefcountsame{trace_class}
952 @sa bt_ctf_trace_add_is_static_listener(): Adds a listener to a trace
953 class which is called when the trace class is made static.
955 extern int bt_ctf_trace_remove_is_static_listener(
956 struct bt_ctf_trace
*trace_class
, int listener_id
);
959 @brief Accepts the visitor \p visitor to visit the hierarchy of the
960 CTF IR trace class \p trace_class.
962 This function traverses the hierarchy of \p trace_class in pre-order
963 and calls \p visitor on each element.
965 The trace class itself is visited first, then, for each children stream
966 class, the stream class itself, and all its children event classes.
968 @param[in] trace_class Trace class to visit.
969 @param[in] visitor Visiting function.
970 @param[in] data User data.
971 @returns 0 on success, or a negative value on error.
973 @prenotnull{trace_class}
976 extern int bt_ctf_trace_visit(struct bt_ctf_trace
*trace_class
,
977 bt_ctf_visitor visitor
, void *data
);
987 #endif /* BABELTRACE_CTF_IR_TRACE_H */