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 #ifndef __BT_IN_BABELTRACE_H
11 # error "Please include <babeltrace2/babeltrace.h> instead."
16 #include <babeltrace2/types.h>
23 @defgroup api-tir-trace-cls Trace class
29 A <strong><em>trace class</em></strong> is the class of \bt_p_trace:
31 @image html trace-structure.png
33 In the illustration above, notice that a trace is an instance of a
36 A trace class is a \ref api-tir "trace IR" metadata object.
38 A trace class is a \ref api-fund-shared-object "shared object": get a
39 new reference with bt_trace_class_get_ref() and put an existing
40 reference with bt_trace_class_put_ref().
42 Some library functions \ref api-fund-freezing "freeze" trace classes on
43 success. The documentation of those functions indicate this
44 postcondition. With a frozen trace class, you can still:
46 - Create and add a \bt_p_stream_cls to it with
47 bt_stream_class_create() or bt_stream_class_create_with_id().
48 - Add a destruction listener to it with
49 bt_trace_class_add_destruction_listener().
51 The type of a trace class is #bt_trace_class.
53 A trace class contains \bt_p_stream_cls. All the stream classes of a
54 given trace class have unique
55 \ref api-tir-stream-cls-prop-id "numeric IDs". Get the number of stream
56 classes in a trace class with bt_trace_class_get_stream_class_count().
57 Borrow a specific stream class from a trace class with
58 bt_trace_class_borrow_stream_class_by_index(),
59 bt_trace_class_borrow_stream_class_by_index_const(),
60 bt_trace_class_borrow_stream_class_by_id(), or
61 bt_trace_class_borrow_stream_class_by_id_const().
63 Set whether or not the \bt_p_stream_cls you create for a trace class get
64 automatic numeric IDs with
65 bt_trace_class_set_assigns_automatic_stream_class_id().
67 Create a default trace class from a \bt_self_comp with
68 bt_trace_class_create().
70 Add to and remove a destruction listener from a trace class with
71 bt_trace_class_add_destruction_listener() and
72 bt_trace_class_remove_destruction_listener().
76 A trace class has the following properties:
80 \anchor api-tir-trace-cls-prop-auto-sc-id
81 Assigns automatic stream class IDs?
84 Whether or not the stream classes you create and add to the trace
85 class get \ref api-tir-stream-cls-prop-id "numeric IDs"
88 Depending on the value of this property, to create a stream class
89 and add it to the trace class:
94 Use bt_stream_class_create().
99 Use bt_stream_class_create_with_id().
103 Use bt_trace_class_set_assigns_automatic_stream_class_id()
104 and bt_trace_class_assigns_automatic_stream_class_id().
108 \anchor api-tir-trace-cls-prop-user-attrs
109 \bt_dt_opt User attributes
112 User attributes of the trace class.
114 User attributes are custom attributes attached to a trace class.
116 Use bt_trace_class_set_user_attributes(),
117 bt_trace_class_borrow_user_attributes(), and
118 bt_trace_class_borrow_user_attributes_const().
129 @typedef struct bt_trace_class bt_trace_class;
144 Creates a default trace class from the \bt_self_comp
145 \bt_p{self_component}.
147 On success, the returned trace class has the following property values:
154 <td>\ref api-tir-trace-cls-prop-auto-sc-id "Assigns automatic stream class IDs?"
157 <td>\ref api-tir-trace-cls-prop-user-attrs "User attributes"
158 <td>Empty \bt_map_val
161 @param[in] self_component
162 Self component from which to create the default trace class.
165 New trace class reference, or \c NULL on memory error.
167 extern bt_trace_class
*bt_trace_class_create(bt_self_component
*self_component
);
172 @name Stream class access
178 Returns the number of \bt_p_stream_cls contained in the trace
179 class \bt_p{trace_class}.
181 @param[in] trace_class
182 Trace class of which to get the number of contained stream classes.
185 Number of contained stream classes in \bt_p{trace_class}.
187 @bt_pre_not_null{trace_class}
189 extern uint64_t bt_trace_class_get_stream_class_count(
190 const bt_trace_class
*trace_class
);
194 Borrows the \bt_stream_cls at index \bt_p{index} from the
195 trace class \bt_p{trace_class}.
197 @param[in] trace_class
198 Trace class from which to borrow the stream class at index
201 Index of the stream class to borrow from \bt_p{trace_class}.
205 \em Borrowed reference of the stream class of
206 \bt_p{trace_class} at index \bt_p{index}.
208 The returned pointer remains valid as long as \bt_p{trace_class}
212 @bt_pre_not_null{trace_class}
214 \bt_p{index} is less than the number of stream classes in
215 \bt_p{trace_class} (as returned by
216 bt_trace_class_get_stream_class_count()).
218 @sa bt_trace_class_get_stream_class_count() —
219 Returns the number of stream classes contained in a trace class.
220 @sa bt_trace_class_borrow_stream_class_by_index_const() —
221 \c const version of this function.
223 extern bt_stream_class
*bt_trace_class_borrow_stream_class_by_index(
224 bt_trace_class
*trace_class
, uint64_t index
);
228 Borrows the \bt_stream_cls at index \bt_p{index} from the
229 trace class \bt_p{trace_class} (\c const version).
231 See bt_trace_class_borrow_stream_class_by_index().
233 extern const bt_stream_class
*
234 bt_trace_class_borrow_stream_class_by_index_const(
235 const bt_trace_class
*trace_class
, uint64_t index
);
239 Borrows the \bt_stream_cls having the numeric ID \bt_p{id} from the
240 trace class \bt_p{trace_class}.
242 If there's no stream class having the numeric ID \bt_p{id} in
243 \bt_p{trace_class}, this function returns \c NULL.
245 @param[in] trace_class
246 Trace class from which to borrow the stream class having the
247 numeric ID \bt_p{id}.
249 ID of the stream class to borrow from \bt_p{trace_class}.
253 \em Borrowed reference of the stream class of
254 \bt_p{trace_class} having the numeric ID \bt_p{id}, or \c NULL
257 The returned pointer remains valid as long as \bt_p{trace_class}
261 @bt_pre_not_null{trace_class}
263 @sa bt_trace_class_borrow_stream_class_by_id_const() —
264 \c const version of this function.
266 extern bt_stream_class
*bt_trace_class_borrow_stream_class_by_id(
267 bt_trace_class
*trace_class
, uint64_t id
);
271 Borrows the \bt_stream_cls having the numeric ID \bt_p{id} from the
272 trace class \bt_p{trace_class} (\c const version).
274 See bt_trace_class_borrow_stream_class_by_id().
276 extern const bt_stream_class
*bt_trace_class_borrow_stream_class_by_id_const(
277 const bt_trace_class
*trace_class
, uint64_t id
);
288 Sets whether or not the trace class \bt_p{trace_class} automatically
289 assigns a numeric ID to a \bt_stream_cls you create and add to it.
291 See the \ref api-tir-trace-cls-prop-auto-sc-id "assigns automatic stream class IDs?"
294 @param[in] trace_class
295 Trace class of which to set whether or not it assigns automatic
297 @param[in] assigns_automatic_stream_class_id
298 #BT_TRUE to make \bt_p{trace_class} assign automatic stream class
301 @bt_pre_not_null{trace_class}
302 @bt_pre_hot{trace_class}
304 @sa bt_trace_class_assigns_automatic_stream_class_id() —
305 Returns whether or not a trace class automatically assigns
308 extern void bt_trace_class_set_assigns_automatic_stream_class_id(
309 bt_trace_class
*trace_class
,
310 bt_bool assigns_automatic_stream_class_id
);
314 Returns whether or not the trace class \bt_p{trace_class}
315 automatically assigns a numeric ID to a \bt_stream_cls you create
318 See the \ref api-tir-trace-cls-prop-auto-sc-id "assigns automatic stream class IDs?"
321 @param[in] trace_class
322 Trace class of which to get whether or not it assigns automatic
326 #BT_TRUE if \bt_p{trace_class} automatically
327 assigns stream class IDs.
329 @bt_pre_not_null{trace_class}
331 @sa bt_trace_class_set_assigns_automatic_stream_class_id() —
332 Sets whether or not a trace class automatically assigns
335 extern bt_bool
bt_trace_class_assigns_automatic_stream_class_id(
336 const bt_trace_class
*trace_class
);
340 Sets the user attributes of the trace class \bt_p{trace_class} to
341 \bt_p{user_attributes}.
343 See the \ref api-tir-trace-cls-prop-user-attrs "user attributes"
347 When you create a default trace class with bt_trace_class_create()
348 or bt_trace_class_create_with_id(), the trace class's initial user
349 attributes is an empty \bt_map_val. Therefore you can borrow it with
350 bt_trace_class_borrow_user_attributes() and fill it directly
351 instead of setting a new one with this function.
353 @param[in] trace_class
354 Trace class of which to set the user attributes to
355 \bt_p{user_attributes}.
356 @param[in] user_attributes
357 New user attributes of \bt_p{trace_class}.
359 @bt_pre_not_null{trace_class}
360 @bt_pre_hot{trace_class}
361 @bt_pre_not_null{user_attributes}
362 @bt_pre_is_map_val{user_attributes}
364 @sa bt_trace_class_borrow_user_attributes() —
365 Borrows the user attributes of a trace class.
367 extern void bt_trace_class_set_user_attributes(
368 bt_trace_class
*trace_class
, const bt_value
*user_attributes
);
372 Borrows the user attributes of the trace class \bt_p{trace_class}.
374 See the \ref api-tir-trace-cls-prop-user-attrs "user attributes"
378 When you create a default trace class with bt_trace_class_create()
379 or bt_trace_class_create_with_id(), the trace class's initial user
380 attributes is an empty \bt_map_val.
382 @param[in] trace_class
383 Trace class from which to borrow the user attributes.
386 User attributes of \bt_p{trace_class} (a \bt_map_val).
388 @bt_pre_not_null{trace_class}
390 @sa bt_trace_class_set_user_attributes() —
391 Sets the user attributes of a trace class.
392 @sa bt_trace_class_borrow_user_attributes_const() —
393 \c const version of this function.
395 extern bt_value
*bt_trace_class_borrow_user_attributes(
396 bt_trace_class
*trace_class
);
400 Borrows the user attributes of the trace class \bt_p{trace_class}
403 See bt_trace_class_borrow_user_attributes().
405 extern const bt_value
*bt_trace_class_borrow_user_attributes_const(
406 const bt_trace_class
*trace_class
);
417 User function for bt_trace_class_add_destruction_listener().
419 This is the user function type for a trace class destruction listener.
421 @param[in] trace_class
422 Trace class being destroyed (\ref api-fund-freezing "frozen").
424 User data, as passed as the \bt_p{user_data} parameter of
425 bt_trace_class_add_destruction_listener().
427 @bt_pre_not_null{trace_class}
430 The reference count of \bt_p{trace_class} is not changed.
433 @sa bt_trace_class_add_destruction_listener() —
434 Adds a destruction listener to a trace class.
436 typedef void (* bt_trace_class_destruction_listener_func
)(
437 const bt_trace_class
*trace_class
, void *user_data
);
441 Status codes for bt_trace_class_add_destruction_listener().
443 typedef enum bt_trace_class_add_listener_status
{
448 BT_TRACE_CLASS_ADD_LISTENER_STATUS_OK
= __BT_FUNC_STATUS_OK
,
454 BT_TRACE_CLASS_ADD_LISTENER_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
455 } bt_trace_class_add_listener_status
;
459 Adds a destruction listener having the function \bt_p{user_func}
460 to the trace class \bt_p{trace_class}.
462 All the destruction listener user functions of a trace class are called
463 when it's being destroyed.
465 If \bt_p{listener_id} is not \c NULL, then this function, on success,
466 sets \bt_p{*listener_id} to the ID of the added destruction listener
467 within \bt_p{trace_class}. You can then use this ID to remove the
468 added destruction listener with
469 bt_trace_class_remove_destruction_listener().
471 @param[in] trace_class
472 Trace class to add the destruction listener to.
474 User function of the destruction listener to add to
477 User data to pass as the \bt_p{user_data} parameter of
479 @param[out] listener_id
480 <strong>On success and if not \c NULL</strong>, \bt_p{*listener_id}
481 is the ID of the added destruction listener within
484 @retval #BT_TRACE_CLASS_ADD_LISTENER_STATUS_OK
486 @retval #BT_TRACE_CLASS_ADD_LISTENER_STATUS_MEMORY_ERROR
489 @bt_pre_not_null{trace_class}
490 @bt_pre_not_null{user_func}
492 @sa bt_trace_class_remove_destruction_listener() —
493 Removes a destruction listener from a trace class.
495 extern bt_trace_class_add_listener_status
496 bt_trace_class_add_destruction_listener(
497 const bt_trace_class
*trace_class
,
498 bt_trace_class_destruction_listener_func user_func
,
499 void *user_data
, bt_listener_id
*listener_id
);
503 Status codes for bt_trace_class_remove_destruction_listener().
505 typedef enum bt_trace_class_remove_listener_status
{
510 BT_TRACE_CLASS_REMOVE_LISTENER_STATUS_OK
= __BT_FUNC_STATUS_OK
,
516 BT_TRACE_CLASS_REMOVE_LISTENER_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
517 } bt_trace_class_remove_listener_status
;
521 Removes the destruction listener having the ID \bt_p{listener_id}
522 from the trace class \bt_p{trace_class}.
524 The destruction listener to remove from \bt_p{trace_class} was
525 previously added with bt_trace_class_add_destruction_listener().
527 You can call this function when \bt_p{trace_class} is
528 \ref api-fund-freezing "frozen".
530 @param[in] trace_class
531 Trace class from which to remove the destruction listener having
532 the ID \bt_p{listener_id}.
533 @param[in] listener_id
534 ID of the destruction listener to remove from \bt_p{trace_class}.
536 @retval #BT_TRACE_CLASS_REMOVE_LISTENER_STATUS_OK
538 @retval #BT_TRACE_CLASS_REMOVE_LISTENER_STATUS_MEMORY_ERROR
541 @bt_pre_not_null{trace_class}
543 \bt_p{listener_id} is the ID of an existing destruction listener
544 in \bt_p{trace_class}.
546 @sa bt_trace_class_add_destruction_listener() —
547 Adds a destruction listener to a trace class.
549 extern bt_trace_class_remove_listener_status
550 bt_trace_class_remove_destruction_listener(
551 const bt_trace_class
*trace_class
, bt_listener_id listener_id
);
556 @name Reference count
562 Increments the \ref api-fund-shared-object "reference count" of
563 the trace class \bt_p{trace_class}.
565 @param[in] trace_class
567 Trace class of which to increment the reference count.
572 @sa bt_trace_class_put_ref() —
573 Decrements the reference count of a trace class.
575 extern void bt_trace_class_get_ref(const bt_trace_class
*trace_class
);
579 Decrements the \ref api-fund-shared-object "reference count" of
580 the trace class \bt_p{trace_class}.
582 @param[in] trace_class
584 Trace class of which to decrement the reference count.
589 @sa bt_trace_class_get_ref() —
590 Increments the reference count of a trace class.
592 extern void bt_trace_class_put_ref(const bt_trace_class
*trace_class
);
596 Decrements the reference count of the trace class
597 \bt_p{_trace_class}, and then sets \bt_p{_trace_class} to \c NULL.
601 Trace class of which to decrement the reference count.
606 @bt_pre_assign_expr{_trace_class}
608 #define BT_TRACE_CLASS_PUT_REF_AND_RESET(_trace_class) \
610 bt_trace_class_put_ref(_trace_class); \
611 (_trace_class) = NULL; \
616 Decrements the reference count of the trace class \bt_p{_dst}, sets
617 \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL.
619 This macro effectively moves a trace class reference from the expression
620 \bt_p{_src} to the expression \bt_p{_dst}, putting the existing
621 \bt_p{_dst} reference.
625 Destination expression.
636 @bt_pre_assign_expr{_dst}
637 @bt_pre_assign_expr{_src}
639 #define BT_TRACE_CLASS_MOVE_REF(_dst, _src) \
641 bt_trace_class_put_ref(_dst); \
654 #endif /* BABELTRACE2_TRACE_IR_TRACE_CLASS_H */