2 * SPDX-License-Identifier: MIT
4 * Copyright (C) 2010-2019 EfficiOS Inc. and Linux Foundation
7 #ifndef BABELTRACE2_TRACE_IR_TRACE_H
8 #define BABELTRACE2_TRACE_IR_TRACE_H
10 /* IWYU pragma: private, include <babeltrace2/babeltrace.h> */
12 #ifndef __BT_IN_BABELTRACE_H
13 # error "Please include <babeltrace2/babeltrace.h> instead."
18 #include <babeltrace2/types.h>
25 @defgroup api-tir-trace Trace
29 Trace (set of \bt_p_stream).
31 A <strong><em>trace</em></strong> is a set of \bt_p_stream with
34 @image html trace-structure.png
36 In the illustration above, notice that a trace is an instance of a
37 \bt_trace_cls and that it contains streams.
39 Borrow the class of a trace with bt_trace_borrow_class() and
40 bt_trace_borrow_class_const().
42 A trace is a \ref api-tir "trace IR" data object.
44 A trace is a \ref api-fund-shared-object "shared object": get a
45 new reference with bt_trace_get_ref() and put an existing
46 reference with bt_trace_put_ref().
48 Some library functions \ref api-fund-freezing "freeze" traces on
49 success. The documentation of those functions indicate this
50 postcondition. With a frozen trace, you can still:
52 - Create \bt_p_stream from it with bt_stream_create() or
53 bt_stream_create_with_id().
54 - Add a destruction listener to it with
55 bt_trace_add_destruction_listener().
57 The type of a trace is #bt_trace.
59 A trace contains \bt_p_stream. All the streams of a
60 given trace have unique \ref api-tir-stream-prop-id "numeric IDs".
61 Get the number of streams in a trace with bt_trace_get_stream_count().
62 Borrow a specific stream from a trace with
63 bt_trace_borrow_stream_by_index(),
64 bt_trace_borrow_stream_by_index_const(), bt_trace_borrow_stream_by_id(),
65 or bt_trace_borrow_stream_by_id_const().
67 Create a default trace from a \bt_trace_cls with bt_trace_create().
69 Add to and remove a destruction listener from a trace with
70 bt_trace_add_destruction_listener() and
71 bt_trace_remove_destruction_listener().
75 A trace has the following properties:
79 \anchor api-tir-trace-prop-name
85 Use bt_trace_set_name() and bt_trace_get_name().
89 \anchor api-tir-trace-prop-uuid
93 <a href="https://en.wikipedia.org/wiki/Universally_unique_identifier">UUID</a>
96 The trace's UUID uniquely identifies the trace.
98 Use bt_trace_set_uuid() and bt_trace_get_uuid().
102 \anchor api-tir-trace-prop-env
103 \bt_dt_opt Environment
106 Generic key-value store which describes the environment of the trace
107 (for example, the system's hostname, its network address, the
108 tracer's name and version, and the rest).
110 Trace environment keys are strings while values are signed integers
113 Set a trace environment entry's value with
114 bt_trace_set_environment_entry_integer() and
115 bt_trace_set_environment_entry_string().
117 Get the number of environment entries in a trace with
118 bt_trace_get_environment_entry_count().
120 Borrow an environment entry from a trace with
121 bt_trace_borrow_environment_entry_value_by_name_const().
125 \anchor api-tir-trace-prop-user-attrs
126 \bt_dt_opt User attributes
129 User attributes of the trace.
131 User attributes are custom attributes attached to a trace.
133 Use bt_trace_set_user_attributes(),
134 bt_trace_borrow_user_attributes(), and
135 bt_trace_borrow_user_attributes_const().
146 @typedef struct bt_trace bt_trace;
161 Creates a default trace from the \bt_trace_cls \bt_p{trace_class}.
163 This function instantiates \bt_p{trace_class}.
165 On success, the returned trace has the following property values:
172 <td>\ref api-tir-trace-prop-name "Name"
175 <td>\ref api-tir-trace-prop-uuid "UUID"
178 <td>\ref api-tir-trace-prop-env "Environment"
181 <td>\ref api-tir-trace-prop-user-attrs "User attributes"
182 <td>Empty \bt_map_val
185 @param[in] trace_class
186 Trace class from which to create the default trace.
189 New trace reference, or \c NULL on memory error.
191 extern bt_trace
*bt_trace_create(bt_trace_class
*trace_class
);
202 Borrows the \ref api-tir-trace-cls "class" of the trace
206 Trace of which to borrow the class.
209 \em Borrowed reference of the class of \bt_p{trace}.
211 @bt_pre_not_null{trace}
213 @sa bt_trace_borrow_class_const() —
214 \c const version of this function.
216 extern bt_trace_class
*bt_trace_borrow_class(bt_trace
*trace
);
220 Borrows the \ref api-tir-trace-cls "class" of the trace
221 \bt_p{trace} (\c const version).
223 See bt_trace_borrow_class().
225 extern const bt_trace_class
*bt_trace_borrow_class_const(
226 const bt_trace
*trace
);
237 Returns the number of \bt_p_stream contained in the trace
241 Trace of which to get the number of contained streams.
244 Number of contained streams in \bt_p{trace}.
246 @bt_pre_not_null{trace}
248 extern uint64_t bt_trace_get_stream_count(const bt_trace
*trace
);
252 Borrows the \bt_stream at index \bt_p{index} from the
256 Trace from which to borrow the stream at index
259 Index of the stream to borrow from \bt_p{trace}.
263 \em Borrowed reference of the stream of
264 \bt_p{trace} at index \bt_p{index}.
266 The returned pointer remains valid as long as \bt_p{trace}
270 @bt_pre_not_null{trace}
272 \bt_p{index} is less than the number of streams in
273 \bt_p{trace} (as returned by
274 bt_trace_get_stream_count()).
276 @sa bt_trace_get_stream_count() —
277 Returns the number of streams contained in a trace.
278 @sa bt_trace_borrow_stream_by_index_const() —
279 \c const version of this function.
281 extern bt_stream
*bt_trace_borrow_stream_by_index(bt_trace
*trace
,
286 Borrows the \bt_stream at index \bt_p{index} from the
287 trace \bt_p{trace} (\c const version).
289 See bt_trace_borrow_stream_by_index().
291 extern const bt_stream
*bt_trace_borrow_stream_by_index_const(
292 const bt_trace
*trace
, uint64_t index
);
296 Borrows the \bt_stream having the numeric ID \bt_p{id} from the
299 If there's no stream having the numeric ID \bt_p{id} in
300 \bt_p{trace}, this function returns \c NULL.
303 Trace from which to borrow the stream having the
304 numeric ID \bt_p{id}.
306 ID of the stream to borrow from \bt_p{trace}.
310 \em Borrowed reference of the stream of
311 \bt_p{trace} having the numeric ID \bt_p{id}, or \c NULL
314 The returned pointer remains valid as long as \bt_p{trace}
318 @bt_pre_not_null{trace}
320 @sa bt_trace_borrow_stream_by_id_const() —
321 \c const version of this function.
323 extern bt_stream
*bt_trace_borrow_stream_by_id(bt_trace
*trace
,
328 Borrows the \bt_stream having the numeric ID \bt_p{id} from the
329 trace \bt_p{trace} (\c const version).
331 See bt_trace_borrow_stream_by_id().
333 extern const bt_stream
*bt_trace_borrow_stream_by_id_const(
334 const bt_trace
*trace
, uint64_t id
);
345 Status codes for bt_trace_set_name().
347 typedef enum bt_trace_set_name_status
{
352 BT_TRACE_SET_NAME_STATUS_OK
= __BT_FUNC_STATUS_OK
,
358 BT_TRACE_SET_NAME_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
359 } bt_trace_set_name_status
;
363 Sets the name of the trace \bt_p{trace} to a copy of \bt_p{name}.
365 See the \ref api-tir-trace-prop-name "name" property.
368 Trace of which to set the name to \bt_p{name}.
370 New name of \bt_p{trace} (copied).
372 @retval #BT_TRACE_SET_NAME_STATUS_OK
374 @retval #BT_TRACE_SET_NAME_STATUS_MEMORY_ERROR
377 @bt_pre_not_null{trace}
379 @bt_pre_not_null{name}
381 @sa bt_trace_get_name() —
382 Returns the name of a trace.
384 extern bt_trace_set_name_status
bt_trace_set_name(bt_trace
*trace
,
389 Returns the name of the trace \bt_p{trace}.
391 See the \ref api-tir-trace-prop-name "name" property.
393 If \bt_p{trace} has no name, this function returns \c NULL.
396 Trace of which to get the name.
400 Name of \bt_p{trace}, or \c NULL if none.
402 The returned pointer remains valid as long as \bt_p{trace}
406 @bt_pre_not_null{trace}
408 @sa bt_trace_set_name() —
409 Sets the name of a trace.
411 extern const char *bt_trace_get_name(const bt_trace
*trace
);
416 <a href="https://en.wikipedia.org/wiki/Universally_unique_identifier">UUID</a>
417 of the trace \bt_p{trace} to a copy of \bt_p{uuid}.
419 See the \ref api-tir-trace-prop-uuid "UUID" property.
422 Trace of which to set the UUID to \bt_p{uuid}.
424 New UUID of \bt_p{trace} (copied).
426 @bt_pre_not_null{trace}
428 @bt_pre_not_null{uuid}
430 @sa bt_trace_get_uuid() —
431 Returns the UUID of a trace.
433 extern void bt_trace_set_uuid(bt_trace
*trace
, bt_uuid uuid
);
437 Returns the UUID of the trace \bt_p{trace}.
439 See the \ref api-tir-trace-prop-uuid "UUID" property.
441 If \bt_p{trace} has no UUID, this function returns \c NULL.
444 Trace of which to get the UUID.
448 UUID of \bt_p{trace}, or \c NULL if none.
450 The returned pointer remains valid as long as \bt_p{trace}
454 @bt_pre_not_null{trace}
456 @sa bt_trace_set_uuid() —
457 Sets the UUID of a trace.
459 extern bt_uuid
bt_trace_get_uuid(const bt_trace
*trace
);
463 Status codes for bt_trace_set_name().
465 typedef enum bt_trace_set_environment_entry_status
{
470 BT_TRACE_SET_ENVIRONMENT_ENTRY_STATUS_OK
= __BT_FUNC_STATUS_OK
,
476 BT_TRACE_SET_ENVIRONMENT_ENTRY_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
477 } bt_trace_set_environment_entry_status
;
481 Sets the value of the environment entry of the trace \bt_p{trace}
482 named \bt_p{name} to the signed integer \bt_p{value}.
484 See the \ref api-tir-trace-prop-env "environment" property.
486 On success, if \bt_p{trace} already contains an environment entry named
487 \bt_p{name}, this function replaces the existing entry's value with
491 Trace in which to insert or replace an environment entry named
492 \bt_p{name} with the value \bt_p{value}.
494 Name of the entry to insert or replace in \bt_p{trace} (copied).
496 Value of the environment entry to insert or replace in \bt_p{trace}.
498 @retval #BT_TRACE_SET_ENVIRONMENT_ENTRY_STATUS_OK
500 @retval #BT_TRACE_SET_ENVIRONMENT_ENTRY_STATUS_MEMORY_ERROR
503 @bt_pre_not_null{trace}
505 @bt_pre_not_null{name}
507 @sa bt_trace_set_environment_entry_string() —
508 Sets a trace environment entry's value to a string.
510 extern bt_trace_set_environment_entry_status
511 bt_trace_set_environment_entry_integer(bt_trace
*trace
, const char *name
,
516 Sets the value of the environment entry of the trace \bt_p{trace}
517 named \bt_p{name} to the string \bt_p{value}.
519 See the \ref api-tir-trace-prop-env "environment" property.
521 On success, if \bt_p{trace} already contains an environment entry named
522 \bt_p{name}, this function replaces the existing entry's value with
526 Trace in which to insert or replace an environment entry named
527 \bt_p{name} with the value \bt_p{value}.
529 Name of the entry to insert or replace in \bt_p{trace} (copied).
531 Value of the environment entry to insert or replace in \bt_p{trace}.
533 @retval #BT_TRACE_SET_ENVIRONMENT_ENTRY_STATUS_OK
535 @retval #BT_TRACE_SET_ENVIRONMENT_ENTRY_STATUS_MEMORY_ERROR
538 @bt_pre_not_null{trace}
540 @bt_pre_not_null{name}
541 @bt_pre_not_null{value}
543 @sa bt_trace_set_environment_entry_integer() —
544 Sets a trace environment entry's value to a signed integer.
546 extern bt_trace_set_environment_entry_status
547 bt_trace_set_environment_entry_string(bt_trace
*trace
, const char *name
,
552 Returns the number of environment entries contained in the trace
555 See the \ref api-tir-trace-prop-env "environment" property.
558 Trace of which to get the number of environment entries.
561 Number of environment entries in \bt_p{trace}.
563 @bt_pre_not_null{trace}
565 extern uint64_t bt_trace_get_environment_entry_count(const bt_trace
*trace
);
569 Borrows the environment entry at index \bt_p{index} from the
570 trace \bt_p{trace}, setting \bt_p{*name} to its name and
571 \bt_p{*value} to its value.
573 See the \ref api-tir-trace-prop-env "environment" property.
576 Trace from which to borrow the environment entry at index
579 Index of the environment entry to borrow from \bt_p{trace}.
582 <strong>On success</strong>, \bt_p{*name} is the name of the
583 environment entry at index \bt_p{index} in \bt_p{trace}.
585 The returned pointer remains valid as long as \bt_p{trace}
590 <strong>On success</strong>, \bt_p{*value} is a \em borrowed
591 reference of the environment entry at index \bt_p{index} in
594 \bt_p{*value} is either a \bt_sint_val
595 (#BT_VALUE_TYPE_SIGNED_INTEGER) or a \bt_string_val
596 (#BT_VALUE_TYPE_STRING).
598 The returned pointer remains valid as long as \bt_p{trace}
602 @bt_pre_not_null{trace}
604 \bt_p{index} is less than the number of environment entries in
605 \bt_p{trace} (as returned by
606 bt_trace_get_environment_entry_count()).
607 @bt_pre_not_null{name}
608 @bt_pre_not_null{value}
610 @sa bt_trace_get_environment_entry_count() —
611 Returns the number of environment entries contained in a trace.
613 extern void bt_trace_borrow_environment_entry_by_index_const(
614 const bt_trace
*trace
, uint64_t index
,
615 const char **name
, const bt_value
**value
);
619 Borrows the value of the environment entry named \bt_p{name}
620 in the trace \bt_p{trace}.
622 See the \ref api-tir-trace-prop-env "environment" property.
624 If there's no environment entry named \bt_p{name} in \bt_p{trace}, this
625 function returns \c NULL.
628 Trace from which to borrow the value of the environment entry
631 Name of the environment entry to borrow from \bt_p{trace}.
635 \em Borrowed reference of the value of the environment entry named
636 \bt_p{name} in \bt_p{trace}.
638 The returned value is either a \bt_sint_val
639 (#BT_VALUE_TYPE_SIGNED_INTEGER) or a \bt_string_val
640 (#BT_VALUE_TYPE_STRING).
642 The returned pointer remains valid as long as \bt_p{trace}
646 @bt_pre_not_null{trace}
647 @bt_pre_not_null{name}
649 extern const bt_value
*bt_trace_borrow_environment_entry_value_by_name_const(
650 const bt_trace
*trace
, const char *name
);
654 Sets the user attributes of the trace \bt_p{trace} to
655 \bt_p{user_attributes}.
657 See the \ref api-tir-trace-prop-user-attrs "user attributes"
661 When you create a default trace with bt_trace_create(), the trace's
662 initial user attributes is an empty \bt_map_val. Therefore you can
663 borrow it with bt_trace_borrow_user_attributes() and fill it
664 directly instead of setting a new one with this function.
667 Trace of which to set the user attributes to \bt_p{user_attributes}.
668 @param[in] user_attributes
669 New user attributes of \bt_p{trace}.
671 @bt_pre_not_null{trace}
673 @bt_pre_not_null{user_attributes}
674 @bt_pre_is_map_val{user_attributes}
676 @sa bt_trace_borrow_user_attributes() —
677 Borrows the user attributes of a trace.
679 extern void bt_trace_set_user_attributes(
680 bt_trace
*trace
, const bt_value
*user_attributes
);
684 Borrows the user attributes of the trace \bt_p{trace}.
686 See the \ref api-tir-trace-prop-user-attrs "user attributes"
690 When you create a default trace with bt_trace_create(), the trace's
691 initial user attributes is an empty \bt_map_val.
694 Trace from which to borrow the user attributes.
697 User attributes of \bt_p{trace} (a \bt_map_val).
699 @bt_pre_not_null{trace}
701 @sa bt_trace_set_user_attributes() —
702 Sets the user attributes of a trace.
703 @sa bt_trace_borrow_user_attributes_const() —
704 \c const version of this function.
706 extern bt_value
*bt_trace_borrow_user_attributes(bt_trace
*trace
);
710 Borrows the user attributes of the trace \bt_p{trace}
713 See bt_trace_borrow_user_attributes().
715 extern const bt_value
*bt_trace_borrow_user_attributes_const(
716 const bt_trace
*trace
);
727 User function for bt_trace_add_destruction_listener().
729 This is the user function type for a trace destruction listener.
732 Trace being destroyed (\ref api-fund-freezing "frozen").
734 User data, as passed as the \bt_p{user_data} parameter of
735 bt_trace_add_destruction_listener().
737 @bt_pre_not_null{trace}
740 The reference count of \bt_p{trace} is not changed.
743 @sa bt_trace_add_destruction_listener() —
744 Adds a destruction listener to a trace.
746 typedef void (* bt_trace_destruction_listener_func
)(
747 const bt_trace
*trace
, void *user_data
);
751 Status codes for bt_trace_add_destruction_listener().
753 typedef enum bt_trace_add_listener_status
{
758 BT_TRACE_ADD_LISTENER_STATUS_OK
= __BT_FUNC_STATUS_OK
,
764 BT_TRACE_ADD_LISTENER_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
765 } bt_trace_add_listener_status
;
769 Adds a destruction listener having the function \bt_p{user_func}
770 to the trace \bt_p{trace}.
772 All the destruction listener user functions of a trace are called
773 when it's being destroyed.
775 If \bt_p{listener_id} is not \c NULL, then this function, on success,
776 sets \bt_p{*listener_id} to the ID of the added destruction listener
777 within \bt_p{trace}. You can then use this ID to remove the
778 added destruction listener with bt_trace_remove_destruction_listener().
781 Trace to add the destruction listener to.
783 User function of the destruction listener to add to
786 User data to pass as the \bt_p{user_data} parameter of
788 @param[out] listener_id
789 <strong>On success and if not \c NULL</strong>, \bt_p{*listener_id}
790 is the ID of the added destruction listener within
793 @retval #BT_TRACE_ADD_LISTENER_STATUS_OK
795 @retval #BT_TRACE_ADD_LISTENER_STATUS_MEMORY_ERROR
798 @bt_pre_not_null{trace}
799 @bt_pre_not_null{user_func}
801 @sa bt_trace_remove_destruction_listener() —
802 Removes a destruction listener from a trace.
804 extern bt_trace_add_listener_status
bt_trace_add_destruction_listener(
805 const bt_trace
*trace
,
806 bt_trace_destruction_listener_func user_func
,
807 void *user_data
, bt_listener_id
*listener_id
);
811 Status codes for bt_trace_remove_destruction_listener().
813 typedef enum bt_trace_remove_listener_status
{
818 BT_TRACE_REMOVE_LISTENER_STATUS_OK
= __BT_FUNC_STATUS_OK
,
824 BT_TRACE_REMOVE_LISTENER_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
825 } bt_trace_remove_listener_status
;
829 Removes the destruction listener having the ID \bt_p{listener_id}
830 from the trace \bt_p{trace}.
832 The destruction listener to remove from \bt_p{trace} was
833 previously added with bt_trace_add_destruction_listener().
835 You can call this function when \bt_p{trace} is
836 \ref api-fund-freezing "frozen".
839 Trace from which to remove the destruction listener having
840 the ID \bt_p{listener_id}.
841 @param[in] listener_id
842 ID of the destruction listener to remove from \bt_p{trace}.
844 @retval #BT_TRACE_REMOVE_LISTENER_STATUS_OK
846 @retval #BT_TRACE_REMOVE_LISTENER_STATUS_MEMORY_ERROR
849 @bt_pre_not_null{trace}
851 \bt_p{listener_id} is the ID of an existing destruction listener
854 @sa bt_trace_add_destruction_listener() —
855 Adds a destruction listener to a trace.
857 extern bt_trace_remove_listener_status
bt_trace_remove_destruction_listener(
858 const bt_trace
*trace
, bt_listener_id listener_id
);
863 @name Reference count
869 Increments the \ref api-fund-shared-object "reference count" of
870 the trace \bt_p{trace}.
874 Trace of which to increment the reference count.
879 @sa bt_trace_put_ref() —
880 Decrements the reference count of a trace.
882 extern void bt_trace_get_ref(const bt_trace
*trace
);
886 Decrements the \ref api-fund-shared-object "reference count" of
887 the trace \bt_p{trace}.
891 Trace of which to decrement the reference count.
896 @sa bt_trace_get_ref() —
897 Increments the reference count of a trace.
899 extern void bt_trace_put_ref(const bt_trace
*trace
);
903 Decrements the reference count of the trace
904 \bt_p{_trace}, and then sets \bt_p{_trace} to \c NULL.
908 Trace of which to decrement the reference count.
913 @bt_pre_assign_expr{_trace}
915 #define BT_TRACE_PUT_REF_AND_RESET(_trace) \
917 bt_trace_put_ref(_trace); \
923 Decrements the reference count of the trace \bt_p{_dst}, sets
924 \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL.
926 This macro effectively moves a trace reference from the expression
927 \bt_p{_src} to the expression \bt_p{_dst}, putting the existing
928 \bt_p{_dst} reference.
932 Destination expression.
943 @bt_pre_assign_expr{_dst}
944 @bt_pre_assign_expr{_src}
946 #define BT_TRACE_MOVE_REF(_dst, _src) \
948 bt_trace_put_ref(_dst); \
961 #endif /* BABELTRACE2_TRACE_IR_TRACE_H */