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 #ifndef __BT_IN_BABELTRACE_H
11 # error "Please include <babeltrace2/babeltrace.h> instead."
16 #include <babeltrace2/types.h>
23 @defgroup api-tir-trace Trace
27 Trace (set of \bt_p_stream).
29 A <strong><em>trace</em></strong> is a set of \bt_p_stream with
32 @image html trace-structure.png
34 In the illustration above, notice that a trace is an instance of a
35 \bt_trace_cls and that it contains streams.
37 Borrow the class of a trace with bt_trace_borrow_class() and
38 bt_trace_borrow_class_const().
40 A trace is a \ref api-tir "trace IR" data object.
42 A trace is a \ref api-fund-shared-object "shared object": get a
43 new reference with bt_trace_get_ref() and put an existing
44 reference with bt_trace_put_ref().
46 Some library functions \ref api-fund-freezing "freeze" traces on
47 success. The documentation of those functions indicate this
48 postcondition. With a frozen trace, you can still:
50 - Create \bt_p_stream from it with bt_stream_create() or
51 bt_stream_create_with_id().
52 - Add a destruction listener to it with
53 bt_trace_add_destruction_listener().
55 The type of a trace is #bt_trace.
57 A trace contains \bt_p_stream. All the streams of a
58 given trace have unique \ref api-tir-stream-prop-id "numeric IDs".
59 Get the number of streams in a trace with bt_trace_get_stream_count().
60 Borrow a specific stream from a trace with
61 bt_trace_borrow_stream_by_index(),
62 bt_trace_borrow_stream_by_index_const(), bt_trace_borrow_stream_by_id(),
63 or bt_trace_borrow_stream_by_id_const().
65 Create a default trace from a \bt_trace_cls with bt_trace_create().
67 Add to and remove a destruction listener from a trace with
68 bt_trace_add_destruction_listener() and
69 bt_trace_remove_destruction_listener().
73 A trace has the following properties:
77 \anchor api-tir-trace-prop-name
83 Use bt_trace_set_name() and bt_trace_get_name().
87 \anchor api-tir-trace-prop-uuid
91 <a href="https://en.wikipedia.org/wiki/Universally_unique_identifier">UUID</a>
94 The trace's UUID uniquely identifies the trace.
96 Use bt_trace_set_uuid() and bt_trace_get_uuid().
100 \anchor api-tir-trace-prop-env
101 \bt_dt_opt Environment
104 Generic key-value store which describes the environment of the trace
105 (for example, the system's hostname, its network address, the
106 tracer's name and version, and the rest).
108 Trace environment keys are strings while values are signed integers
111 Set a trace environment entry's value with
112 bt_trace_set_environment_entry_integer() and
113 bt_trace_set_environment_entry_string().
115 Get the number of environment entries in a trace with
116 bt_trace_get_environment_entry_count().
118 Borrow an environment entry from a trace with
119 bt_trace_borrow_environment_entry_value_by_name_const().
123 \anchor api-tir-trace-prop-user-attrs
124 \bt_dt_opt User attributes
127 User attributes of the trace.
129 User attributes are custom attributes attached to a trace.
131 Use bt_trace_set_user_attributes(),
132 bt_trace_borrow_user_attributes(), and
133 bt_trace_borrow_user_attributes_const().
144 @typedef struct bt_trace bt_trace;
159 Creates a default trace from the \bt_trace_cls \bt_p{trace_class}.
161 This function instantiates \bt_p{trace_class}.
163 On success, the returned trace has the following property values:
170 <td>\ref api-tir-trace-prop-name "Name"
173 <td>\ref api-tir-trace-prop-uuid "UUID"
176 <td>\ref api-tir-trace-prop-env "Environment"
179 <td>\ref api-tir-trace-prop-user-attrs "User attributes"
180 <td>Empty \bt_map_val
183 @param[in] trace_class
184 Trace class from which to create the default trace.
187 New trace reference, or \c NULL on memory error.
189 extern bt_trace
*bt_trace_create(bt_trace_class
*trace_class
);
200 Borrows the \ref api-tir-trace-cls "class" of the trace
204 Trace of which to borrow the class.
207 \em Borrowed reference of the class of \bt_p{trace}.
209 @bt_pre_not_null{trace}
211 @sa bt_trace_borrow_class_const() —
212 \c const version of this function.
214 extern bt_trace_class
*bt_trace_borrow_class(bt_trace
*trace
);
218 Borrows the \ref api-tir-trace-cls "class" of the trace
219 \bt_p{trace} (\c const version).
221 See bt_trace_borrow_class().
223 extern const bt_trace_class
*bt_trace_borrow_class_const(
224 const bt_trace
*trace
);
235 Returns the number of \bt_p_stream contained in the trace
239 Trace of which to get the number of contained streams.
242 Number of contained streams in \bt_p{trace}.
244 @bt_pre_not_null{trace}
246 extern uint64_t bt_trace_get_stream_count(const bt_trace
*trace
);
250 Borrows the \bt_stream at index \bt_p{index} from the
254 Trace from which to borrow the stream at index
257 Index of the stream to borrow from \bt_p{trace}.
261 \em Borrowed reference of the stream of
262 \bt_p{trace} at index \bt_p{index}.
264 The returned pointer remains valid as long as \bt_p{trace}
268 @bt_pre_not_null{trace}
270 \bt_p{index} is less than the number of streams in
271 \bt_p{trace} (as returned by
272 bt_trace_get_stream_count()).
274 @sa bt_trace_get_stream_count() —
275 Returns the number of streams contained in a trace.
276 @sa bt_trace_borrow_stream_by_index_const() —
277 \c const version of this function.
279 extern bt_stream
*bt_trace_borrow_stream_by_index(bt_trace
*trace
,
284 Borrows the \bt_stream at index \bt_p{index} from the
285 trace \bt_p{trace} (\c const version).
287 See bt_trace_borrow_stream_by_index().
289 extern const bt_stream
*bt_trace_borrow_stream_by_index_const(
290 const bt_trace
*trace
, uint64_t index
);
294 Borrows the \bt_stream having the numeric ID \bt_p{id} from the
297 If there's no stream having the numeric ID \bt_p{id} in
298 \bt_p{trace}, this function returns \c NULL.
301 Trace from which to borrow the stream having the
302 numeric ID \bt_p{id}.
304 ID of the stream to borrow from \bt_p{trace}.
308 \em Borrowed reference of the stream of
309 \bt_p{trace} having the numeric ID \bt_p{id}, or \c NULL
312 The returned pointer remains valid as long as \bt_p{trace}
316 @bt_pre_not_null{trace}
318 @sa bt_trace_borrow_stream_by_id_const() —
319 \c const version of this function.
321 extern bt_stream
*bt_trace_borrow_stream_by_id(bt_trace
*trace
,
326 Borrows the \bt_stream having the numeric ID \bt_p{id} from the
327 trace \bt_p{trace} (\c const version).
329 See bt_trace_borrow_stream_by_id().
331 extern const bt_stream
*bt_trace_borrow_stream_by_id_const(
332 const bt_trace
*trace
, uint64_t id
);
343 Status codes for bt_trace_set_name().
345 typedef enum bt_trace_set_name_status
{
350 BT_TRACE_SET_NAME_STATUS_OK
= __BT_FUNC_STATUS_OK
,
356 BT_TRACE_SET_NAME_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
357 } bt_trace_set_name_status
;
361 Sets the name of the trace \bt_p{trace} to a copy of \bt_p{name}.
363 See the \ref api-tir-trace-prop-name "name" property.
366 Trace of which to set the name to \bt_p{name}.
368 New name of \bt_p{trace} (copied).
370 @retval #BT_TRACE_SET_NAME_STATUS_OK
372 @retval #BT_TRACE_SET_NAME_STATUS_MEMORY_ERROR
375 @bt_pre_not_null{trace}
377 @bt_pre_not_null{name}
379 @sa bt_trace_get_name() —
380 Returns the name of a trace.
382 extern bt_trace_set_name_status
bt_trace_set_name(bt_trace
*trace
,
387 Returns the name of the trace \bt_p{trace}.
389 See the \ref api-tir-trace-prop-name "name" property.
391 If \bt_p{trace} has no name, this function returns \c NULL.
394 Trace of which to get the name.
398 Name of \bt_p{trace}, or \c NULL if none.
400 The returned pointer remains valid as long as \bt_p{trace}
404 @bt_pre_not_null{trace}
406 @sa bt_trace_set_name() —
407 Sets the name of a trace.
409 extern const char *bt_trace_get_name(const bt_trace
*trace
);
414 <a href="https://en.wikipedia.org/wiki/Universally_unique_identifier">UUID</a>
415 of the trace \bt_p{trace} to a copy of \bt_p{uuid}.
417 See the \ref api-tir-trace-prop-uuid "UUID" property.
420 Trace of which to set the UUID to \bt_p{uuid}.
422 New UUID of \bt_p{trace} (copied).
424 @bt_pre_not_null{trace}
426 @bt_pre_not_null{uuid}
428 @sa bt_trace_get_uuid() —
429 Returns the UUID of a trace.
431 extern void bt_trace_set_uuid(bt_trace
*trace
, bt_uuid uuid
);
435 Returns the UUID of the trace \bt_p{trace}.
437 See the \ref api-tir-trace-prop-uuid "UUID" property.
439 If \bt_p{trace} has no UUID, this function returns \c NULL.
442 Trace of which to get the UUID.
446 UUID of \bt_p{trace}, or \c NULL if none.
448 The returned pointer remains valid as long as \bt_p{trace}
452 @bt_pre_not_null{trace}
454 @sa bt_trace_set_uuid() —
455 Sets the UUID of a trace.
457 extern bt_uuid
bt_trace_get_uuid(const bt_trace
*trace
);
461 Status codes for bt_trace_set_name().
463 typedef enum bt_trace_set_environment_entry_status
{
468 BT_TRACE_SET_ENVIRONMENT_ENTRY_STATUS_OK
= __BT_FUNC_STATUS_OK
,
474 BT_TRACE_SET_ENVIRONMENT_ENTRY_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
475 } bt_trace_set_environment_entry_status
;
479 Sets the value of the environment entry of the trace \bt_p{trace}
480 named \bt_p{name} to the signed integer \bt_p{value}.
482 See the \ref api-tir-trace-prop-env "environment" property.
484 On success, if \bt_p{trace} already contains an environment entry named
485 \bt_p{name}, this function replaces the existing entry's value with
489 Trace in which to insert or replace an environment entry named
490 \bt_p{name} with the value \bt_p{value}.
492 Name of the entry to insert or replace in \bt_p{trace} (copied).
494 Value of the environment entry to insert or replace in \bt_p{trace}.
496 @retval #BT_TRACE_SET_ENVIRONMENT_ENTRY_STATUS_OK
498 @retval #BT_TRACE_SET_ENVIRONMENT_ENTRY_STATUS_MEMORY_ERROR
501 @bt_pre_not_null{trace}
503 @bt_pre_not_null{name}
505 @sa bt_trace_set_environment_entry_string() —
506 Sets a trace environment entry's value to a string.
508 extern bt_trace_set_environment_entry_status
509 bt_trace_set_environment_entry_integer(bt_trace
*trace
, const char *name
,
514 Sets the value of the environment entry of the trace \bt_p{trace}
515 named \bt_p{name} to the string \bt_p{value}.
517 See the \ref api-tir-trace-prop-env "environment" property.
519 On success, if \bt_p{trace} already contains an environment entry named
520 \bt_p{name}, this function replaces the existing entry's value with
524 Trace in which to insert or replace an environment entry named
525 \bt_p{name} with the value \bt_p{value}.
527 Name of the entry to insert or replace in \bt_p{trace} (copied).
529 Value of the environment entry to insert or replace in \bt_p{trace}.
531 @retval #BT_TRACE_SET_ENVIRONMENT_ENTRY_STATUS_OK
533 @retval #BT_TRACE_SET_ENVIRONMENT_ENTRY_STATUS_MEMORY_ERROR
536 @bt_pre_not_null{trace}
538 @bt_pre_not_null{name}
539 @bt_pre_not_null{value}
541 @sa bt_trace_set_environment_entry_integer() —
542 Sets a trace environment entry's value to a signed integer.
544 extern bt_trace_set_environment_entry_status
545 bt_trace_set_environment_entry_string(bt_trace
*trace
, const char *name
,
550 Returns the number of environment entries contained in the trace
553 See the \ref api-tir-trace-prop-env "environment" property.
556 Trace of which to get the number of environment entries.
559 Number of environment entries in \bt_p{trace}.
561 @bt_pre_not_null{trace}
563 extern uint64_t bt_trace_get_environment_entry_count(const bt_trace
*trace
);
567 Borrows the environment entry at index \bt_p{index} from the
568 trace \bt_p{trace}, setting \bt_p{*name} to its name and
569 \bt_p{*value} to its value.
571 See the \ref api-tir-trace-prop-env "environment" property.
574 Trace from which to borrow the environment entry at index
577 Index of the environment entry to borrow from \bt_p{trace}.
580 <strong>On success</strong>, \bt_p{*name} is the name of the
581 environment entry at index \bt_p{index} in \bt_p{trace}.
583 The returned pointer remains valid as long as \bt_p{trace}
588 <strong>On success</strong>, \bt_p{*value} is a \em borrowed
589 reference of the environment entry at index \bt_p{index} in
592 \bt_p{*value} is either a \bt_sint_val
593 (#BT_VALUE_TYPE_SIGNED_INTEGER) or a \bt_string_val
594 (#BT_VALUE_TYPE_STRING).
596 The returned pointer remains valid as long as \bt_p{trace}
600 @bt_pre_not_null{trace}
602 \bt_p{index} is less than the number of environment entries in
603 \bt_p{trace} (as returned by
604 bt_trace_get_environment_entry_count()).
605 @bt_pre_not_null{name}
606 @bt_pre_not_null{value}
608 @sa bt_trace_get_environment_entry_count() —
609 Returns the number of environment entries contained in a trace.
611 extern void bt_trace_borrow_environment_entry_by_index_const(
612 const bt_trace
*trace
, uint64_t index
,
613 const char **name
, const bt_value
**value
);
617 Borrows the value of the environment entry named \bt_p{name}
618 in the trace \bt_p{trace}.
620 See the \ref api-tir-trace-prop-env "environment" property.
622 If there's no environment entry named \bt_p{name} in \bt_p{trace}, this
623 function returns \c NULL.
626 Trace from which to borrow the value of the environment entry
629 Name of the environment entry to borrow from \bt_p{trace}.
633 \em Borrowed reference of the value of the environment entry named
634 \bt_p{name} in \bt_p{trace}.
636 The returned value is either a \bt_sint_val
637 (#BT_VALUE_TYPE_SIGNED_INTEGER) or a \bt_string_val
638 (#BT_VALUE_TYPE_STRING).
640 The returned pointer remains valid as long as \bt_p{trace}
644 @bt_pre_not_null{trace}
645 @bt_pre_not_null{name}
647 extern const bt_value
*bt_trace_borrow_environment_entry_value_by_name_const(
648 const bt_trace
*trace
, const char *name
);
652 Sets the user attributes of the trace \bt_p{trace} to
653 \bt_p{user_attributes}.
655 See the \ref api-tir-trace-prop-user-attrs "user attributes"
659 When you create a default trace with bt_trace_create(), the trace's
660 initial user attributes is an empty \bt_map_val. Therefore you can
661 borrow it with bt_trace_borrow_user_attributes() and fill it
662 directly instead of setting a new one with this function.
665 Trace of which to set the user attributes to \bt_p{user_attributes}.
666 @param[in] user_attributes
667 New user attributes of \bt_p{trace}.
669 @bt_pre_not_null{trace}
671 @bt_pre_not_null{user_attributes}
672 @bt_pre_is_map_val{user_attributes}
674 @sa bt_trace_borrow_user_attributes() —
675 Borrows the user attributes of a trace.
677 extern void bt_trace_set_user_attributes(
678 bt_trace
*trace
, const bt_value
*user_attributes
);
682 Borrows the user attributes of the trace \bt_p{trace}.
684 See the \ref api-tir-trace-prop-user-attrs "user attributes"
688 When you create a default trace with bt_trace_create(), the trace's
689 initial user attributes is an empty \bt_map_val.
692 Trace from which to borrow the user attributes.
695 User attributes of \bt_p{trace} (a \bt_map_val).
697 @bt_pre_not_null{trace}
699 @sa bt_trace_set_user_attributes() —
700 Sets the user attributes of a trace.
701 @sa bt_trace_borrow_user_attributes_const() —
702 \c const version of this function.
704 extern bt_value
*bt_trace_borrow_user_attributes(bt_trace
*trace
);
708 Borrows the user attributes of the trace \bt_p{trace}
711 See bt_trace_borrow_user_attributes().
713 extern const bt_value
*bt_trace_borrow_user_attributes_const(
714 const bt_trace
*trace
);
725 User function for bt_trace_add_destruction_listener().
727 This is the user function type for a trace destruction listener.
730 Trace being destroyed (\ref api-fund-freezing "frozen").
732 User data, as passed as the \bt_p{user_data} parameter of
733 bt_trace_add_destruction_listener().
735 @bt_pre_not_null{trace}
738 The reference count of \bt_p{trace} is not changed.
741 @sa bt_trace_add_destruction_listener() —
742 Adds a destruction listener to a trace.
744 typedef void (* bt_trace_destruction_listener_func
)(
745 const bt_trace
*trace
, void *user_data
);
749 Status codes for bt_trace_add_destruction_listener().
751 typedef enum bt_trace_add_listener_status
{
756 BT_TRACE_ADD_LISTENER_STATUS_OK
= __BT_FUNC_STATUS_OK
,
762 BT_TRACE_ADD_LISTENER_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
763 } bt_trace_add_listener_status
;
767 Adds a destruction listener having the function \bt_p{user_func}
768 to the trace \bt_p{trace}.
770 All the destruction listener user functions of a trace are called
771 when it's being destroyed.
773 If \bt_p{listener_id} is not \c NULL, then this function, on success,
774 sets \bt_p{*listener_id} to the ID of the added destruction listener
775 within \bt_p{trace}. You can then use this ID to remove the
776 added destruction listener with bt_trace_remove_destruction_listener().
779 Trace to add the destruction listener to.
781 User function of the destruction listener to add to
784 User data to pass as the \bt_p{user_data} parameter of
786 @param[out] listener_id
787 <strong>On success and if not \c NULL</strong>, \bt_p{*listener_id}
788 is the ID of the added destruction listener within
791 @retval #BT_TRACE_ADD_LISTENER_STATUS_OK
793 @retval #BT_TRACE_ADD_LISTENER_STATUS_MEMORY_ERROR
796 @bt_pre_not_null{trace}
797 @bt_pre_not_null{user_func}
799 @sa bt_trace_remove_destruction_listener() —
800 Removes a destruction listener from a trace.
802 extern bt_trace_add_listener_status
bt_trace_add_destruction_listener(
803 const bt_trace
*trace
,
804 bt_trace_destruction_listener_func user_func
,
805 void *user_data
, bt_listener_id
*listener_id
);
809 Status codes for bt_trace_remove_destruction_listener().
811 typedef enum bt_trace_remove_listener_status
{
816 BT_TRACE_REMOVE_LISTENER_STATUS_OK
= __BT_FUNC_STATUS_OK
,
822 BT_TRACE_REMOVE_LISTENER_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
823 } bt_trace_remove_listener_status
;
827 Removes the destruction listener having the ID \bt_p{listener_id}
828 from the trace \bt_p{trace}.
830 The destruction listener to remove from \bt_p{trace} was
831 previously added with bt_trace_add_destruction_listener().
833 You can call this function when \bt_p{trace} is
834 \ref api-fund-freezing "frozen".
837 Trace from which to remove the destruction listener having
838 the ID \bt_p{listener_id}.
839 @param[in] listener_id
840 ID of the destruction listener to remove from \bt_p{trace}.
842 @retval #BT_TRACE_REMOVE_LISTENER_STATUS_OK
844 @retval #BT_TRACE_REMOVE_LISTENER_STATUS_MEMORY_ERROR
847 @bt_pre_not_null{trace}
849 \bt_p{listener_id} is the ID of an existing destruction listener
852 @sa bt_trace_add_destruction_listener() —
853 Adds a destruction listener to a trace.
855 extern bt_trace_remove_listener_status
bt_trace_remove_destruction_listener(
856 const bt_trace
*trace
, bt_listener_id listener_id
);
861 @name Reference count
867 Increments the \ref api-fund-shared-object "reference count" of
868 the trace \bt_p{trace}.
872 Trace of which to increment the reference count.
877 @sa bt_trace_put_ref() —
878 Decrements the reference count of a trace.
880 extern void bt_trace_get_ref(const bt_trace
*trace
);
884 Decrements the \ref api-fund-shared-object "reference count" of
885 the trace \bt_p{trace}.
889 Trace of which to decrement the reference count.
894 @sa bt_trace_get_ref() —
895 Increments the reference count of a trace.
897 extern void bt_trace_put_ref(const bt_trace
*trace
);
901 Decrements the reference count of the trace
902 \bt_p{_trace}, and then sets \bt_p{_trace} to \c NULL.
906 Trace of which to decrement the reference count.
911 @bt_pre_assign_expr{_trace}
913 #define BT_TRACE_PUT_REF_AND_RESET(_trace) \
915 bt_trace_put_ref(_trace); \
921 Decrements the reference count of the trace \bt_p{_dst}, sets
922 \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL.
924 This macro effectively moves a trace reference from the expression
925 \bt_p{_src} to the expression \bt_p{_dst}, putting the existing
926 \bt_p{_dst} reference.
930 Destination expression.
941 @bt_pre_assign_expr{_dst}
942 @bt_pre_assign_expr{_src}
944 #define BT_TRACE_MOVE_REF(_dst, _src) \
946 bt_trace_put_ref(_dst); \
959 #endif /* BABELTRACE2_TRACE_IR_TRACE_H */