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
34 #include <babeltrace/ref.h>
37 #include <babeltrace/ctf-ir/visitor.h>
40 #include <babeltrace/types.h>
51 @defgroup ctfirtraceclass CTF IR trace class
53 @brief CTF IR trace class.
56 #include <babeltrace/ctf-ir/trace.h>
59 A CTF IR <strong><em>trace class</em></strong> is a descriptor of
62 You can obtain a trace class in two different modes:
64 - <strong>Normal mode</strong>: use bt_trace_create() to create a
65 default, empty trace class.
66 - <strong>CTF writer mode</strong>: use bt_writer_get_trace() to
67 get the trace class created by a given CTF writer object.
69 A trace class has the following properties:
72 - A <strong>native byte order</strong>: all the
73 \link ctfirfieldtypes field types\endlink eventually part of the trace
74 class with a byte order set to #BT_BYTE_ORDER_NATIVE have this
77 - An \b environment, which is a custom key-value mapping. Keys are
78 strings and values can be strings or integers.
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
84 bt_stream_class_add_event_class(). You can add a stream class to a
85 trace class with bt_trace_add_stream_class().
87 You can access the streams of a trace, that is, the streams which were
88 created from the trace's stream classes with bt_stream_create(),
89 with bt_trace_get_stream_by_index().
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
97 The trace packet header field type \em must be a structure field type as
98 of Babeltrace \btversion.
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.
104 As a reminder, here's the structure of a CTF packet:
108 A trace class also contains zero or more
109 \link ctfirclockclass CTF IR clock classes\endlink.
112 Elaborate about clock classes irt clock values.
114 As with any Babeltrace object, CTF IR trace class objects have
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.
119 The following functions \em freeze their trace class parameter on
122 - bt_trace_add_stream_class()
123 - bt_writer_create_stream()
124 (\link ctfwriter CTF writer\endlink mode only)
126 You cannot modify a frozen trace class: it is considered immutable,
129 - Adding a stream class to it with
130 bt_trace_add_stream_class().
131 - Adding a CTF IR clock class to it with bt_trace_add_clock_class().
132 - \link refs Reference counting\endlink.
139 @brief CTF IR trace class type and functions.
142 @addtogroup ctfirtraceclass
148 @brief A CTF IR trace class.
153 struct bt_stream_class
;
154 struct bt_clock_class
;
157 @brief User function type to use with
158 bt_trace_add_is_static_listener().
160 @param[in] trace_class Trace class which is now static.
161 @param[in] data User data as passed to
162 bt_trace_add_is_static_listener() when
163 you added the listener.
165 @prenotnull{trace_class}
167 typedef void (* bt_trace_is_static_listener
)(
168 struct bt_trace
*trace_class
, void *data
);
171 @brief User function type to use with
172 bt_trace_add_is_static_listener().
174 @param[in] trace_class Trace class to which the listener was added.
175 @param[in] data User data as passed to
176 bt_trace_add_is_static_listener() when
177 you added the listener.
179 @prenotnull{trace_class}
181 typedef void (* bt_trace_listener_removed
)(
182 struct bt_trace
*trace_class
, void *data
);
185 @name Creation function
190 @brief Creates a default CTF IR trace class.
192 On success, the trace packet header field type of the created trace
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
195 bt_trace_get_packet_header_field_type() and
196 bt_trace_set_packet_header_field_type().
198 The created trace class has the following initial properties:
200 - <strong>Name</strong>: none. You can set a name
201 with bt_trace_set_name().
202 - <strong>UUID</strong>: none. You can set a UUID with
204 - <strong>Native byte order</strong>: #BT_BYTE_ORDER_UNSPECIFIED.
205 You can set a native byte order with
206 bt_trace_set_native_byte_order().
207 - <strong>Environment</strong>: empty. You can add environment entries
208 with bt_trace_set_environment_field(),
209 bt_trace_set_environment_field_integer(), and
210 bt_trace_set_environment_field_string().
212 @returns Created trace class, or \c NULL on error.
214 @postsuccessrefcountret1
216 extern struct bt_trace
*bt_trace_create(void);
221 @name Properties functions
226 @brief Returns the name of the CTF IR trace class \p trace_class.
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
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
237 @prenotnull{trace_class}
238 @postrefcountsame{trace_class}
240 @sa bt_trace_set_name(): Sets the name of a given trace class.
242 extern const char *bt_trace_get_name(struct bt_trace
*trace_class
);
245 @brief Sets the name of the CTF IR trace class \p trace_class
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.
252 @prenotnull{trace_class}
255 @postrefcountsame{trace_class}
257 @sa bt_trace_get_name(): Returns the name of a given trace class.
259 extern int bt_trace_set_name(struct bt_trace
*trace_class
,
263 @brief Returns the native byte order of the CTF IR trace class
266 @param[in] trace_class Trace class of which to get the default byte
268 @returns Native byte order of \p trace_class,
269 or #BT_BYTE_ORDER_UNKNOWN on error.
271 @prenotnull{trace_class}
272 @postrefcountsame{trace_class}
274 @sa bt_trace_set_native_byte_order(): Sets the native byte order of
277 extern enum bt_byte_order
bt_trace_get_native_byte_order(
278 struct bt_trace
*trace_class
);
281 @brief Sets the native byte order of the CTF IR trace class
282 \p trace_class to \p native_byte_order.
284 \p native_byte_order \em must be one of:
286 - #BT_BYTE_ORDER_LITTLE_ENDIAN
287 - #BT_BYTE_ORDER_BIG_ENDIAN
288 - #BT_BYTE_ORDER_NETWORK
289 - <strong>If the trace is not in CTF writer mode<strong>,
290 #BT_BYTE_ORDER_UNSPECIFIED.
292 @param[in] trace_class Trace class of which to set the native byte
294 @param[in] native_byte_order Native byte order of the trace class.
295 @returns 0 on success, or a negative value on error.
297 @prenotnull{trace_class}
299 @pre \p native_byte_order is either #BT_BYTE_ORDER_UNSPECIFIED (if the
300 trace is not in CTF writer mode),
301 #BT_BYTE_ORDER_LITTLE_ENDIAN, #BT_BYTE_ORDER_BIG_ENDIAN, or
302 #BT_BYTE_ORDER_NETWORK.
303 @postrefcountsame{trace_class}
305 @sa bt_trace_get_native_byte_order(): Returns the native byte order of a
308 extern int bt_trace_set_native_byte_order(struct bt_trace
*trace_class
,
309 enum bt_byte_order native_byte_order
);
312 @brief Returns the UUID of the CTF IR trace class \p trace_class.
314 On success, the return value is an array of 16 bytes.
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.
320 @prenotnull{trace_class}
321 @postrefcountsame{trace_class}
323 @sa bt_trace_set_uuid(): Sets the UUID of a given trace class.
325 extern const unsigned char *bt_trace_get_uuid(
326 struct bt_trace
*trace_class
);
329 @brief Sets the UUID of the CTF IR trace class \p trace_class to
332 \p uuid \em must be an array of 16 bytes.
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
337 @returns 0 on success, or a negative value on error.
339 @prenotnull{trace_class}
342 @pre \p uuid is an array of 16 bytes.
343 @postrefcountsame{trace_class}
345 @sa bt_trace_get_uuid(): Returns the UUID of a given trace class.
347 extern int bt_trace_set_uuid(struct bt_trace
*trace_class
,
348 const unsigned char *uuid
);
351 @brief Returns the number of entries contained in the environment of
352 the CTF IR trace class \p trace_class.
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.
360 @prenotnull{trace_class}
361 @postrefcountsame{trace_class}
363 extern int64_t bt_trace_get_environment_field_count(
364 struct bt_trace
*trace_class
);
367 @brief Returns the field name of the environment entry at index
368 \p index in the CTF IR trace class \p trace_class.
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
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.
380 @prenotnull{trace_class}
381 @pre \p index is lesser than the number of environment entries in
382 \p trace_class (see bt_trace_get_environment_field_count()).
383 @postrefcountsame{trace_class}
385 @sa bt_trace_get_environment_field_value_by_index(): Finds a trace class's
386 environment entry by index.
387 @sa bt_trace_get_environment_field_value_by_name(): Finds a trace
388 class's environment entry by name.
389 @sa bt_trace_set_environment_field(): Sets the value of a trace
390 class's environment entry.
393 bt_trace_get_environment_field_name_by_index(
394 struct bt_trace
*trace_class
, uint64_t index
);
396 extern struct bt_value
*
397 bt_trace_borrow_environment_field_value_by_index(struct bt_trace
*trace_class
,
401 @brief Returns the value of the environment entry at index
402 \p index in the CTF IR trace class \p trace_class.
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.
410 @prenotnull{trace_class}
411 @pre \p index is lesser than the number of environment entries in
412 \p trace_class (see bt_trace_get_environment_field_count()).
413 @postrefcountsame{trace_class}
414 @postsuccessrefcountretinc
416 @sa bt_trace_get_environment_field_value_by_name(): Finds a trace
417 class's environment entry by name.
418 @sa bt_trace_set_environment_field(): Sets the value of a trace
419 class's environment entry.
422 struct bt_value
*bt_trace_get_environment_field_value_by_index(
423 struct bt_trace
*trace_class
, uint64_t index
)
425 return bt_get(bt_trace_borrow_environment_field_value_by_index(
426 trace_class
, index
));
429 extern struct bt_value
*
430 bt_trace_borrow_environment_field_value_by_name(
431 struct bt_trace
*trace_class
, const char *name
);
434 @brief Returns the value of the environment entry named \p name
435 in the CTF IR trace class \p trace_class.
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
444 @prenotnull{trace_class}
446 @postrefcountsame{trace_class}
447 @postsuccessrefcountretinc
449 @sa bt_trace_get_environment_field_value_by_index(): Finds a trace class's
450 environment entry by index.
451 @sa bt_trace_set_environment_field(): Sets the value of a trace
452 class's environment entry.
456 bt_trace_get_environment_field_value_by_name(
457 struct bt_trace
*trace_class
, const char *name
)
460 bt_trace_borrow_environment_field_value_by_name(
465 @brief Sets the environment entry named \p name in the
466 CTF IR trace class \p trace_class to \p value.
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.
471 @param[in] trace_class Trace class of which to set the environment
473 @param[in] name Name of the environment entry to set (copied
475 @param[in] value Value of the environment entry named \p name.
476 @returns 0 on success, or a negative value on error.
478 @prenotnull{trace_class}
483 \link bt_value_integer_create() integer value object\endlink
485 \link bt_value_string_create() string value object\endlink.
486 @postrefcountsame{trace_class}
487 @postsuccessrefcountinc{value}
489 @sa bt_trace_get_environment_field_value_by_index(): Finds a trace class's
490 environment entry by index.
491 @sa bt_trace_get_environment_field_value_by_name(): Finds a trace
492 class's environment entry by name.
494 extern int bt_trace_set_environment_field(
495 struct bt_trace
*trace_class
, const char *name
,
496 struct bt_value
*value
);
499 @brief Sets the environment entry named \p name in the
500 CTF IR trace class \p trace_class to \p value.
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
507 @param[in] trace_class Trace class of which to set the environment
509 @param[in] name Name of the environment entry to set (copied
511 @param[in] value Value of the environment entry named \p name.
512 @returns 0 on success, or a negative value on error.
514 @prenotnull{trace_class}
517 @postrefcountsame{trace_class}
519 @sa bt_trace_set_environment_field(): Sets the value of a trace
520 class's environment entry.
522 extern int bt_trace_set_environment_field_integer(
523 struct bt_trace
*trace_class
, const char *name
,
527 @brief Sets the environment entry named \p name in the
528 CTF IR trace class \p trace_class to \p value.
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
535 @param[in] trace_class Trace class of which to set the environment
537 @param[in] name Name of the environment entry to set (copied
539 @param[in] value Value of the environment entry named \p name
541 @returns 0 on success, or a negative value on error.
543 @prenotnull{trace_class}
547 @postrefcountsame{trace_class}
549 @sa bt_trace_set_environment_field(): Sets the value of a trace
550 class's environment entry.
552 extern int bt_trace_set_environment_field_string(
553 struct bt_trace
*trace_class
, const char *name
,
559 @name Contained field types functions
563 extern struct bt_field_type
*bt_trace_borrow_packet_header_field_type(
564 struct bt_trace
*trace_class
);
567 @brief Returns the packet header field type of the CTF IR trace class
570 @param[in] trace_class Trace class of which to get the packet
572 @returns Packet header field type of \p trace_class,
573 or \c NULL if \p trace_class has no packet header field
576 @prenotnull{trace_class}
577 @postrefcountsame{trace_class}
578 @post <strong>On success, if the return value is a field type</strong>, its
579 reference count is incremented.
581 @sa bt_trace_set_packet_header_field_type(): Sets the packet
582 header field type of a given trace class.
585 struct bt_field_type
*bt_trace_get_packet_header_field_type(
586 struct bt_trace
*trace_class
)
588 return bt_get(bt_trace_borrow_packet_header_field_type(trace_class
));
592 @brief Sets the packet header field type of the CTF IR trace class
593 \p trace_class to \p packet_header_type, or unsets the current packet
594 header field type from \p trace_class.
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.
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.
603 @param[in] trace_class Trace class of which to set the packet
605 @param[in] packet_header_type Packet header field type, or \c NULL to unset
606 the current packet header field type.
607 @returns 0 on success, or a negative value on error.
609 @prenotnull{trace_class}
611 @pre <strong>\p packet_header_type, if not \c NULL</strong>, is a CTF IR
612 structure field type.
613 @postrefcountsame{trace_class}
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.
617 @sa bt_trace_get_packet_header_field_type(): Returns the packet
618 header field type of a given trace class.
620 extern int bt_trace_set_packet_header_field_type(struct bt_trace
*trace_class
,
621 struct bt_field_type
*packet_header_type
);
626 @name Contained clock classes functions
631 @brief Returns the number of CTF IR clock classes contained in the
632 CTF IR trace class \p trace_class.
634 @param[in] trace_class Trace class of which to get the number
635 of contained clock classes.
636 @returns Number of contained clock classes
637 contained in \p trace_class, or a negative
640 @prenotnull{trace_class}
641 @postrefcountsame{trace_class}
643 extern int64_t bt_trace_get_clock_class_count(
644 struct bt_trace
*trace_class
);
646 extern struct bt_clock_class
*bt_trace_borrow_clock_class_by_index(
647 struct bt_trace
*trace_class
, uint64_t index
);
650 @brief Returns the CTF IR clock class at index \p index in the CTF
651 IR trace class \p trace_class.
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
657 @returns Clock class at index \p index in \p trace_class,
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
663 bt_trace_get_clock_class_count()).
664 @postrefcountsame{trace_class}
665 @postsuccessrefcountretinc
667 @sa bt_trace_get_clock_class_by_name(): Finds a clock class by name
668 in a given trace class.
669 @sa bt_trace_add_clock_class(): Adds a clock class to a trace class.
672 struct bt_clock_class
*bt_trace_get_clock_class_by_index(
673 struct bt_trace
*trace_class
, uint64_t index
)
675 return bt_get(bt_trace_borrow_clock_class_by_index(
676 trace_class
, index
));
679 extern struct bt_clock_class
*bt_trace_borrow_clock_class_by_name(
680 struct bt_trace
*trace_class
, const char *name
);
683 @brief Returns the CTF IR clock class named \c name found in the CTF
684 IR trace class \p trace_class.
686 @param[in] trace_class Trace class of which to get the clock class
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,
692 @prenotnull{trace_class}
694 @postrefcountsame{trace_class}
695 @postsuccessrefcountretinc
697 @sa bt_trace_get_clock_class_by_index(): Returns the clock class contained
698 in a given trace class at a given index.
699 @sa bt_trace_add_clock_class(): Adds a clock class to a trace class.
702 struct bt_clock_class
*bt_trace_get_clock_class_by_name(
703 struct bt_trace
*trace_class
, const char *name
)
705 return bt_get(bt_trace_borrow_clock_class_by_name(trace_class
, name
));
709 @brief Adds the CTF IR clock class \p clock_class to the CTF IR
710 trace class \p trace_class.
712 On success, \p trace_class contains \p clock_class.
714 You can call this function even if \p trace_class or \p clock_class
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.
721 @prenotnull{trace_class}
722 @prenotnull{clock_class}
723 @postrefcountsame{trace_class}
724 @postsuccessrefcountinc{clock_class}
725 @post <strong>On success, if \p trace_class is frozen</strong>,
726 \p clock_class is frozen.
728 @sa bt_trace_get_clock_class_by_index(): Returns the clock class contained
729 in a given trace class at a given index.
730 @sa bt_trace_get_clock_class_by_name(): Finds a clock class by name
731 in a given trace class.
733 extern int bt_trace_add_clock_class(struct bt_trace
*trace_class
,
734 struct bt_clock_class
*clock_class
);
739 @name Stream class children functions
744 @brief Returns the number of stream classes contained in the
745 CTF IR trace class \p trace_class.
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
753 @prenotnull{trace_class}
754 @postrefcountsame{trace_class}
756 extern int64_t bt_trace_get_stream_class_count(
757 struct bt_trace
*trace_class
);
759 extern struct bt_stream_class
*bt_trace_borrow_stream_class_by_index(
760 struct bt_trace
*trace_class
, uint64_t index
);
763 @brief Returns the stream class at index \p index in the CTF IR trace
764 class \p trace_class.
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
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
774 bt_trace_get_stream_class_count()).
775 @postrefcountsame{trace_class}
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.
781 struct bt_stream_class
*bt_trace_get_stream_class_by_index(
782 struct bt_trace
*trace_class
, uint64_t index
)
784 return bt_get(bt_trace_borrow_stream_class_by_index(
785 trace_class
, index
));
788 extern struct bt_stream_class
*bt_trace_borrow_stream_class_by_id(
789 struct bt_trace
*trace_class
, uint64_t id
);
792 @brief Returns the stream class with ID \c id found in the CTF IR
793 trace class \p trace_class.
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
800 @prenotnull{trace_class}
801 @postrefcountsame{trace_class}
802 @postsuccessrefcountretinc
804 @sa bt_trace_get_stream_class_by_index(): Returns the stream class contained
805 in a given trace class at a given index.
806 @sa bt_trace_add_stream_class(): Adds a stream class to a trace class.
809 struct bt_stream_class
*bt_trace_get_stream_class_by_id(
810 struct bt_trace
*trace_class
, uint64_t id
)
812 return bt_get(bt_trace_borrow_stream_class_by_id(trace_class
, id
));
816 @brief Adds the CTF IR stream class \p stream_class to the
817 CTF IR trace class \p trace_class.
819 On success, \p stream_class becomes the child of \p trace_class.
821 You can only add a given stream class to one trace class.
823 You can call this function even if \p trace_class is frozen.
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.
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.
836 @prenotnull{trace_class}
837 @prenotnull{stream_class}
838 @postrefcountsame{trace_class}
839 @postsuccessrefcountinc{stream_class}
840 @postsuccessfrozen{stream_class}
842 @sa bt_trace_get_stream_class_by_index(): Returns the stream class contained
843 in a given trace class at a given index.
844 @sa bt_trace_get_stream_class_by_id(): Finds a stream class by ID.
846 extern int bt_trace_add_stream_class(struct bt_trace
*trace_class
,
847 struct bt_stream_class
*stream_class
);
852 @name Stream children functions
857 @brief Returns the number of streams contained in the CTF IR trace
858 class \p trace_class.
860 @param[in] trace_class Trace class of which to get the number
862 @returns Number of children streams
863 contained in \p trace_class, or a negative
866 @prenotnull{trace_class}
867 @postrefcountsame{trace_class}
869 extern int64_t bt_trace_get_stream_count(struct bt_trace
*trace_class
);
871 extern struct bt_stream
*bt_trace_borrow_stream_by_index(
872 struct bt_trace
*trace_class
, uint64_t index
);
875 @brief Returns the stream at index \p index in the CTF IR trace
876 class \p trace_class.
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
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
886 bt_trace_get_stream_count()).
887 @postrefcountsame{trace_class}
890 struct bt_stream
*bt_trace_get_stream_by_index(
891 struct bt_trace
*trace_class
, uint64_t index
)
893 return bt_get(bt_trace_borrow_stream_by_index(trace_class
, index
));
899 @name Misc. functions
904 @brief Returns whether or not the CTF IR trace class \p trace_class
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
911 This function returns #BT_TRUE if bt_trace_set_is_static() was
912 previously called on it.
914 @param[in] trace_class Trace class to check.
915 @returns #BT_TRUE if \p trace_class is static,
917 @sa bt_trace_set_is_static(): Makes a trace class static.
919 extern bt_bool
bt_trace_is_static(struct bt_trace
*trace_class
);
922 @brief Makes the CTF IR trace class \p trace_class static.
924 A static trace class is frozen and you cannot call any modifying
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()
934 You cannot create a stream with bt_stream_create() with any of the
935 stream classes of a static trace class.
937 @param[in] trace_class Trace class to make static.
938 @returns 0 on success, or a negative value on error.
940 @prenotnull{trace_class}
941 @postrefcountsame{trace_class}
942 @postsuccessfrozen{trace_class}
944 @sa bt_trace_is_static(): Checks whether or not a given trace class
946 @sa bt_trace_add_is_static_listener(): Adds a listener to a trace
947 class which is called when the trace class is made static.
949 extern int bt_trace_set_is_static(struct bt_trace
*trace_class
);
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.
955 \p listener is called with \p data, the user data, the first time
956 bt_trace_set_is_static() is called on \p trace_class.
958 When the trace is destroyed, or when you remove the added listener with
959 bt_trace_remove_is_static_listener(), \p listener_removed is called
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
963 \p listener_removed, including bt_trace_remove_is_static_listener().
965 This function fails if \p trace_class is already static: you need to
966 check the condition first with bt_trace_is_static().
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
971 bt_trace_remove_is_static_listener().
973 @param[in] trace_class Trace class to which to add the
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
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.
986 @prenotnull{trace_class}
987 @prenotnull{listener}
988 @pre \p trace_class is not static.
989 @postrefcountsame{trace_class}
991 @sa bt_trace_remove_is_static_listener(): Removes a "trace is
992 static" listener from a trace class previously added with this
994 @sa bt_trace_is_static(): Checks whether or not a given trace class
996 @sa bt_trace_set_is_static(): Makes a trace class static.
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
);
1004 @brief Removes the "trace is static" listener identified by
1005 \p listener_id from the trace class \p trace_class.
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
1011 @returns 0 if this function removed the listener, or
1012 a negative value on error.
1014 @prenotnull{trace_class}
1015 @pre \p listener_id is the identifier of a listener that you previously
1016 added with bt_trace_add_is_static_listener() and did not
1017 already remove with this function.
1018 @postrefcountsame{trace_class}
1020 @sa bt_trace_add_is_static_listener(): Adds a listener to a trace
1021 class which is called when the trace class is made static.
1023 extern int bt_trace_remove_is_static_listener(
1024 struct bt_trace
*trace_class
, int listener_id
);
1027 @brief Accepts the visitor \p visitor to visit the hierarchy of the
1028 CTF IR trace class \p trace_class.
1030 This function traverses the hierarchy of \p trace_class in pre-order
1031 and calls \p visitor on each element.
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.
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.
1041 @prenotnull{trace_class}
1042 @prenotnull{visitor}
1044 extern int bt_trace_visit(struct bt_trace
*trace_class
,
1045 bt_visitor visitor
, void *data
);
1055 #endif /* BABELTRACE_CTF_IR_TRACE_H */