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-ns
81 (only available when the class of the trace was created
82 from a \bt_comp which belongs to a trace processing \bt_graph
83 with the effective \bt_mip version 1)
86 Namespace of the trace.
88 Use bt_trace_set_namespace() and
89 bt_trace_get_namespace().
93 \anchor api-tir-trace-prop-name
99 Use bt_trace_set_name() and bt_trace_get_name().
103 \bt_dt_opt Depending on the effective \bt_mip (MIP) version of the
104 trace processing \bt_graph:
109 \anchor api-tir-trace-prop-uuid
113 <a href="https://en.wikipedia.org/wiki/Universally_unique_identifier">UUID</a>
116 The trace's UUID uniquely identifies the trace.
118 Use bt_trace_set_uuid() and bt_trace_get_uuid().
122 \anchor api-tir-trace-prop-uid
126 <a href="https://en.wikipedia.org/wiki/Unique_identifier">Unique identifier</a>
129 The combination of the trace's
130 \link api-tir-trace-prop-name name\endlink and UID
131 uniquely identifies the trace.
133 Use bt_trace_set_uid() and bt_trace_get_uid().
138 \anchor api-tir-trace-prop-env
139 \bt_dt_opt Environment
142 Generic key-value store which describes the environment of the trace
143 (for example, the system's hostname, its network address, the
144 tracer's name and version, and the rest).
146 Trace environment keys are strings while values are signed integers
149 Set a trace environment entry's value with
150 bt_trace_set_environment_entry_integer() and
151 bt_trace_set_environment_entry_string().
153 Get the number of environment entries in a trace with
154 bt_trace_get_environment_entry_count().
156 Borrow an environment entry from a trace with
157 bt_trace_borrow_environment_entry_value_by_name_const().
161 \anchor api-tir-trace-prop-user-attrs
162 \bt_dt_opt User attributes
165 User attributes of the trace.
167 User attributes are custom attributes attached to a trace.
169 Use bt_trace_set_user_attributes(),
170 bt_trace_borrow_user_attributes(), and
171 bt_trace_borrow_user_attributes_const().
182 @typedef struct bt_trace bt_trace;
197 Creates a default trace from the \bt_trace_cls \bt_p{trace_class}.
199 This function instantiates \bt_p{trace_class}.
201 On success, the returned trace has the following property values:
208 <td>\bt_mip version 1: \ref api-tir-trace-prop-ns "Namespace"
211 <td>\ref api-tir-trace-prop-name "Name"
214 <td>\bt_mip (MIP) version 0: \ref api-tir-trace-prop-uuid "UUID"
217 <td>MIP 1: \ref api-tir-trace-prop-uid "UID"
220 <td>\ref api-tir-trace-prop-env "Environment"
223 <td>\ref api-tir-trace-prop-user-attrs "User attributes"
224 <td>Empty \bt_map_val
227 @param[in] trace_class
228 Trace class from which to create the default trace.
231 New trace reference, or \c NULL on memory error.
233 extern bt_trace
*bt_trace_create(bt_trace_class
*trace_class
) __BT_NOEXCEPT
;
244 Borrows the \ref api-tir-trace-cls "class" of the trace
248 Trace of which to borrow the class.
251 \em Borrowed reference of the class of \bt_p{trace}.
253 @bt_pre_not_null{trace}
255 @sa bt_trace_borrow_class_const() —
256 \c const version of this function.
258 extern bt_trace_class
*bt_trace_borrow_class(bt_trace
*trace
) __BT_NOEXCEPT
;
262 Borrows the \ref api-tir-trace-cls "class" of the trace
263 \bt_p{trace} (\c const version).
265 See bt_trace_borrow_class().
267 extern const bt_trace_class
*bt_trace_borrow_class_const(
268 const bt_trace
*trace
) __BT_NOEXCEPT
;
279 Returns the number of \bt_p_stream contained in the trace
283 Trace of which to get the number of contained streams.
286 Number of contained streams in \bt_p{trace}.
288 @bt_pre_not_null{trace}
290 extern uint64_t bt_trace_get_stream_count(const bt_trace
*trace
) __BT_NOEXCEPT
;
294 Borrows the \bt_stream at index \bt_p{index} from the
298 Trace from which to borrow the stream at index
301 Index of the stream to borrow from \bt_p{trace}.
305 \em Borrowed reference of the stream of
306 \bt_p{trace} at index \bt_p{index}.
308 The returned pointer remains valid as long as \bt_p{trace}
312 @bt_pre_not_null{trace}
314 \bt_p{index} is less than the number of streams in
315 \bt_p{trace} (as returned by
316 bt_trace_get_stream_count()).
318 @sa bt_trace_get_stream_count() —
319 Returns the number of streams contained in a trace.
320 @sa bt_trace_borrow_stream_by_index_const() —
321 \c const version of this function.
323 extern bt_stream
*bt_trace_borrow_stream_by_index(bt_trace
*trace
,
324 uint64_t index
) __BT_NOEXCEPT
;
328 Borrows the \bt_stream at index \bt_p{index} from the
329 trace \bt_p{trace} (\c const version).
331 See bt_trace_borrow_stream_by_index().
333 extern const bt_stream
*bt_trace_borrow_stream_by_index_const(
334 const bt_trace
*trace
, uint64_t index
) __BT_NOEXCEPT
;
338 Borrows the \bt_stream having the numeric ID \bt_p{id} from the
341 If there's no stream having the numeric ID \bt_p{id} in
342 \bt_p{trace}, this function returns \c NULL.
345 Trace from which to borrow the stream having the
346 numeric ID \bt_p{id}.
348 ID of the stream to borrow from \bt_p{trace}.
352 \em Borrowed reference of the stream of
353 \bt_p{trace} having the numeric ID \bt_p{id}, or \c NULL
356 The returned pointer remains valid as long as \bt_p{trace}
360 @bt_pre_not_null{trace}
362 @sa bt_trace_borrow_stream_by_id_const() —
363 \c const version of this function.
365 extern bt_stream
*bt_trace_borrow_stream_by_id(bt_trace
*trace
,
366 uint64_t id
) __BT_NOEXCEPT
;
370 Borrows the \bt_stream having the numeric ID \bt_p{id} from the
371 trace \bt_p{trace} (\c const version).
373 See bt_trace_borrow_stream_by_id().
375 extern const bt_stream
*bt_trace_borrow_stream_by_id_const(
376 const bt_trace
*trace
, uint64_t id
) __BT_NOEXCEPT
;
387 Status codes for bt_trace_set_namespace().
389 typedef enum bt_trace_set_namespace_status
{
394 BT_TRACE_SET_NAMESPACE_STATUS_OK
= __BT_FUNC_STATUS_OK
,
400 BT_TRACE_SET_NAMESPACE_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
401 } bt_trace_set_namespace_status
;
405 Sets the namespace of the trace \bt_p{trace} to a copy of \bt_p{ns}.
407 See the \ref api-tir-trace-prop-ns "namespace" property.
410 Trace of which to set the namespace to \bt_p{ns}.
412 New namespace of \bt_p{trace} (copied).
414 @retval #BT_TRACE_SET_NAMESPACE_STATUS_OK
416 @retval #BT_TRACE_SET_NAMESPACE_STATUS_MEMORY_ERROR
419 @bt_pre_not_null{trace}
421 @bt_pre_trace_with_mip{trace, 1}
424 @sa bt_trace_get_namespace() —
425 Returns the namespace of a trace.
427 extern bt_trace_set_namespace_status
bt_trace_set_namespace(bt_trace
*trace
,
428 const char *ns
) __BT_NOEXCEPT
;
432 Returns the namespace of the trace \bt_p{trace}.
434 See the \ref api-tir-trace-prop-ns "namespace" property.
436 If \bt_p{trace} has no namespace, this function returns \c NULL.
439 Trace of which to get the namespace.
443 Namespace of \bt_p{trace}, or \c NULL if none.
445 The returned pointer remains valid as long as \bt_p{trace}
449 @bt_pre_not_null{trace}
450 @bt_pre_stream_cls_with_mip{trace, 1}
452 @sa bt_trace_set_namespace() —
453 Sets the namespace of a trace.
455 extern const char *bt_trace_get_namespace(const bt_trace
*trace
) __BT_NOEXCEPT
;
459 Status codes for bt_trace_set_name().
461 typedef enum bt_trace_set_name_status
{
466 BT_TRACE_SET_NAME_STATUS_OK
= __BT_FUNC_STATUS_OK
,
472 BT_TRACE_SET_NAME_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
473 } bt_trace_set_name_status
;
477 Sets the name of the trace \bt_p{trace} to a copy of \bt_p{name}.
479 See the \ref api-tir-trace-prop-name "name" property.
482 Trace of which to set the name to \bt_p{name}.
484 New name of \bt_p{trace} (copied).
486 @retval #BT_TRACE_SET_NAME_STATUS_OK
488 @retval #BT_TRACE_SET_NAME_STATUS_MEMORY_ERROR
491 @bt_pre_not_null{trace}
493 @bt_pre_not_null{name}
495 @sa bt_trace_get_name() —
496 Returns the name of a trace.
498 extern bt_trace_set_name_status
bt_trace_set_name(bt_trace
*trace
,
499 const char *name
) __BT_NOEXCEPT
;
503 Returns the name of the trace \bt_p{trace}.
505 See the \ref api-tir-trace-prop-name "name" property.
507 If \bt_p{trace} has no name, this function returns \c NULL.
510 Trace of which to get the name.
514 Name of \bt_p{trace}, or \c NULL if none.
516 The returned pointer remains valid as long as \bt_p{trace}
520 @bt_pre_not_null{trace}
522 @sa bt_trace_set_name() —
523 Sets the name of a trace.
525 extern const char *bt_trace_get_name(const bt_trace
*trace
) __BT_NOEXCEPT
;
530 <a href="https://en.wikipedia.org/wiki/Universally_unique_identifier">UUID</a>
531 of the trace \bt_p{trace} to a copy of \bt_p{uuid}.
535 This function is only available when the class of \bt_p{trace} was
536 created from a \bt_comp which belongs to a trace processing
537 \bt_graph with the effective \bt_mip (MIP) version 0.
539 With MIP 1, see the
540 \ref api-tir-trace-prop-uid "UID" property.
543 See the \ref api-tir-trace-prop-uuid "UUID" property.
546 Trace of which to set the UUID to \bt_p{uuid}.
548 New UUID of \bt_p{trace} (copied).
550 @bt_pre_not_null{trace}
552 @bt_pre_trace_with_mip{trace, 0}
553 @bt_pre_not_null{uuid}
555 @sa bt_trace_get_uuid() —
556 Returns the UUID of a trace.
558 extern void bt_trace_set_uuid(bt_trace
*trace
, bt_uuid uuid
) __BT_NOEXCEPT
;
562 Status codes for bt_trace_set_uid().
564 typedef enum bt_trace_set_uid_status
{
569 BT_TRACE_SET_UID_STATUS_OK
= __BT_FUNC_STATUS_OK
,
575 BT_TRACE_SET_UID_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
576 } bt_trace_set_uid_status
;
580 Returns the UUID of the trace \bt_p{trace}.
584 This function is only available when the class of \bt_p{trace} was
585 created from a \bt_comp which belongs to a trace processing
586 \bt_graph with the effective \bt_mip (MIP) version 0.
588 With MIP 1, see the
589 \ref api-tir-trace-prop-uid "UID" property.
592 See the \ref api-tir-trace-prop-uuid "UUID" property.
594 If \bt_p{trace} has no UUID, this function returns \c NULL.
597 Trace of which to get the UUID.
601 UUID of \bt_p{trace}, or \c NULL if none.
603 The returned pointer remains valid as long as \bt_p{trace}
607 @bt_pre_not_null{trace}
608 @bt_pre_trace_with_mip{trace, 0}
610 @sa bt_trace_set_uuid() —
611 Sets the UUID of a trace.
613 extern bt_uuid
bt_trace_get_uuid(const bt_trace
*trace
) __BT_NOEXCEPT
;
618 <a href="https://en.wikipedia.org/wiki/Unique_identifier">unique identifier</a>
619 (UID) of \bt_p{trace} to a copy of \bt_p{uid}.
621 See the \ref api-tir-trace-prop-uid "UID" property.
624 Trace of which to set the UID to \bt_p{uid}.
626 New UID of \bt_p{trace} (copied).
628 @bt_pre_not_null{trace}
630 @bt_pre_trace_with_mip{trace, 1}
631 @bt_pre_not_null{uid}
633 @sa bt_trace_get_uid() —
634 Returns the UID of a trace.
636 extern bt_trace_set_uid_status
bt_trace_set_uid(bt_trace
*trace
, const char *uid
);
640 Returns the UID of the trace \bt_p{trace}.
642 See the \ref api-tir-trace-prop-uid "UID" property.
644 If \bt_p{trace} has no UID, this function returns \c NULL.
647 Trace of which to get the UID.
651 UID of \bt_p{trace}, or \c NULL if none.
653 The returned pointer remains valid as long as \bt_p{trace}
657 @bt_pre_not_null{trace}
658 @bt_pre_trace_with_mip{trace, 1}
660 @sa bt_trace_set_uid() —
661 Sets the UID of a trace.
663 extern const char *bt_trace_get_uid(const bt_trace
*trace
);
667 Status codes for bt_trace_set_name().
669 typedef enum bt_trace_set_environment_entry_status
{
674 BT_TRACE_SET_ENVIRONMENT_ENTRY_STATUS_OK
= __BT_FUNC_STATUS_OK
,
680 BT_TRACE_SET_ENVIRONMENT_ENTRY_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
681 } bt_trace_set_environment_entry_status
;
685 Sets the value of the environment entry of the trace \bt_p{trace}
686 named \bt_p{name} to the signed integer \bt_p{value}.
688 See the \ref api-tir-trace-prop-env "environment" property.
690 On success, if \bt_p{trace} already contains an environment entry named
691 \bt_p{name}, this function replaces the existing entry's value with
695 Trace in which to insert or replace an environment entry named
696 \bt_p{name} with the value \bt_p{value}.
698 Name of the entry to insert or replace in \bt_p{trace} (copied).
700 Value of the environment entry to insert or replace in \bt_p{trace}.
702 @retval #BT_TRACE_SET_ENVIRONMENT_ENTRY_STATUS_OK
704 @retval #BT_TRACE_SET_ENVIRONMENT_ENTRY_STATUS_MEMORY_ERROR
707 @bt_pre_not_null{trace}
709 @bt_pre_not_null{name}
711 @sa bt_trace_set_environment_entry_string() —
712 Sets a trace environment entry's value to a string.
714 extern bt_trace_set_environment_entry_status
715 bt_trace_set_environment_entry_integer(bt_trace
*trace
, const char *name
,
716 int64_t value
) __BT_NOEXCEPT
;
720 Sets the value of the environment entry of the trace \bt_p{trace}
721 named \bt_p{name} to the string \bt_p{value}.
723 See the \ref api-tir-trace-prop-env "environment" property.
725 On success, if \bt_p{trace} already contains an environment entry named
726 \bt_p{name}, this function replaces the existing entry's value with
730 Trace in which to insert or replace an environment entry named
731 \bt_p{name} with the value \bt_p{value}.
733 Name of the entry to insert or replace in \bt_p{trace} (copied).
735 Value of the environment entry to insert or replace in \bt_p{trace}.
737 @retval #BT_TRACE_SET_ENVIRONMENT_ENTRY_STATUS_OK
739 @retval #BT_TRACE_SET_ENVIRONMENT_ENTRY_STATUS_MEMORY_ERROR
742 @bt_pre_not_null{trace}
744 @bt_pre_not_null{name}
745 @bt_pre_not_null{value}
747 @sa bt_trace_set_environment_entry_integer() —
748 Sets a trace environment entry's value to a signed integer.
750 extern bt_trace_set_environment_entry_status
751 bt_trace_set_environment_entry_string(bt_trace
*trace
, const char *name
,
752 const char *value
) __BT_NOEXCEPT
;
756 Returns the number of environment entries contained in the trace
759 See the \ref api-tir-trace-prop-env "environment" property.
762 Trace of which to get the number of environment entries.
765 Number of environment entries in \bt_p{trace}.
767 @bt_pre_not_null{trace}
769 extern uint64_t bt_trace_get_environment_entry_count(
770 const bt_trace
*trace
) __BT_NOEXCEPT
;
774 Borrows the environment entry at index \bt_p{index} from the
775 trace \bt_p{trace}, setting \bt_p{*name} to its name and
776 \bt_p{*value} to its value.
778 See the \ref api-tir-trace-prop-env "environment" property.
781 Trace from which to borrow the environment entry at index
784 Index of the environment entry to borrow from \bt_p{trace}.
787 <strong>On success</strong>, \bt_p{*name} is the name of the
788 environment entry at index \bt_p{index} in \bt_p{trace}.
790 The returned pointer remains valid as long as \bt_p{trace}
795 <strong>On success</strong>, \bt_p{*value} is a \em borrowed
796 reference of the environment entry at index \bt_p{index} in
799 \bt_p{*value} is either a \bt_sint_val
800 (#BT_VALUE_TYPE_SIGNED_INTEGER) or a \bt_string_val
801 (#BT_VALUE_TYPE_STRING).
803 The returned pointer remains valid as long as \bt_p{trace}
807 @bt_pre_not_null{trace}
809 \bt_p{index} is less than the number of environment entries in
810 \bt_p{trace} (as returned by
811 bt_trace_get_environment_entry_count()).
812 @bt_pre_not_null{name}
813 @bt_pre_not_null{value}
815 @sa bt_trace_get_environment_entry_count() —
816 Returns the number of environment entries contained in a trace.
818 extern void bt_trace_borrow_environment_entry_by_index_const(
819 const bt_trace
*trace
, uint64_t index
,
820 const char **name
, const bt_value
**value
) __BT_NOEXCEPT
;
824 Borrows the value of the environment entry named \bt_p{name}
825 in the trace \bt_p{trace}.
827 See the \ref api-tir-trace-prop-env "environment" property.
829 If there's no environment entry named \bt_p{name} in \bt_p{trace}, this
830 function returns \c NULL.
833 Trace from which to borrow the value of the environment entry
836 Name of the environment entry to borrow from \bt_p{trace}.
840 \em Borrowed reference of the value of the environment entry named
841 \bt_p{name} in \bt_p{trace}.
843 The returned value is either a \bt_sint_val
844 (#BT_VALUE_TYPE_SIGNED_INTEGER) or a \bt_string_val
845 (#BT_VALUE_TYPE_STRING).
847 The returned pointer remains valid as long as \bt_p{trace}
851 @bt_pre_not_null{trace}
852 @bt_pre_not_null{name}
854 extern const bt_value
*bt_trace_borrow_environment_entry_value_by_name_const(
855 const bt_trace
*trace
, const char *name
) __BT_NOEXCEPT
;
859 Sets the user attributes of the trace \bt_p{trace} to
860 \bt_p{user_attributes}.
862 See the \ref api-tir-trace-prop-user-attrs "user attributes"
866 When you create a default trace with bt_trace_create(), the trace's
867 initial user attributes is an empty \bt_map_val. Therefore you can
868 borrow it with bt_trace_borrow_user_attributes() and fill it
869 directly instead of setting a new one with this function.
872 Trace of which to set the user attributes to \bt_p{user_attributes}.
873 @param[in] user_attributes
874 New user attributes of \bt_p{trace}.
876 @bt_pre_not_null{trace}
878 @bt_pre_not_null{user_attributes}
879 @bt_pre_is_map_val{user_attributes}
881 @sa bt_trace_borrow_user_attributes() —
882 Borrows the user attributes of a trace.
884 extern void bt_trace_set_user_attributes(
885 bt_trace
*trace
, const bt_value
*user_attributes
) __BT_NOEXCEPT
;
889 Borrows the user attributes of the trace \bt_p{trace}.
891 See the \ref api-tir-trace-prop-user-attrs "user attributes"
895 When you create a default trace with bt_trace_create(), the trace's
896 initial user attributes is an empty \bt_map_val.
899 Trace from which to borrow the user attributes.
902 User attributes of \bt_p{trace} (a \bt_map_val).
904 @bt_pre_not_null{trace}
906 @sa bt_trace_set_user_attributes() —
907 Sets the user attributes of a trace.
908 @sa bt_trace_borrow_user_attributes_const() —
909 \c const version of this function.
911 extern bt_value
*bt_trace_borrow_user_attributes(bt_trace
*trace
) __BT_NOEXCEPT
;
915 Borrows the user attributes of the trace \bt_p{trace}
918 See bt_trace_borrow_user_attributes().
920 extern const bt_value
*bt_trace_borrow_user_attributes_const(
921 const bt_trace
*trace
) __BT_NOEXCEPT
;
932 User function for bt_trace_add_destruction_listener().
934 This is the user function type for a trace destruction listener.
937 Trace being destroyed (\ref api-fund-freezing "frozen").
939 User data, as passed as the \bt_p{user_data} parameter of
940 bt_trace_add_destruction_listener().
942 @bt_pre_not_null{trace}
945 The reference count of \bt_p{trace} is not changed.
948 @sa bt_trace_add_destruction_listener() —
949 Adds a destruction listener to a trace.
951 typedef void (* bt_trace_destruction_listener_func
)(
952 const bt_trace
*trace
, void *user_data
);
956 Status codes for bt_trace_add_destruction_listener().
958 typedef enum bt_trace_add_listener_status
{
963 BT_TRACE_ADD_LISTENER_STATUS_OK
= __BT_FUNC_STATUS_OK
,
969 BT_TRACE_ADD_LISTENER_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
970 } bt_trace_add_listener_status
;
974 Adds a destruction listener having the function \bt_p{user_func}
975 to the trace \bt_p{trace}.
977 All the destruction listener user functions of a trace are called
978 when it's being destroyed.
980 If \bt_p{listener_id} is not \c NULL, then this function, on success,
981 sets \bt_p{*listener_id} to the ID of the added destruction listener
982 within \bt_p{trace}. You can then use this ID to remove the
983 added destruction listener with bt_trace_remove_destruction_listener().
986 Trace to add the destruction listener to.
988 User function of the destruction listener to add to
991 User data to pass as the \bt_p{user_data} parameter of
993 @param[out] listener_id
994 <strong>On success and if not \c NULL</strong>, \bt_p{*listener_id}
995 is the ID of the added destruction listener within
998 @retval #BT_TRACE_ADD_LISTENER_STATUS_OK
1000 @retval #BT_TRACE_ADD_LISTENER_STATUS_MEMORY_ERROR
1003 @bt_pre_not_null{trace}
1004 @bt_pre_not_null{user_func}
1006 @sa bt_trace_remove_destruction_listener() —
1007 Removes a destruction listener from a trace.
1009 extern bt_trace_add_listener_status
bt_trace_add_destruction_listener(
1010 const bt_trace
*trace
,
1011 bt_trace_destruction_listener_func user_func
,
1012 void *user_data
, bt_listener_id
*listener_id
) __BT_NOEXCEPT
;
1016 Status codes for bt_trace_remove_destruction_listener().
1018 typedef enum bt_trace_remove_listener_status
{
1023 BT_TRACE_REMOVE_LISTENER_STATUS_OK
= __BT_FUNC_STATUS_OK
,
1029 BT_TRACE_REMOVE_LISTENER_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
1030 } bt_trace_remove_listener_status
;
1034 Removes the destruction listener having the ID \bt_p{listener_id}
1035 from the trace \bt_p{trace}.
1037 The destruction listener to remove from \bt_p{trace} was
1038 previously added with bt_trace_add_destruction_listener().
1040 You can call this function when \bt_p{trace} is
1041 \ref api-fund-freezing "frozen".
1044 Trace from which to remove the destruction listener having
1045 the ID \bt_p{listener_id}.
1046 @param[in] listener_id
1047 ID of the destruction listener to remove from \bt_p{trace}.
1049 @retval #BT_TRACE_REMOVE_LISTENER_STATUS_OK
1051 @retval #BT_TRACE_REMOVE_LISTENER_STATUS_MEMORY_ERROR
1054 @bt_pre_not_null{trace}
1056 \bt_p{listener_id} is the ID of an existing destruction listener
1059 @sa bt_trace_add_destruction_listener() —
1060 Adds a destruction listener to a trace.
1062 extern bt_trace_remove_listener_status
bt_trace_remove_destruction_listener(
1063 const bt_trace
*trace
, bt_listener_id listener_id
)
1069 @name Reference count
1075 Increments the \ref api-fund-shared-object "reference count" of
1076 the trace \bt_p{trace}.
1080 Trace of which to increment the reference count.
1085 @sa bt_trace_put_ref() —
1086 Decrements the reference count of a trace.
1088 extern void bt_trace_get_ref(const bt_trace
*trace
) __BT_NOEXCEPT
;
1092 Decrements the \ref api-fund-shared-object "reference count" of
1093 the trace \bt_p{trace}.
1097 Trace of which to decrement the reference count.
1102 @sa bt_trace_get_ref() —
1103 Increments the reference count of a trace.
1105 extern void bt_trace_put_ref(const bt_trace
*trace
) __BT_NOEXCEPT
;
1109 Decrements the reference count of the trace
1110 \bt_p{_trace}, and then sets \bt_p{_trace} to \c NULL.
1114 Trace of which to decrement the reference count.
1116 Can contain \c NULL.
1119 @bt_pre_assign_expr{_trace}
1121 #define BT_TRACE_PUT_REF_AND_RESET(_trace) \
1123 bt_trace_put_ref(_trace); \
1129 Decrements the reference count of the trace \bt_p{_dst}, sets
1130 \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL.
1132 This macro effectively moves a trace reference from the expression
1133 \bt_p{_src} to the expression \bt_p{_dst}, putting the existing
1134 \bt_p{_dst} reference.
1138 Destination expression.
1140 Can contain \c NULL.
1146 Can contain \c NULL.
1149 @bt_pre_assign_expr{_dst}
1150 @bt_pre_assign_expr{_src}
1152 #define BT_TRACE_MOVE_REF(_dst, _src) \
1154 bt_trace_put_ref(_dst); \
1167 #endif /* BABELTRACE2_TRACE_IR_TRACE_H */