579dd5fe3be52d26b18bbfe90363f5ad0a1597b3
[babeltrace.git] / include / babeltrace2 / trace-ir / trace-class.h
1 /*
2 * SPDX-License-Identifier: MIT
3 *
4 * Copyright (C) 2010-2019 EfficiOS Inc. and Linux Foundation
5 */
6
7 #ifndef BABELTRACE2_TRACE_IR_TRACE_CLASS_H
8 #define BABELTRACE2_TRACE_IR_TRACE_CLASS_H
9
10 /* IWYU pragma: private, include <babeltrace2/babeltrace.h> */
11
12 #ifndef __BT_IN_BABELTRACE_H
13 # error "Please include <babeltrace2/babeltrace.h> instead."
14 #endif
15
16 #include <stdint.h>
17
18 #include <babeltrace2/types.h>
19
20 #ifdef __cplusplus
21 extern "C" {
22 #endif
23
24 /*!
25 @defgroup api-tir-trace-cls Trace class
26 @ingroup api-tir
27
28 @brief
29 Class of \bt_p_trace.
30
31 A <strong><em>trace class</em></strong> is the class of \bt_p_trace:
32
33 @image html trace-structure.png
34
35 In the illustration above, notice that a trace is an instance of a
36 trace class.
37
38 A trace class is a \ref api-tir "trace IR" metadata object.
39
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().
43
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:
47
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().
52
53 The type of a trace class is #bt_trace_class.
54
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().
64
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().
68
69 Create a default trace class from a \bt_self_comp with
70 bt_trace_class_create().
71
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().
75
76 <h1>Properties</h1>
77
78 A trace class has the following properties:
79
80 <dl>
81 <dt>
82 \anchor api-tir-trace-cls-prop-auto-sc-id
83 Assigns automatic stream class IDs?
84 </dt>
85 <dd>
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"
88 automatically.
89
90 Depending on the value of this property, to create a stream class
91 and add it to the trace class:
92
93 <dl>
94 <dt>#BT_TRUE</dt>
95 <dd>
96 Use bt_stream_class_create().
97 </dd>
98
99 <dt>#BT_FALSE</dt>
100 <dd>
101 Use bt_stream_class_create_with_id().
102 </dd>
103 </dl>
104
105 Use bt_trace_class_set_assigns_automatic_stream_class_id()
106 and bt_trace_class_assigns_automatic_stream_class_id().
107 </dd>
108
109 <dt>
110 \anchor api-tir-trace-cls-prop-user-attrs
111 \bt_dt_opt User attributes
112 </dt>
113 <dd>
114 User attributes of the trace class.
115
116 User attributes are custom attributes attached to a trace class.
117
118 Use bt_trace_class_set_user_attributes(),
119 bt_trace_class_borrow_user_attributes(), and
120 bt_trace_class_borrow_user_attributes_const().
121 </dd>
122 </dl>
123 */
124
125 /*! @{ */
126
127 /*!
128 @name Type
129 @{
130
131 @typedef struct bt_trace_class bt_trace_class;
132
133 @brief
134 Trace class.
135
136 @}
137 */
138
139 /*!
140 @name Creation
141 @{
142 */
143
144 /*!
145 @brief
146 Creates a default trace class from the \bt_self_comp
147 \bt_p{self_component}.
148
149 On success, the returned trace class has the following property values:
150
151 <table>
152 <tr>
153 <th>Property
154 <th>Value
155 <tr>
156 <td>\ref api-tir-trace-cls-prop-auto-sc-id "Assigns automatic stream class IDs?"
157 <td>Yes
158 <tr>
159 <td>\ref api-tir-trace-cls-prop-user-attrs "User attributes"
160 <td>Empty \bt_map_val
161 </table>
162
163 @param[in] self_component
164 Self component from which to create the default trace class.
165
166 @returns
167 New trace class reference, or \c NULL on memory error.
168 */
169 extern bt_trace_class *bt_trace_class_create(bt_self_component *self_component);
170
171 /*! @} */
172
173 /*!
174 @name Stream class access
175 @{
176 */
177
178 /*!
179 @brief
180 Returns the number of \bt_p_stream_cls contained in the trace
181 class \bt_p{trace_class}.
182
183 @param[in] trace_class
184 Trace class of which to get the number of contained stream classes.
185
186 @returns
187 Number of contained stream classes in \bt_p{trace_class}.
188
189 @bt_pre_not_null{trace_class}
190 */
191 extern uint64_t bt_trace_class_get_stream_class_count(
192 const bt_trace_class *trace_class);
193
194 /*!
195 @brief
196 Borrows the \bt_stream_cls at index \bt_p{index} from the
197 trace class \bt_p{trace_class}.
198
199 @param[in] trace_class
200 Trace class from which to borrow the stream class at index
201 \bt_p{index}.
202 @param[in] index
203 Index of the stream class to borrow from \bt_p{trace_class}.
204
205 @returns
206 @parblock
207 \em Borrowed reference of the stream class of
208 \bt_p{trace_class} at index \bt_p{index}.
209
210 The returned pointer remains valid as long as \bt_p{trace_class}
211 exists.
212 @endparblock
213
214 @bt_pre_not_null{trace_class}
215 @pre
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()).
219
220 @sa bt_trace_class_get_stream_class_count() &mdash;
221 Returns the number of stream classes contained in a trace class.
222 @sa bt_trace_class_borrow_stream_class_by_index_const() &mdash;
223 \c const version of this function.
224 */
225 extern bt_stream_class *bt_trace_class_borrow_stream_class_by_index(
226 bt_trace_class *trace_class, uint64_t index);
227
228 /*!
229 @brief
230 Borrows the \bt_stream_cls at index \bt_p{index} from the
231 trace class \bt_p{trace_class} (\c const version).
232
233 See bt_trace_class_borrow_stream_class_by_index().
234 */
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);
238
239 /*!
240 @brief
241 Borrows the \bt_stream_cls having the numeric ID \bt_p{id} from the
242 trace class \bt_p{trace_class}.
243
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.
246
247 @param[in] trace_class
248 Trace class from which to borrow the stream class having the
249 numeric ID \bt_p{id}.
250 @param[in] id
251 ID of the stream class to borrow from \bt_p{trace_class}.
252
253 @returns
254 @parblock
255 \em Borrowed reference of the stream class of
256 \bt_p{trace_class} having the numeric ID \bt_p{id}, or \c NULL
257 if none.
258
259 The returned pointer remains valid as long as \bt_p{trace_class}
260 exists.
261 @endparblock
262
263 @bt_pre_not_null{trace_class}
264
265 @sa bt_trace_class_borrow_stream_class_by_id_const() &mdash;
266 \c const version of this function.
267 */
268 extern bt_stream_class *bt_trace_class_borrow_stream_class_by_id(
269 bt_trace_class *trace_class, uint64_t id);
270
271 /*!
272 @brief
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).
275
276 See bt_trace_class_borrow_stream_class_by_id().
277 */
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);
280
281 /*! @} */
282
283 /*!
284 @name Properties
285 @{
286 */
287
288 /*!
289 @brief
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.
292
293 See the \ref api-tir-trace-cls-prop-auto-sc-id "assigns automatic stream class IDs?"
294 property.
295
296 @param[in] trace_class
297 Trace class of which to set whether or not it assigns automatic
298 stream class IDs.
299 @param[in] assigns_automatic_stream_class_id
300 #BT_TRUE to make \bt_p{trace_class} assign automatic stream class
301 IDs.
302
303 @bt_pre_not_null{trace_class}
304 @bt_pre_hot{trace_class}
305
306 @sa bt_trace_class_assigns_automatic_stream_class_id() &mdash;
307 Returns whether or not a trace class automatically assigns
308 stream class IDs.
309 */
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);
313
314 /*!
315 @brief
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
318 and add to it.
319
320 See the \ref api-tir-trace-cls-prop-auto-sc-id "assigns automatic stream class IDs?"
321 property.
322
323 @param[in] trace_class
324 Trace class of which to get whether or not it assigns automatic
325 stream class IDs.
326
327 @returns
328 #BT_TRUE if \bt_p{trace_class} automatically
329 assigns stream class IDs.
330
331 @bt_pre_not_null{trace_class}
332
333 @sa bt_trace_class_set_assigns_automatic_stream_class_id() &mdash;
334 Sets whether or not a trace class automatically assigns
335 stream class IDs.
336 */
337 extern bt_bool bt_trace_class_assigns_automatic_stream_class_id(
338 const bt_trace_class *trace_class);
339
340 /*!
341 @brief
342 Sets the user attributes of the trace class \bt_p{trace_class} to
343 \bt_p{user_attributes}.
344
345 See the \ref api-tir-trace-cls-prop-user-attrs "user attributes"
346 property.
347
348 @note
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.
354
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}.
360
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}
365
366 @sa bt_trace_class_borrow_user_attributes() &mdash;
367 Borrows the user attributes of a trace class.
368 */
369 extern void bt_trace_class_set_user_attributes(
370 bt_trace_class *trace_class, const bt_value *user_attributes);
371
372 /*!
373 @brief
374 Borrows the user attributes of the trace class \bt_p{trace_class}.
375
376 See the \ref api-tir-trace-cls-prop-user-attrs "user attributes"
377 property.
378
379 @note
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.
383
384 @param[in] trace_class
385 Trace class from which to borrow the user attributes.
386
387 @returns
388 User attributes of \bt_p{trace_class} (a \bt_map_val).
389
390 @bt_pre_not_null{trace_class}
391
392 @sa bt_trace_class_set_user_attributes() &mdash;
393 Sets the user attributes of a trace class.
394 @sa bt_trace_class_borrow_user_attributes_const() &mdash;
395 \c const version of this function.
396 */
397 extern bt_value *bt_trace_class_borrow_user_attributes(
398 bt_trace_class *trace_class);
399
400 /*!
401 @brief
402 Borrows the user attributes of the trace class \bt_p{trace_class}
403 (\c const version).
404
405 See bt_trace_class_borrow_user_attributes().
406 */
407 extern const bt_value *bt_trace_class_borrow_user_attributes_const(
408 const bt_trace_class *trace_class);
409
410 /*! @} */
411
412 /*!
413 @name Listeners
414 @{
415 */
416
417 /*!
418 @brief
419 User function for bt_trace_class_add_destruction_listener().
420
421 This is the user function type for a trace class destruction listener.
422
423 @param[in] trace_class
424 Trace class being destroyed (\ref api-fund-freezing "frozen").
425 @param[in] user_data
426 User data, as passed as the \bt_p{user_data} parameter of
427 bt_trace_class_add_destruction_listener().
428
429 @bt_pre_not_null{trace_class}
430
431 @post
432 The reference count of \bt_p{trace_class} is not changed.
433 @bt_post_no_error
434
435 @sa bt_trace_class_add_destruction_listener() &mdash;
436 Adds a destruction listener to a trace class.
437 */
438 typedef void (* bt_trace_class_destruction_listener_func)(
439 const bt_trace_class *trace_class, void *user_data);
440
441 /*!
442 @brief
443 Status codes for bt_trace_class_add_destruction_listener().
444 */
445 typedef enum bt_trace_class_add_listener_status {
446 /*!
447 @brief
448 Success.
449 */
450 BT_TRACE_CLASS_ADD_LISTENER_STATUS_OK = __BT_FUNC_STATUS_OK,
451
452 /*!
453 @brief
454 Out of memory.
455 */
456 BT_TRACE_CLASS_ADD_LISTENER_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
457 } bt_trace_class_add_listener_status;
458
459 /*!
460 @brief
461 Adds a destruction listener having the function \bt_p{user_func}
462 to the trace class \bt_p{trace_class}.
463
464 All the destruction listener user functions of a trace class are called
465 when it's being destroyed.
466
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().
472
473 @param[in] trace_class
474 Trace class to add the destruction listener to.
475 @param[in] user_func
476 User function of the destruction listener to add to
477 \bt_p{trace_class}.
478 @param[in] user_data
479 User data to pass as the \bt_p{user_data} parameter of
480 \bt_p{user_func}.
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
484 \bt_p{trace_class}.
485
486 @retval #BT_TRACE_CLASS_ADD_LISTENER_STATUS_OK
487 Success.
488 @retval #BT_TRACE_CLASS_ADD_LISTENER_STATUS_MEMORY_ERROR
489 Out of memory.
490
491 @bt_pre_not_null{trace_class}
492 @bt_pre_not_null{user_func}
493
494 @sa bt_trace_class_remove_destruction_listener() &mdash;
495 Removes a destruction listener from a trace class.
496 */
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);
502
503 /*!
504 @brief
505 Status codes for bt_trace_class_remove_destruction_listener().
506 */
507 typedef enum bt_trace_class_remove_listener_status {
508 /*!
509 @brief
510 Success.
511 */
512 BT_TRACE_CLASS_REMOVE_LISTENER_STATUS_OK = __BT_FUNC_STATUS_OK,
513
514 /*!
515 @brief
516 Out of memory.
517 */
518 BT_TRACE_CLASS_REMOVE_LISTENER_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
519 } bt_trace_class_remove_listener_status;
520
521 /*!
522 @brief
523 Removes the destruction listener having the ID \bt_p{listener_id}
524 from the trace class \bt_p{trace_class}.
525
526 The destruction listener to remove from \bt_p{trace_class} was
527 previously added with bt_trace_class_add_destruction_listener().
528
529 You can call this function when \bt_p{trace_class} is
530 \ref api-fund-freezing "frozen".
531
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}­.
537
538 @retval #BT_TRACE_CLASS_REMOVE_LISTENER_STATUS_OK
539 Success.
540 @retval #BT_TRACE_CLASS_REMOVE_LISTENER_STATUS_MEMORY_ERROR
541 Out of memory.
542
543 @bt_pre_not_null{trace_class}
544 @pre
545 \bt_p{listener_id} is the ID of an existing destruction listener
546 in \bt_p{trace_class}.
547
548 @sa bt_trace_class_add_destruction_listener() &mdash;
549 Adds a destruction listener to a trace class.
550 */
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);
554
555 /*! @} */
556
557 /*!
558 @name Reference count
559 @{
560 */
561
562 /*!
563 @brief
564 Increments the \ref api-fund-shared-object "reference count" of
565 the trace class \bt_p{trace_class}.
566
567 @param[in] trace_class
568 @parblock
569 Trace class of which to increment the reference count.
570
571 Can be \c NULL.
572 @endparblock
573
574 @sa bt_trace_class_put_ref() &mdash;
575 Decrements the reference count of a trace class.
576 */
577 extern void bt_trace_class_get_ref(const bt_trace_class *trace_class);
578
579 /*!
580 @brief
581 Decrements the \ref api-fund-shared-object "reference count" of
582 the trace class \bt_p{trace_class}.
583
584 @param[in] trace_class
585 @parblock
586 Trace class of which to decrement the reference count.
587
588 Can be \c NULL.
589 @endparblock
590
591 @sa bt_trace_class_get_ref() &mdash;
592 Increments the reference count of a trace class.
593 */
594 extern void bt_trace_class_put_ref(const bt_trace_class *trace_class);
595
596 /*!
597 @brief
598 Decrements the reference count of the trace class
599 \bt_p{_trace_class}, and then sets \bt_p{_trace_class} to \c NULL.
600
601 @param _trace_class
602 @parblock
603 Trace class of which to decrement the reference count.
604
605 Can contain \c NULL.
606 @endparblock
607
608 @bt_pre_assign_expr{_trace_class}
609 */
610 #define BT_TRACE_CLASS_PUT_REF_AND_RESET(_trace_class) \
611 do { \
612 bt_trace_class_put_ref(_trace_class); \
613 (_trace_class) = NULL; \
614 } while (0)
615
616 /*!
617 @brief
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.
620
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.
624
625 @param _dst
626 @parblock
627 Destination expression.
628
629 Can contain \c NULL.
630 @endparblock
631 @param _src
632 @parblock
633 Source expression.
634
635 Can contain \c NULL.
636 @endparblock
637
638 @bt_pre_assign_expr{_dst}
639 @bt_pre_assign_expr{_src}
640 */
641 #define BT_TRACE_CLASS_MOVE_REF(_dst, _src) \
642 do { \
643 bt_trace_class_put_ref(_dst); \
644 (_dst) = (_src); \
645 (_src) = NULL; \
646 } while (0)
647
648 /*! @} */
649
650 /*! @} */
651
652 #ifdef __cplusplus
653 }
654 #endif
655
656 #endif /* BABELTRACE2_TRACE_IR_TRACE_CLASS_H */
This page took 0.043519 seconds and 3 git commands to generate.