1 #ifndef BABELTRACE2_TRACE_IR_TRACE_H
2 #define BABELTRACE2_TRACE_IR_TRACE_H
5 * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
7 * Permission is hereby granted, free of charge, to any person obtaining a copy
8 * of this software and associated documentation files (the "Software"), to deal
9 * in the Software without restriction, including without limitation the rights
10 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
11 * copies of the Software, and to permit persons to whom the Software is
12 * furnished to do so, subject to the following conditions:
14 * The above copyright notice and this permission notice shall be included in
15 * all copies or substantial portions of the Software.
17 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
18 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
19 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
20 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
21 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
22 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
26 #ifndef __BT_IN_BABELTRACE_H
27 # error "Please include <babeltrace2/babeltrace.h> instead."
32 #include <babeltrace2/types.h>
39 @defgroup api-tir-trace Trace
43 Trace (set of \bt_p_stream).
45 A <strong><em>trace</em></strong> is a set of \bt_p_stream with
48 @image html trace-structure.png
50 In the illustration above, notice that a trace is an instance of a
51 \bt_trace_cls and that it contains streams.
53 Borrow the class of a trace with bt_trace_borrow_class() and
54 bt_trace_borrow_class_const().
56 A trace is a \ref api-tir "trace IR" data object.
58 A trace is a \ref api-fund-shared-object "shared object": get a
59 new reference with bt_trace_get_ref() and put an existing
60 reference with bt_trace_put_ref().
62 Some library functions \ref api-fund-freezing "freeze" traces on
63 success. The documentation of those functions indicate this
64 postcondition. With a frozen trace, you can still:
66 - Create \bt_p_stream from it with bt_stream_create() or
67 bt_stream_create_with_id().
68 - Add a destruction listener to it with
69 bt_trace_add_destruction_listener().
71 The type of a trace is #bt_trace.
73 A trace contains \bt_p_stream. All the streams of a
74 given trace have unique \ref api-tir-stream-prop-id "numeric IDs".
75 Get the number of streams in a trace with bt_trace_get_stream_count().
76 Borrow a specific stream from a trace with
77 bt_trace_borrow_stream_by_index(),
78 bt_trace_borrow_stream_by_index_const(), bt_trace_borrow_stream_by_id(),
79 or bt_trace_borrow_stream_by_id_const().
81 Create a default trace from a \bt_trace_cls with bt_trace_create().
83 Add to and remove a destruction listener from a trace with
84 bt_trace_add_destruction_listener() and
85 bt_trace_remove_destruction_listener().
89 A trace has the following properties:
93 \anchor api-tir-trace-prop-name
99 Use bt_trace_set_name() and bt_trace_get_name().
103 \anchor api-tir-trace-prop-uuid
107 <a href="https://en.wikipedia.org/wiki/Universally_unique_identifier">UUID</a>
110 The trace's UUID uniquely identifies the trace.
112 Use bt_trace_set_uuid() and bt_trace_get_uuid().
116 \anchor api-tir-trace-prop-env
117 \bt_dt_opt Environment
120 Generic key-value store which describes the environment of the trace
121 (for example, the system's hostname, its network address, the
122 tracer's name and version, and the rest).
124 Trace environment keys are strings while values are signed integers
127 Set a trace environment entry's value with
128 bt_trace_set_environment_entry_integer() and
129 bt_trace_set_environment_entry_string().
131 Get the number of environment entries in a trace with
132 bt_trace_get_environment_entry_count().
134 Borrow an environment entry from a trace with
135 bt_trace_borrow_environment_entry_value_by_name_const().
139 \anchor api-tir-trace-prop-user-attrs
140 \bt_dt_opt User attributes
143 User attributes of the trace.
145 User attributes are custom attributes attached to a trace.
147 Use bt_trace_set_user_attributes(),
148 bt_trace_borrow_user_attributes(), and
149 bt_trace_borrow_user_attributes_const().
160 @typedef struct bt_trace bt_trace;
175 Creates a default trace from the \bt_trace_cls \bt_p{trace_class}.
177 This function instantiates \bt_p{trace_class}.
179 On success, the returned trace has the following property values:
186 <td>\ref api-tir-trace-prop-name "Name"
189 <td>\ref api-tir-trace-prop-uuid "UUID"
192 <td>\ref api-tir-trace-prop-env "Environment"
195 <td>\ref api-tir-trace-prop-user-attrs "User attributes"
196 <td>Empty \bt_map_val
199 @param[in] trace_class
200 Trace class from which to create the default trace.
203 New trace reference, or \c NULL on memory error.
205 extern bt_trace
*bt_trace_create(bt_trace_class
*trace_class
);
216 Borrows the \ref api-tir-trace-cls "class" of the trace
220 Trace of which to borrow the class.
223 \em Borrowed reference of the class of \bt_p{trace}.
225 @bt_pre_not_null{trace}
227 @sa bt_trace_borrow_class_const() —
228 \c const version of this function.
230 extern bt_trace_class
*bt_trace_borrow_class(bt_trace
*trace
);
234 Borrows the \ref api-tir-trace-cls "class" of the trace
235 \bt_p{trace} (\c const version).
237 See bt_trace_borrow_class().
239 extern const bt_trace_class
*bt_trace_borrow_class_const(
240 const bt_trace
*trace
);
251 Returns the number of \bt_p_stream contained in the trace
255 Trace of which to get the number of contained streams.
258 Number of contained streams in \bt_p{trace}.
260 @bt_pre_not_null{trace}
262 extern uint64_t bt_trace_get_stream_count(const bt_trace
*trace
);
266 Borrows the \bt_stream at index \bt_p{index} from the
270 Trace from which to borrow the stream at index
273 Index of the stream to borrow from \bt_p{trace}.
277 \em Borrowed reference of the stream of
278 \bt_p{trace} at index \bt_p{index}.
280 The returned pointer remains valid as long as \bt_p{trace}
284 @bt_pre_not_null{trace}
286 \bt_p{index} is less than the number of streams in
287 \bt_p{trace} (as returned by
288 bt_trace_get_stream_count()).
290 @sa bt_trace_get_stream_count() —
291 Returns the number of streams contained in a trace.
292 @sa bt_trace_borrow_stream_by_index_const() —
293 \c const version of this function.
295 extern bt_stream
*bt_trace_borrow_stream_by_index(bt_trace
*trace
,
300 Borrows the \bt_stream at index \bt_p{index} from the
301 trace \bt_p{trace} (\c const version).
303 See bt_trace_borrow_stream_by_index().
305 extern const bt_stream
*bt_trace_borrow_stream_by_index_const(
306 const bt_trace
*trace
, uint64_t index
);
310 Borrows the \bt_stream having the numeric ID \bt_p{id} from the
313 If there's no stream having the numeric ID \bt_p{id} in
314 \bt_p{trace}, this function returns \c NULL.
317 Trace from which to borrow the stream having the
318 numeric ID \bt_p{id}.
320 ID of the stream to borrow from \bt_p{trace}.
324 \em Borrowed reference of the stream of
325 \bt_p{trace} having the numeric ID \bt_p{id}, or \c NULL
328 The returned pointer remains valid as long as \bt_p{trace}
332 @bt_pre_not_null{trace}
334 @sa bt_trace_borrow_stream_by_id_const() —
335 \c const version of this function.
337 extern bt_stream
*bt_trace_borrow_stream_by_id(bt_trace
*trace
,
342 Borrows the \bt_stream having the numeric ID \bt_p{id} from the
343 trace \bt_p{trace} (\c const version).
345 See bt_trace_borrow_stream_by_id().
347 extern const bt_stream
*bt_trace_borrow_stream_by_id_const(
348 const bt_trace
*trace
, uint64_t id
);
359 Status codes for bt_trace_set_name().
361 typedef enum bt_trace_set_name_status
{
366 BT_TRACE_SET_NAME_STATUS_OK
= __BT_FUNC_STATUS_OK
,
372 BT_TRACE_SET_NAME_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
373 } bt_trace_set_name_status
;
377 Sets the name of the trace \bt_p{trace} to a copy of \bt_p{name}.
379 See the \ref api-tir-trace-prop-name "name" property.
382 Trace of which to set the name to \bt_p{name}.
384 New name of \bt_p{trace} (copied).
386 @retval #BT_TRACE_SET_NAME_STATUS_OK
388 @retval #BT_TRACE_SET_NAME_STATUS_MEMORY_ERROR
391 @bt_pre_not_null{trace}
393 @bt_pre_not_null{name}
395 @sa bt_trace_get_name() —
396 Returns the name of a trace.
398 extern bt_trace_set_name_status
bt_trace_set_name(bt_trace
*trace
,
403 Returns the name of the trace \bt_p{trace}.
405 See the \ref api-tir-trace-prop-name "name" property.
407 If \bt_p{trace} has no name, this function returns \c NULL.
410 Trace of which to get the name.
414 Name of \bt_p{trace}, or \c NULL if none.
416 The returned pointer remains valid as long as \bt_p{trace}
420 @bt_pre_not_null{trace}
422 @sa bt_trace_set_name() —
423 Sets the name of a trace.
425 extern const char *bt_trace_get_name(const bt_trace
*trace
);
430 <a href="https://en.wikipedia.org/wiki/Universally_unique_identifier">UUID</a>
431 of the trace \bt_p{trace} to a copy of \bt_p{uuid}.
433 See the \ref api-tir-trace-prop-uuid "UUID" property.
436 Trace of which to set the UUID to \bt_p{uuid}.
438 New UUID of \bt_p{trace} (copied).
440 @bt_pre_not_null{trace}
442 @bt_pre_not_null{uuid}
444 @sa bt_trace_get_uuid() —
445 Returns the UUID of a trace.
447 extern void bt_trace_set_uuid(bt_trace
*trace
, bt_uuid uuid
);
451 Returns the UUID of the trace \bt_p{trace}.
453 See the \ref api-tir-trace-prop-uuid "UUID" property.
455 If \bt_p{trace} has no UUID, this function returns \c NULL.
458 Trace of which to get the UUID.
462 UUID of \bt_p{trace}, or \c NULL if none.
464 The returned pointer remains valid as long as \bt_p{trace}
468 @bt_pre_not_null{trace}
470 @sa bt_trace_set_uuid() —
471 Sets the UUID of a trace.
473 extern bt_uuid
bt_trace_get_uuid(const bt_trace
*trace
);
477 Status codes for bt_trace_set_name().
479 typedef enum bt_trace_set_environment_entry_status
{
484 BT_TRACE_SET_ENVIRONMENT_ENTRY_STATUS_OK
= __BT_FUNC_STATUS_OK
,
490 BT_TRACE_SET_ENVIRONMENT_ENTRY_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
491 } bt_trace_set_environment_entry_status
;
495 Sets the value of the environment entry of the trace \bt_p{trace}
496 named \bt_p{name} to the signed integer \bt_p{value}.
498 See the \ref api-tir-trace-prop-env "environment" property.
500 On success, if \bt_p{trace} already contains an environment entry named
501 \bt_p{name}, this function replaces the existing entry's value with
505 Trace in which to insert or replace an environment entry named
506 \bt_p{name} with the value \bt_p{value}.
508 Name of the entry to insert or replace in \bt_p{trace} (copied).
510 Value of the environment entry to insert or replace in \bt_p{trace}.
512 @retval #BT_TRACE_SET_ENVIRONMENT_ENTRY_STATUS_OK
514 @retval #BT_TRACE_SET_ENVIRONMENT_ENTRY_STATUS_MEMORY_ERROR
517 @bt_pre_not_null{trace}
519 @bt_pre_not_null{name}
521 @sa bt_trace_set_environment_entry_string() —
522 Sets a trace environment entry's value to a string.
524 extern bt_trace_set_environment_entry_status
525 bt_trace_set_environment_entry_integer(bt_trace
*trace
, const char *name
,
530 Sets the value of the environment entry of the trace \bt_p{trace}
531 named \bt_p{name} to the string \bt_p{value}.
533 See the \ref api-tir-trace-prop-env "environment" property.
535 On success, if \bt_p{trace} already contains an environment entry named
536 \bt_p{name}, this function replaces the existing entry's value with
540 Trace in which to insert or replace an environment entry named
541 \bt_p{name} with the value \bt_p{value}.
543 Name of the entry to insert or replace in \bt_p{trace} (copied).
545 Value of the environment entry to insert or replace in \bt_p{trace}.
547 @retval #BT_TRACE_SET_ENVIRONMENT_ENTRY_STATUS_OK
549 @retval #BT_TRACE_SET_ENVIRONMENT_ENTRY_STATUS_MEMORY_ERROR
552 @bt_pre_not_null{trace}
554 @bt_pre_not_null{name}
555 @bt_pre_not_null{value}
557 @sa bt_trace_set_environment_entry_integer() —
558 Sets a trace environment entry's value to a signed integer.
560 extern bt_trace_set_environment_entry_status
561 bt_trace_set_environment_entry_string(bt_trace
*trace
, const char *name
,
566 Returns the number of environment entries contained in the trace
569 See the \ref api-tir-trace-prop-env "environment" property.
572 Trace of which to get the number of environment entries.
575 Number of environment entries in \bt_p{trace}.
577 @bt_pre_not_null{trace}
579 extern uint64_t bt_trace_get_environment_entry_count(const bt_trace
*trace
);
583 Borrows the environment entry at index \bt_p{index} from the
584 trace \bt_p{trace}, setting \bt_p{*name} to its name and
585 \bt_p{*value} to its value.
587 See the \ref api-tir-trace-prop-env "environment" property.
590 Trace from which to borrow the environment entry at index
593 Index of the environment entry to borrow from \bt_p{trace}.
596 <strong>On success</strong>, \bt_p{*name} is the name of the
597 environment entry at index \bt_p{index} in \bt_p{trace}.
599 The returned pointer remains valid as long as \bt_p{trace}
604 <strong>On success</strong>, \bt_p{*value} is a \em borrowed
605 reference of the environment entry at index \bt_p{index} in
608 \bt_p{*value} is either a \bt_sint_val
609 (#BT_VALUE_TYPE_SIGNED_INTEGER) or a \bt_string_val
610 (#BT_VALUE_TYPE_STRING).
612 The returned pointer remains valid as long as \bt_p{trace}
616 @bt_pre_not_null{trace}
618 \bt_p{index} is less than the number of environment entries in
619 \bt_p{trace} (as returned by
620 bt_trace_get_environment_entry_count()).
621 @bt_pre_not_null{name}
622 @bt_pre_not_null{value}
624 @sa bt_trace_get_environment_entry_count() —
625 Returns the number of environment entries contained in a trace.
627 extern void bt_trace_borrow_environment_entry_by_index_const(
628 const bt_trace
*trace
, uint64_t index
,
629 const char **name
, const bt_value
**value
);
633 Borrows the value of the environment entry named \bt_p{name}
634 in the trace \bt_p{trace}.
636 See the \ref api-tir-trace-prop-env "environment" property.
638 If there's no environment entry named \bt_p{name} in \bt_p{trace}, this
639 function returns \c NULL.
642 Trace from which to borrow the value of the environment entry
645 Name of the environment entry to borrow from \bt_p{trace}.
649 \em Borrowed reference of the value of the environment entry named
650 \bt_p{name} in \bt_p{trace}.
652 The returned value is either a \bt_sint_val
653 (#BT_VALUE_TYPE_SIGNED_INTEGER) or a \bt_string_val
654 (#BT_VALUE_TYPE_STRING).
656 The returned pointer remains valid as long as \bt_p{trace}
660 @bt_pre_not_null{trace}
661 @bt_pre_not_null{name}
663 extern const bt_value
*bt_trace_borrow_environment_entry_value_by_name_const(
664 const bt_trace
*trace
, const char *name
);
668 Sets the user attributes of the trace \bt_p{trace} to
669 \bt_p{user_attributes}.
671 See the \ref api-tir-trace-prop-user-attrs "user attributes"
675 When you create a default trace with bt_trace_create(), the trace's
676 initial user attributes is an empty \bt_map_val. Therefore you can
677 borrow it with bt_trace_borrow_user_attributes() and fill it
678 directly instead of setting a new one with this function.
681 Trace of which to set the user attributes to \bt_p{user_attributes}.
682 @param[in] user_attributes
683 New user attributes of \bt_p{trace}.
685 @bt_pre_not_null{trace}
687 @bt_pre_not_null{user_attributes}
688 @bt_pre_is_map_val{user_attributes}
690 @sa bt_trace_borrow_user_attributes() —
691 Borrows the user attributes of a trace.
693 extern void bt_trace_set_user_attributes(
694 bt_trace
*trace
, const bt_value
*user_attributes
);
698 Borrows the user attributes of the trace \bt_p{trace}.
700 See the \ref api-tir-trace-prop-user-attrs "user attributes"
704 When you create a default trace with bt_trace_create(), the trace's
705 initial user attributes is an empty \bt_map_val.
708 Trace from which to borrow the user attributes.
711 User attributes of \bt_p{trace} (a \bt_map_val).
713 @bt_pre_not_null{trace}
715 @sa bt_trace_set_user_attributes() —
716 Sets the user attributes of a trace.
717 @sa bt_trace_borrow_user_attributes_const() —
718 \c const version of this function.
720 extern bt_value
*bt_trace_borrow_user_attributes(bt_trace
*trace
);
724 Borrows the user attributes of the trace \bt_p{trace}
727 See bt_trace_borrow_user_attributes().
729 extern const bt_value
*bt_trace_borrow_user_attributes_const(
730 const bt_trace
*trace
);
741 User function for bt_trace_add_destruction_listener().
743 This is the user function type for a trace destruction listener.
746 Trace being destroyed (\ref api-fund-freezing "frozen").
748 User data, as passed as the \bt_p{user_data} parameter of
749 bt_trace_add_destruction_listener().
751 @bt_pre_not_null{trace}
754 The reference count of \bt_p{trace} is not changed.
757 @sa bt_trace_add_destruction_listener() —
758 Adds a destruction listener to a trace.
760 typedef void (* bt_trace_destruction_listener_func
)(
761 const bt_trace
*trace
, void *user_data
);
765 Status codes for bt_trace_add_destruction_listener().
767 typedef enum bt_trace_add_listener_status
{
772 BT_TRACE_ADD_LISTENER_STATUS_OK
= __BT_FUNC_STATUS_OK
,
778 BT_TRACE_ADD_LISTENER_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
779 } bt_trace_add_listener_status
;
783 Adds a destruction listener having the function \bt_p{user_func}
784 to the trace \bt_p{trace}.
786 All the destruction listener user functions of a trace are called
787 when it's being destroyed.
789 If \bt_p{listener_id} is not \c NULL, then this function, on success,
790 sets \bt_p{*listener_id} to the ID of the added destruction listener
791 within \bt_p{trace}. You can then use this ID to remove the
792 added destruction listener with bt_trace_remove_destruction_listener().
795 Trace to add the destruction listener to.
797 User function of the destruction listener to add to
800 User data to pass as the \bt_p{user_data} parameter of
802 @param[out] listener_id
803 <strong>On success and if not \c NULL</strong>, \bt_p{*listener_id}
804 is the ID of the added destruction listener within
807 @retval #BT_TRACE_ADD_LISTENER_STATUS_OK
809 @retval #BT_TRACE_ADD_LISTENER_STATUS_MEMORY_ERROR
812 @bt_pre_not_null{trace}
813 @bt_pre_not_null{user_func}
815 @sa bt_trace_remove_destruction_listener() —
816 Removes a destruction listener from a trace.
818 extern bt_trace_add_listener_status
bt_trace_add_destruction_listener(
819 const bt_trace
*trace
,
820 bt_trace_destruction_listener_func user_func
,
821 void *user_data
, bt_listener_id
*listener_id
);
825 Status codes for bt_trace_remove_destruction_listener().
827 typedef enum bt_trace_remove_listener_status
{
832 BT_TRACE_REMOVE_LISTENER_STATUS_OK
= __BT_FUNC_STATUS_OK
,
838 BT_TRACE_REMOVE_LISTENER_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
839 } bt_trace_remove_listener_status
;
843 Removes the destruction listener having the ID \bt_p{listener_id}
844 from the trace \bt_p{trace}.
846 The destruction listener to remove from \bt_p{trace} was
847 previously added with bt_trace_add_destruction_listener().
849 You can call this function when \bt_p{trace} is
850 \ref api-fund-freezing "frozen".
853 Trace from which to remove the destruction listener having
854 the ID \bt_p{listener_id}.
855 @param[in] listener_id
856 ID of the destruction listener to remove from \bt_p{trace}.
858 @retval #BT_TRACE_REMOVE_LISTENER_STATUS_OK
860 @retval #BT_TRACE_REMOVE_LISTENER_STATUS_MEMORY_ERROR
863 @bt_pre_not_null{trace}
865 \bt_p{listener_id} is the ID of an existing destruction listener
868 @sa bt_trace_add_destruction_listener() —
869 Adds a destruction listener to a trace.
871 extern bt_trace_remove_listener_status
bt_trace_remove_destruction_listener(
872 const bt_trace
*trace
, bt_listener_id listener_id
);
877 @name Reference count
883 Increments the \ref api-fund-shared-object "reference count" of
884 the trace \bt_p{trace}.
888 Trace of which to increment the reference count.
893 @sa bt_trace_put_ref() —
894 Decrements the reference count of a trace.
896 extern void bt_trace_get_ref(const bt_trace
*trace
);
900 Decrements the \ref api-fund-shared-object "reference count" of
901 the trace \bt_p{trace}.
905 Trace of which to decrement the reference count.
910 @sa bt_trace_get_ref() —
911 Increments the reference count of a trace.
913 extern void bt_trace_put_ref(const bt_trace
*trace
);
917 Decrements the reference count of the trace
918 \bt_p{_trace}, and then sets \bt_p{_trace} to \c NULL.
922 Trace of which to decrement the reference count.
927 @bt_pre_assign_expr{_trace}
929 #define BT_TRACE_PUT_REF_AND_RESET(_trace) \
931 bt_trace_put_ref(_trace); \
937 Decrements the reference count of the trace \bt_p{_dst}, sets
938 \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL.
940 This macro effectively moves a trace reference from the expression
941 \bt_p{_src} to the expression \bt_p{_dst}, putting the existing
942 \bt_p{_dst} reference.
946 Destination expression.
957 @bt_pre_assign_expr{_dst}
958 @bt_pre_assign_expr{_src}
960 #define BT_TRACE_MOVE_REF(_dst, _src) \
962 bt_trace_put_ref(_dst); \
975 #endif /* BABELTRACE2_TRACE_IR_TRACE_H */