2 * SPDX-License-Identifier: MIT
4 * Copyright (C) 2010-2019 EfficiOS Inc. and Linux Foundation
7 #ifndef BABELTRACE2_TRACE_IR_TRACE_CLASS_H
8 #define BABELTRACE2_TRACE_IR_TRACE_CLASS_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-cls Trace class
31 A <strong><em>trace class</em></strong> is the class of \bt_p_trace:
33 @image html trace-structure.png
35 In the illustration above, notice that a trace is an instance of a
38 A trace class is a \ref api-tir "trace IR" metadata object.
40 A trace class is a \ref api-fund-shared-object "shared object": get a
41 new reference with bt_trace_class_get_ref() and put an existing
42 reference with bt_trace_class_put_ref().
44 Some library functions \ref api-fund-freezing "freeze" trace classes on
45 success. The documentation of those functions indicate this
46 postcondition. With a frozen trace class, you can still:
48 - Create and add a \bt_p_stream_cls to it with
49 bt_stream_class_create() or bt_stream_class_create_with_id().
50 - Add a destruction listener to it with
51 bt_trace_class_add_destruction_listener().
53 The type of a trace class is #bt_trace_class.
55 A trace class contains \bt_p_stream_cls. All the stream classes of a
56 given trace class have unique
57 \ref api-tir-stream-cls-prop-id "numeric IDs". Get the number of stream
58 classes in a trace class with bt_trace_class_get_stream_class_count().
59 Borrow a specific stream class from a trace class with
60 bt_trace_class_borrow_stream_class_by_index(),
61 bt_trace_class_borrow_stream_class_by_index_const(),
62 bt_trace_class_borrow_stream_class_by_id(), or
63 bt_trace_class_borrow_stream_class_by_id_const().
65 Set whether or not the \bt_p_stream_cls you create for a trace class get
66 automatic numeric IDs with
67 bt_trace_class_set_assigns_automatic_stream_class_id().
69 Create a default trace class from a \bt_self_comp with
70 bt_trace_class_create().
72 Add to and remove a destruction listener from a trace class with
73 bt_trace_class_add_destruction_listener() and
74 bt_trace_class_remove_destruction_listener().
78 A trace class has the following properties:
82 \anchor api-tir-trace-cls-prop-auto-sc-id
83 Assigns automatic stream class IDs?
86 Whether or not the stream classes you create and add to the trace
87 class get \ref api-tir-stream-cls-prop-id "numeric IDs"
90 Depending on the value of this property, to create a stream class
91 and add it to the trace class:
96 Use bt_stream_class_create().
101 Use bt_stream_class_create_with_id().
105 Use bt_trace_class_set_assigns_automatic_stream_class_id()
106 and bt_trace_class_assigns_automatic_stream_class_id().
110 \anchor api-tir-trace-cls-prop-user-attrs
111 \bt_dt_opt User attributes
114 User attributes of the trace class.
116 User attributes are custom attributes attached to a trace class.
118 Use bt_trace_class_set_user_attributes(),
119 bt_trace_class_borrow_user_attributes(), and
120 bt_trace_class_borrow_user_attributes_const().
131 @typedef struct bt_trace_class bt_trace_class;
146 Creates a default trace class from the \bt_self_comp
147 \bt_p{self_component}.
149 On success, the returned trace class has the following property values:
156 <td>\ref api-tir-trace-cls-prop-auto-sc-id "Assigns automatic stream class IDs?"
159 <td>\ref api-tir-trace-cls-prop-user-attrs "User attributes"
160 <td>Empty \bt_map_val
163 @param[in] self_component
164 Self component from which to create the default trace class.
167 New trace class reference, or \c NULL on memory error.
169 extern bt_trace_class
*bt_trace_class_create(bt_self_component
*self_component
);
174 @name Stream class access
180 Returns the number of \bt_p_stream_cls contained in the trace
181 class \bt_p{trace_class}.
183 @param[in] trace_class
184 Trace class of which to get the number of contained stream classes.
187 Number of contained stream classes in \bt_p{trace_class}.
189 @bt_pre_not_null{trace_class}
191 extern uint64_t bt_trace_class_get_stream_class_count(
192 const bt_trace_class
*trace_class
);
196 Borrows the \bt_stream_cls at index \bt_p{index} from the
197 trace class \bt_p{trace_class}.
199 @param[in] trace_class
200 Trace class from which to borrow the stream class at index
203 Index of the stream class to borrow from \bt_p{trace_class}.
207 \em Borrowed reference of the stream class of
208 \bt_p{trace_class} at index \bt_p{index}.
210 The returned pointer remains valid as long as \bt_p{trace_class}
214 @bt_pre_not_null{trace_class}
216 \bt_p{index} is less than the number of stream classes in
217 \bt_p{trace_class} (as returned by
218 bt_trace_class_get_stream_class_count()).
220 @sa bt_trace_class_get_stream_class_count() —
221 Returns the number of stream classes contained in a trace class.
222 @sa bt_trace_class_borrow_stream_class_by_index_const() —
223 \c const version of this function.
225 extern bt_stream_class
*bt_trace_class_borrow_stream_class_by_index(
226 bt_trace_class
*trace_class
, uint64_t index
);
230 Borrows the \bt_stream_cls at index \bt_p{index} from the
231 trace class \bt_p{trace_class} (\c const version).
233 See bt_trace_class_borrow_stream_class_by_index().
235 extern const bt_stream_class
*
236 bt_trace_class_borrow_stream_class_by_index_const(
237 const bt_trace_class
*trace_class
, uint64_t index
);
241 Borrows the \bt_stream_cls having the numeric ID \bt_p{id} from the
242 trace class \bt_p{trace_class}.
244 If there's no stream class having the numeric ID \bt_p{id} in
245 \bt_p{trace_class}, this function returns \c NULL.
247 @param[in] trace_class
248 Trace class from which to borrow the stream class having the
249 numeric ID \bt_p{id}.
251 ID of the stream class to borrow from \bt_p{trace_class}.
255 \em Borrowed reference of the stream class of
256 \bt_p{trace_class} having the numeric ID \bt_p{id}, or \c NULL
259 The returned pointer remains valid as long as \bt_p{trace_class}
263 @bt_pre_not_null{trace_class}
265 @sa bt_trace_class_borrow_stream_class_by_id_const() —
266 \c const version of this function.
268 extern bt_stream_class
*bt_trace_class_borrow_stream_class_by_id(
269 bt_trace_class
*trace_class
, uint64_t id
);
273 Borrows the \bt_stream_cls having the numeric ID \bt_p{id} from the
274 trace class \bt_p{trace_class} (\c const version).
276 See bt_trace_class_borrow_stream_class_by_id().
278 extern const bt_stream_class
*bt_trace_class_borrow_stream_class_by_id_const(
279 const bt_trace_class
*trace_class
, uint64_t id
);
290 Sets whether or not the trace class \bt_p{trace_class} automatically
291 assigns a numeric ID to a \bt_stream_cls you create and add to it.
293 See the \ref api-tir-trace-cls-prop-auto-sc-id "assigns automatic stream class IDs?"
296 @param[in] trace_class
297 Trace class of which to set whether or not it assigns automatic
299 @param[in] assigns_automatic_stream_class_id
300 #BT_TRUE to make \bt_p{trace_class} assign automatic stream class
303 @bt_pre_not_null{trace_class}
304 @bt_pre_hot{trace_class}
306 @sa bt_trace_class_assigns_automatic_stream_class_id() —
307 Returns whether or not a trace class automatically assigns
310 extern void bt_trace_class_set_assigns_automatic_stream_class_id(
311 bt_trace_class
*trace_class
,
312 bt_bool assigns_automatic_stream_class_id
);
316 Returns whether or not the trace class \bt_p{trace_class}
317 automatically assigns a numeric ID to a \bt_stream_cls you create
320 See the \ref api-tir-trace-cls-prop-auto-sc-id "assigns automatic stream class IDs?"
323 @param[in] trace_class
324 Trace class of which to get whether or not it assigns automatic
328 #BT_TRUE if \bt_p{trace_class} automatically
329 assigns stream class IDs.
331 @bt_pre_not_null{trace_class}
333 @sa bt_trace_class_set_assigns_automatic_stream_class_id() —
334 Sets whether or not a trace class automatically assigns
337 extern bt_bool
bt_trace_class_assigns_automatic_stream_class_id(
338 const bt_trace_class
*trace_class
);
342 Sets the user attributes of the trace class \bt_p{trace_class} to
343 \bt_p{user_attributes}.
345 See the \ref api-tir-trace-cls-prop-user-attrs "user attributes"
349 When you create a default trace class with bt_trace_class_create()
350 or bt_trace_class_create_with_id(), the trace class's initial user
351 attributes is an empty \bt_map_val. Therefore you can borrow it with
352 bt_trace_class_borrow_user_attributes() and fill it directly
353 instead of setting a new one with this function.
355 @param[in] trace_class
356 Trace class of which to set the user attributes to
357 \bt_p{user_attributes}.
358 @param[in] user_attributes
359 New user attributes of \bt_p{trace_class}.
361 @bt_pre_not_null{trace_class}
362 @bt_pre_hot{trace_class}
363 @bt_pre_not_null{user_attributes}
364 @bt_pre_is_map_val{user_attributes}
366 @sa bt_trace_class_borrow_user_attributes() —
367 Borrows the user attributes of a trace class.
369 extern void bt_trace_class_set_user_attributes(
370 bt_trace_class
*trace_class
, const bt_value
*user_attributes
);
374 Borrows the user attributes of the trace class \bt_p{trace_class}.
376 See the \ref api-tir-trace-cls-prop-user-attrs "user attributes"
380 When you create a default trace class with bt_trace_class_create()
381 or bt_trace_class_create_with_id(), the trace class's initial user
382 attributes is an empty \bt_map_val.
384 @param[in] trace_class
385 Trace class from which to borrow the user attributes.
388 User attributes of \bt_p{trace_class} (a \bt_map_val).
390 @bt_pre_not_null{trace_class}
392 @sa bt_trace_class_set_user_attributes() —
393 Sets the user attributes of a trace class.
394 @sa bt_trace_class_borrow_user_attributes_const() —
395 \c const version of this function.
397 extern bt_value
*bt_trace_class_borrow_user_attributes(
398 bt_trace_class
*trace_class
);
402 Borrows the user attributes of the trace class \bt_p{trace_class}
405 See bt_trace_class_borrow_user_attributes().
407 extern const bt_value
*bt_trace_class_borrow_user_attributes_const(
408 const bt_trace_class
*trace_class
);
419 User function for bt_trace_class_add_destruction_listener().
421 This is the user function type for a trace class destruction listener.
423 @param[in] trace_class
424 Trace class being destroyed (\ref api-fund-freezing "frozen").
426 User data, as passed as the \bt_p{user_data} parameter of
427 bt_trace_class_add_destruction_listener().
429 @bt_pre_not_null{trace_class}
432 The reference count of \bt_p{trace_class} is not changed.
435 @sa bt_trace_class_add_destruction_listener() —
436 Adds a destruction listener to a trace class.
438 typedef void (* bt_trace_class_destruction_listener_func
)(
439 const bt_trace_class
*trace_class
, void *user_data
);
443 Status codes for bt_trace_class_add_destruction_listener().
445 typedef enum bt_trace_class_add_listener_status
{
450 BT_TRACE_CLASS_ADD_LISTENER_STATUS_OK
= __BT_FUNC_STATUS_OK
,
456 BT_TRACE_CLASS_ADD_LISTENER_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
457 } bt_trace_class_add_listener_status
;
461 Adds a destruction listener having the function \bt_p{user_func}
462 to the trace class \bt_p{trace_class}.
464 All the destruction listener user functions of a trace class are called
465 when it's being destroyed.
467 If \bt_p{listener_id} is not \c NULL, then this function, on success,
468 sets \bt_p{*listener_id} to the ID of the added destruction listener
469 within \bt_p{trace_class}. You can then use this ID to remove the
470 added destruction listener with
471 bt_trace_class_remove_destruction_listener().
473 @param[in] trace_class
474 Trace class to add the destruction listener to.
476 User function of the destruction listener to add to
479 User data to pass as the \bt_p{user_data} parameter of
481 @param[out] listener_id
482 <strong>On success and if not \c NULL</strong>, \bt_p{*listener_id}
483 is the ID of the added destruction listener within
486 @retval #BT_TRACE_CLASS_ADD_LISTENER_STATUS_OK
488 @retval #BT_TRACE_CLASS_ADD_LISTENER_STATUS_MEMORY_ERROR
491 @bt_pre_not_null{trace_class}
492 @bt_pre_not_null{user_func}
494 @sa bt_trace_class_remove_destruction_listener() —
495 Removes a destruction listener from a trace class.
497 extern bt_trace_class_add_listener_status
498 bt_trace_class_add_destruction_listener(
499 const bt_trace_class
*trace_class
,
500 bt_trace_class_destruction_listener_func user_func
,
501 void *user_data
, bt_listener_id
*listener_id
);
505 Status codes for bt_trace_class_remove_destruction_listener().
507 typedef enum bt_trace_class_remove_listener_status
{
512 BT_TRACE_CLASS_REMOVE_LISTENER_STATUS_OK
= __BT_FUNC_STATUS_OK
,
518 BT_TRACE_CLASS_REMOVE_LISTENER_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
519 } bt_trace_class_remove_listener_status
;
523 Removes the destruction listener having the ID \bt_p{listener_id}
524 from the trace class \bt_p{trace_class}.
526 The destruction listener to remove from \bt_p{trace_class} was
527 previously added with bt_trace_class_add_destruction_listener().
529 You can call this function when \bt_p{trace_class} is
530 \ref api-fund-freezing "frozen".
532 @param[in] trace_class
533 Trace class from which to remove the destruction listener having
534 the ID \bt_p{listener_id}.
535 @param[in] listener_id
536 ID of the destruction listener to remove from \bt_p{trace_class}.
538 @retval #BT_TRACE_CLASS_REMOVE_LISTENER_STATUS_OK
540 @retval #BT_TRACE_CLASS_REMOVE_LISTENER_STATUS_MEMORY_ERROR
543 @bt_pre_not_null{trace_class}
545 \bt_p{listener_id} is the ID of an existing destruction listener
546 in \bt_p{trace_class}.
548 @sa bt_trace_class_add_destruction_listener() —
549 Adds a destruction listener to a trace class.
551 extern bt_trace_class_remove_listener_status
552 bt_trace_class_remove_destruction_listener(
553 const bt_trace_class
*trace_class
, bt_listener_id listener_id
);
558 @name Reference count
564 Increments the \ref api-fund-shared-object "reference count" of
565 the trace class \bt_p{trace_class}.
567 @param[in] trace_class
569 Trace class of which to increment the reference count.
574 @sa bt_trace_class_put_ref() —
575 Decrements the reference count of a trace class.
577 extern void bt_trace_class_get_ref(const bt_trace_class
*trace_class
);
581 Decrements the \ref api-fund-shared-object "reference count" of
582 the trace class \bt_p{trace_class}.
584 @param[in] trace_class
586 Trace class of which to decrement the reference count.
591 @sa bt_trace_class_get_ref() —
592 Increments the reference count of a trace class.
594 extern void bt_trace_class_put_ref(const bt_trace_class
*trace_class
);
598 Decrements the reference count of the trace class
599 \bt_p{_trace_class}, and then sets \bt_p{_trace_class} to \c NULL.
603 Trace class of which to decrement the reference count.
608 @bt_pre_assign_expr{_trace_class}
610 #define BT_TRACE_CLASS_PUT_REF_AND_RESET(_trace_class) \
612 bt_trace_class_put_ref(_trace_class); \
613 (_trace_class) = NULL; \
618 Decrements the reference count of the trace class \bt_p{_dst}, sets
619 \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL.
621 This macro effectively moves a trace class reference from the expression
622 \bt_p{_src} to the expression \bt_p{_dst}, putting the existing
623 \bt_p{_dst} reference.
627 Destination expression.
638 @bt_pre_assign_expr{_dst}
639 @bt_pre_assign_expr{_src}
641 #define BT_TRACE_CLASS_MOVE_REF(_dst, _src) \
643 bt_trace_class_put_ref(_dst); \
656 #endif /* BABELTRACE2_TRACE_IR_TRACE_CLASS_H */