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().
76 Get the effective \bt_mip version of the trace processing \bt_graph
77 containing the \bt_comp from which a trace class was created with
78 bt_trace_class_get_graph_mip_version().
82 A trace class has the following properties:
86 \anchor api-tir-trace-cls-prop-auto-sc-id
87 Assigns automatic stream class IDs?
90 Whether or not the stream classes you create and add to the trace
91 class get \ref api-tir-stream-cls-prop-id "numeric IDs"
94 Depending on the value of this property, to create a stream class
95 and add it to the trace class:
100 Use bt_stream_class_create().
105 Use bt_stream_class_create_with_id().
109 Use bt_trace_class_set_assigns_automatic_stream_class_id()
110 and bt_trace_class_assigns_automatic_stream_class_id().
114 \anchor api-tir-trace-cls-prop-user-attrs
115 \bt_dt_opt User attributes
118 User attributes of the trace class.
120 User attributes are custom attributes attached to a trace class.
122 Use bt_trace_class_set_user_attributes(),
123 bt_trace_class_borrow_user_attributes(), and
124 bt_trace_class_borrow_user_attributes_const().
135 @typedef struct bt_trace_class bt_trace_class;
150 Creates a default trace class from the \bt_self_comp
151 \bt_p{self_component}.
153 On success, the returned trace class has the following property values:
160 <td>\ref api-tir-trace-cls-prop-auto-sc-id "Assigns automatic stream class IDs?"
163 <td>\ref api-tir-trace-cls-prop-user-attrs "User attributes"
164 <td>Empty \bt_map_val
167 @param[in] self_component
168 Self component from which to create the default trace class.
171 New trace class reference, or \c NULL on memory error.
173 extern bt_trace_class
*bt_trace_class_create(bt_self_component
*self_component
)
179 @name Stream class access
185 Returns the number of \bt_p_stream_cls contained in the trace
186 class \bt_p{trace_class}.
188 @param[in] trace_class
189 Trace class of which to get the number of contained stream classes.
192 Number of contained stream classes in \bt_p{trace_class}.
194 @bt_pre_not_null{trace_class}
196 extern uint64_t bt_trace_class_get_stream_class_count(
197 const bt_trace_class
*trace_class
) __BT_NOEXCEPT
;
201 Borrows the \bt_stream_cls at index \bt_p{index} from the
202 trace class \bt_p{trace_class}.
204 @param[in] trace_class
205 Trace class from which to borrow the stream class at index
208 Index of the stream class to borrow from \bt_p{trace_class}.
212 \em Borrowed reference of the stream class of
213 \bt_p{trace_class} at index \bt_p{index}.
215 The returned pointer remains valid as long as \bt_p{trace_class}
219 @bt_pre_not_null{trace_class}
221 \bt_p{index} is less than the number of stream classes in
222 \bt_p{trace_class} (as returned by
223 bt_trace_class_get_stream_class_count()).
225 @sa bt_trace_class_get_stream_class_count() —
226 Returns the number of stream classes contained in a trace class.
227 @sa bt_trace_class_borrow_stream_class_by_index_const() —
228 \c const version of this function.
230 extern bt_stream_class
*bt_trace_class_borrow_stream_class_by_index(
231 bt_trace_class
*trace_class
, uint64_t index
) __BT_NOEXCEPT
;
235 Borrows the \bt_stream_cls at index \bt_p{index} from the
236 trace class \bt_p{trace_class} (\c const version).
238 See bt_trace_class_borrow_stream_class_by_index().
240 extern const bt_stream_class
*
241 bt_trace_class_borrow_stream_class_by_index_const(
242 const bt_trace_class
*trace_class
,
243 uint64_t index
) __BT_NOEXCEPT
;
247 Borrows the \bt_stream_cls having the numeric ID \bt_p{id} from the
248 trace class \bt_p{trace_class}.
250 If there's no stream class having the numeric ID \bt_p{id} in
251 \bt_p{trace_class}, this function returns \c NULL.
253 @param[in] trace_class
254 Trace class from which to borrow the stream class having the
255 numeric ID \bt_p{id}.
257 ID of the stream class to borrow from \bt_p{trace_class}.
261 \em Borrowed reference of the stream class of
262 \bt_p{trace_class} having the numeric ID \bt_p{id}, or \c NULL
265 The returned pointer remains valid as long as \bt_p{trace_class}
269 @bt_pre_not_null{trace_class}
271 @sa bt_trace_class_borrow_stream_class_by_id_const() —
272 \c const version of this function.
274 extern bt_stream_class
*bt_trace_class_borrow_stream_class_by_id(
275 bt_trace_class
*trace_class
, uint64_t id
) __BT_NOEXCEPT
;
279 Borrows the \bt_stream_cls having the numeric ID \bt_p{id} from the
280 trace class \bt_p{trace_class} (\c const version).
282 See bt_trace_class_borrow_stream_class_by_id().
284 extern const bt_stream_class
*bt_trace_class_borrow_stream_class_by_id_const(
285 const bt_trace_class
*trace_class
, uint64_t id
) __BT_NOEXCEPT
;
296 Sets whether or not the trace class \bt_p{trace_class} automatically
297 assigns a numeric ID to a \bt_stream_cls you create and add to it.
299 See the \ref api-tir-trace-cls-prop-auto-sc-id "assigns automatic stream class IDs?"
302 @param[in] trace_class
303 Trace class of which to set whether or not it assigns automatic
305 @param[in] assigns_automatic_stream_class_id
306 #BT_TRUE to make \bt_p{trace_class} assign automatic stream class
309 @bt_pre_not_null{trace_class}
310 @bt_pre_hot{trace_class}
312 @sa bt_trace_class_assigns_automatic_stream_class_id() —
313 Returns whether or not a trace class automatically assigns
316 extern void bt_trace_class_set_assigns_automatic_stream_class_id(
317 bt_trace_class
*trace_class
,
318 bt_bool assigns_automatic_stream_class_id
) __BT_NOEXCEPT
;
322 Returns whether or not the trace class \bt_p{trace_class}
323 automatically assigns a numeric ID to a \bt_stream_cls you create
326 See the \ref api-tir-trace-cls-prop-auto-sc-id "assigns automatic stream class IDs?"
329 @param[in] trace_class
330 Trace class of which to get whether or not it assigns automatic
334 #BT_TRUE if \bt_p{trace_class} automatically
335 assigns stream class IDs.
337 @bt_pre_not_null{trace_class}
339 @sa bt_trace_class_set_assigns_automatic_stream_class_id() —
340 Sets whether or not a trace class automatically assigns
343 extern bt_bool
bt_trace_class_assigns_automatic_stream_class_id(
344 const bt_trace_class
*trace_class
) __BT_NOEXCEPT
;
348 Sets the user attributes of the trace class \bt_p{trace_class} to
349 \bt_p{user_attributes}.
351 See the \ref api-tir-trace-cls-prop-user-attrs "user attributes"
355 When you create a default trace class with bt_trace_class_create()
356 or bt_trace_class_create_with_id(), the trace class's initial user
357 attributes is an empty \bt_map_val. Therefore you can borrow it with
358 bt_trace_class_borrow_user_attributes() and fill it directly
359 instead of setting a new one with this function.
361 @param[in] trace_class
362 Trace class of which to set the user attributes to
363 \bt_p{user_attributes}.
364 @param[in] user_attributes
365 New user attributes of \bt_p{trace_class}.
367 @bt_pre_not_null{trace_class}
368 @bt_pre_hot{trace_class}
369 @bt_pre_not_null{user_attributes}
370 @bt_pre_is_map_val{user_attributes}
372 @sa bt_trace_class_borrow_user_attributes() —
373 Borrows the user attributes of a trace class.
375 extern void bt_trace_class_set_user_attributes(
376 bt_trace_class
*trace_class
,
377 const bt_value
*user_attributes
) __BT_NOEXCEPT
;
381 Borrows the user attributes of the trace class \bt_p{trace_class}.
383 See the \ref api-tir-trace-cls-prop-user-attrs "user attributes"
387 When you create a default trace class with bt_trace_class_create()
388 or bt_trace_class_create_with_id(), the trace class's initial user
389 attributes is an empty \bt_map_val.
391 @param[in] trace_class
392 Trace class from which to borrow the user attributes.
395 User attributes of \bt_p{trace_class} (a \bt_map_val).
397 @bt_pre_not_null{trace_class}
399 @sa bt_trace_class_set_user_attributes() —
400 Sets the user attributes of a trace class.
401 @sa bt_trace_class_borrow_user_attributes_const() —
402 \c const version of this function.
404 extern bt_value
*bt_trace_class_borrow_user_attributes(
405 bt_trace_class
*trace_class
) __BT_NOEXCEPT
;
409 Borrows the user attributes of the trace class \bt_p{trace_class}
412 See bt_trace_class_borrow_user_attributes().
414 extern const bt_value
*bt_trace_class_borrow_user_attributes_const(
415 const bt_trace_class
*trace_class
) __BT_NOEXCEPT
;
419 Returns the effective \bt_mip (MIP) version of the trace processing
420 \bt_graph containing the \bt_comp from which
421 \bt_p{trace_class} was created.
423 @param[in] trace_class
424 Trace class of which to get the effective MIP version.
427 Effective MIP version of \bt_p{trace_class}.
429 @bt_pre_not_null{trace_class}
431 @sa bt_self_component_get_graph_mip_version() —
432 Returns the effective MIP version of the trace processing
433 graph which contains a given component.
435 extern uint64_t bt_trace_class_get_graph_mip_version(
436 const bt_trace_class
*trace_class
) __BT_NOEXCEPT
;
447 User function for bt_trace_class_add_destruction_listener().
449 This is the user function type for a trace class destruction listener.
451 @param[in] trace_class
452 Trace class being destroyed (\ref api-fund-freezing "frozen").
454 User data, as passed as the \bt_p{user_data} parameter of
455 bt_trace_class_add_destruction_listener().
457 @bt_pre_not_null{trace_class}
460 The reference count of \bt_p{trace_class} is not changed.
463 @sa bt_trace_class_add_destruction_listener() —
464 Adds a destruction listener to a trace class.
466 typedef void (* bt_trace_class_destruction_listener_func
)(
467 const bt_trace_class
*trace_class
, void *user_data
);
471 Status codes for bt_trace_class_add_destruction_listener().
473 typedef enum bt_trace_class_add_listener_status
{
478 BT_TRACE_CLASS_ADD_LISTENER_STATUS_OK
= __BT_FUNC_STATUS_OK
,
484 BT_TRACE_CLASS_ADD_LISTENER_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
485 } bt_trace_class_add_listener_status
;
489 Adds a destruction listener having the function \bt_p{user_func}
490 to the trace class \bt_p{trace_class}.
492 All the destruction listener user functions of a trace class are called
493 when it's being destroyed.
495 If \bt_p{listener_id} is not \c NULL, then this function, on success,
496 sets \bt_p{*listener_id} to the ID of the added destruction listener
497 within \bt_p{trace_class}. You can then use this ID to remove the
498 added destruction listener with
499 bt_trace_class_remove_destruction_listener().
501 @param[in] trace_class
502 Trace class to add the destruction listener to.
504 User function of the destruction listener to add to
507 User data to pass as the \bt_p{user_data} parameter of
509 @param[out] listener_id
510 <strong>On success and if not \c NULL</strong>, \bt_p{*listener_id}
511 is the ID of the added destruction listener within
514 @retval #BT_TRACE_CLASS_ADD_LISTENER_STATUS_OK
516 @retval #BT_TRACE_CLASS_ADD_LISTENER_STATUS_MEMORY_ERROR
519 @bt_pre_not_null{trace_class}
520 @bt_pre_not_null{user_func}
522 @sa bt_trace_class_remove_destruction_listener() —
523 Removes a destruction listener from a trace class.
525 extern bt_trace_class_add_listener_status
526 bt_trace_class_add_destruction_listener(
527 const bt_trace_class
*trace_class
,
528 bt_trace_class_destruction_listener_func user_func
,
529 void *user_data
, bt_listener_id
*listener_id
) __BT_NOEXCEPT
;
533 Status codes for bt_trace_class_remove_destruction_listener().
535 typedef enum bt_trace_class_remove_listener_status
{
540 BT_TRACE_CLASS_REMOVE_LISTENER_STATUS_OK
= __BT_FUNC_STATUS_OK
,
546 BT_TRACE_CLASS_REMOVE_LISTENER_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
547 } bt_trace_class_remove_listener_status
;
551 Removes the destruction listener having the ID \bt_p{listener_id}
552 from the trace class \bt_p{trace_class}.
554 The destruction listener to remove from \bt_p{trace_class} was
555 previously added with bt_trace_class_add_destruction_listener().
557 You can call this function when \bt_p{trace_class} is
558 \ref api-fund-freezing "frozen".
560 @param[in] trace_class
561 Trace class from which to remove the destruction listener having
562 the ID \bt_p{listener_id}.
563 @param[in] listener_id
564 ID of the destruction listener to remove from \bt_p{trace_class}.
566 @retval #BT_TRACE_CLASS_REMOVE_LISTENER_STATUS_OK
568 @retval #BT_TRACE_CLASS_REMOVE_LISTENER_STATUS_MEMORY_ERROR
571 @bt_pre_not_null{trace_class}
573 \bt_p{listener_id} is the ID of an existing destruction listener
574 in \bt_p{trace_class}.
576 @sa bt_trace_class_add_destruction_listener() —
577 Adds a destruction listener to a trace class.
579 extern bt_trace_class_remove_listener_status
580 bt_trace_class_remove_destruction_listener(
581 const bt_trace_class
*trace_class
, bt_listener_id listener_id
)
587 @name Reference count
593 Increments the \ref api-fund-shared-object "reference count" of
594 the trace class \bt_p{trace_class}.
596 @param[in] trace_class
598 Trace class of which to increment the reference count.
603 @sa bt_trace_class_put_ref() —
604 Decrements the reference count of a trace class.
606 extern void bt_trace_class_get_ref(
607 const bt_trace_class
*trace_class
) __BT_NOEXCEPT
;
611 Decrements the \ref api-fund-shared-object "reference count" of
612 the trace class \bt_p{trace_class}.
614 @param[in] trace_class
616 Trace class of which to decrement the reference count.
621 @sa bt_trace_class_get_ref() —
622 Increments the reference count of a trace class.
624 extern void bt_trace_class_put_ref(
625 const bt_trace_class
*trace_class
) __BT_NOEXCEPT
;
629 Decrements the reference count of the trace class
630 \bt_p{_trace_class}, and then sets \bt_p{_trace_class} to \c NULL.
634 Trace class of which to decrement the reference count.
639 @bt_pre_assign_expr{_trace_class}
641 #define BT_TRACE_CLASS_PUT_REF_AND_RESET(_trace_class) \
643 bt_trace_class_put_ref(_trace_class); \
644 (_trace_class) = NULL; \
649 Decrements the reference count of the trace class \bt_p{_dst}, sets
650 \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL.
652 This macro effectively moves a trace class reference from the expression
653 \bt_p{_src} to the expression \bt_p{_dst}, putting the existing
654 \bt_p{_dst} reference.
658 Destination expression.
669 @bt_pre_assign_expr{_dst}
670 @bt_pre_assign_expr{_src}
672 #define BT_TRACE_CLASS_MOVE_REF(_dst, _src) \
674 bt_trace_class_put_ref(_dst); \
687 #endif /* BABELTRACE2_TRACE_IR_TRACE_CLASS_H */