include/babeltrace2: add `noexcept` specifier for C++ ≥ 11
[babeltrace.git] / include / babeltrace2 / trace-ir / trace-class.h
CommitLineData
862ca4ed 1/*
0235b0db 2 * SPDX-License-Identifier: MIT
862ca4ed 3 *
0235b0db 4 * Copyright (C) 2010-2019 EfficiOS Inc. and Linux Foundation
862ca4ed
PP
5 */
6
f38da6ca 7#ifndef BABELTRACE2_TRACE_IR_TRACE_CLASS_H
0235b0db
MJ
8#define BABELTRACE2_TRACE_IR_TRACE_CLASS_H
9
f38da6ca
SM
10/* IWYU pragma: private, include <babeltrace2/babeltrace.h> */
11
4fa90f32
PP
12#ifndef __BT_IN_BABELTRACE_H
13# error "Please include <babeltrace2/babeltrace.h> instead."
14#endif
15
d24d5663
PP
16#include <stdint.h>
17
3fadfbc0 18#include <babeltrace2/types.h>
862ca4ed 19
862ca4ed
PP
20#ifdef __cplusplus
21extern "C" {
22#endif
23
43c59509
PP
24/*!
25@defgroup api-tir-trace-cls Trace class
26@ingroup api-tir
862ca4ed 27
43c59509
PP
28@brief
29 Class of \bt_p_trace.
c6962c96 30
43c59509 31A <strong><em>trace class</em></strong> is the class of \bt_p_trace:
c6962c96 32
43c59509
PP
33@image html trace-structure.png
34
35In the illustration above, notice that a trace is an instance of a
36trace class.
37
38A trace class is a \ref api-tir "trace IR" metadata object.
39
40A trace class is a \ref api-fund-shared-object "shared object": get a
41new reference with bt_trace_class_get_ref() and put an existing
42reference with bt_trace_class_put_ref().
43
44Some library functions \ref api-fund-freezing "freeze" trace classes on
45success. The documentation of those functions indicate this
46postcondition. 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
53The type of a trace class is #bt_trace_class.
54
55A trace class contains \bt_p_stream_cls. All the stream classes of a
56given trace class have unique
57\ref api-tir-stream-cls-prop-id "numeric IDs". Get the number of stream
58classes in a trace class with bt_trace_class_get_stream_class_count().
59Borrow a specific stream class from a trace class with
60bt_trace_class_borrow_stream_class_by_index(),
61bt_trace_class_borrow_stream_class_by_index_const(),
62bt_trace_class_borrow_stream_class_by_id(), or
63bt_trace_class_borrow_stream_class_by_id_const().
64
65Set whether or not the \bt_p_stream_cls you create for a trace class get
66automatic numeric IDs with
67bt_trace_class_set_assigns_automatic_stream_class_id().
68
69Create a default trace class from a \bt_self_comp with
70bt_trace_class_create().
71
72Add to and remove a destruction listener from a trace class with
73bt_trace_class_add_destruction_listener() and
74bt_trace_class_remove_destruction_listener().
75
76<h1>Properties</h1>
77
78A 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
149On 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.
862ca4ed 165
43c59509
PP
166@returns
167 New trace class reference, or \c NULL on memory error.
168*/
4c81a2b7
PP
169extern bt_trace_class *bt_trace_class_create(bt_self_component *self_component)
170 __BT_NOEXCEPT;
43c59509
PP
171
172/*! @} */
173
174/*!
175@name Stream class access
176@{
177*/
178
179/*!
180@brief
181 Returns the number of \bt_p_stream_cls contained in the trace
182 class \bt_p{trace_class}.
183
184@param[in] trace_class
185 Trace class of which to get the number of contained stream classes.
186
187@returns
188 Number of contained stream classes in \bt_p{trace_class}.
189
190@bt_pre_not_null{trace_class}
191*/
192extern uint64_t bt_trace_class_get_stream_class_count(
4c81a2b7 193 const bt_trace_class *trace_class) __BT_NOEXCEPT;
43c59509
PP
194
195/*!
196@brief
197 Borrows the \bt_stream_cls at index \bt_p{index} from the
198 trace class \bt_p{trace_class}.
199
200@param[in] trace_class
201 Trace class from which to borrow the stream class at index
202 \bt_p{index}.
203@param[in] index
204 Index of the stream class to borrow from \bt_p{trace_class}.
205
206@returns
207 @parblock
208 \em Borrowed reference of the stream class of
209 \bt_p{trace_class} at index \bt_p{index}.
210
211 The returned pointer remains valid as long as \bt_p{trace_class}
212 exists.
213 @endparblock
214
215@bt_pre_not_null{trace_class}
216@pre
217 \bt_p{index} is less than the number of stream classes in
218 \bt_p{trace_class} (as returned by
219 bt_trace_class_get_stream_class_count()).
220
221@sa bt_trace_class_get_stream_class_count() &mdash;
222 Returns the number of stream classes contained in a trace class.
223@sa bt_trace_class_borrow_stream_class_by_index_const() &mdash;
224 \c const version of this function.
225*/
b19ff26f 226extern bt_stream_class *bt_trace_class_borrow_stream_class_by_index(
4c81a2b7 227 bt_trace_class *trace_class, uint64_t index) __BT_NOEXCEPT;
862ca4ed 228
43c59509
PP
229/*!
230@brief
231 Borrows the \bt_stream_cls at index \bt_p{index} from the
232 trace class \bt_p{trace_class} (\c const version).
233
234See bt_trace_class_borrow_stream_class_by_index().
235*/
236extern const bt_stream_class *
237bt_trace_class_borrow_stream_class_by_index_const(
4c81a2b7
PP
238 const bt_trace_class *trace_class,
239 uint64_t index) __BT_NOEXCEPT;
43c59509
PP
240
241/*!
242@brief
243 Borrows the \bt_stream_cls having the numeric ID \bt_p{id} from the
244 trace class \bt_p{trace_class}.
245
246If there's no stream class having the numeric ID \bt_p{id} in
247\bt_p{trace_class}, this function returns \c NULL.
248
249@param[in] trace_class
250 Trace class from which to borrow the stream class having the
251 numeric ID \bt_p{id}.
252@param[in] id
253 ID of the stream class to borrow from \bt_p{trace_class}.
254
255@returns
256 @parblock
257 \em Borrowed reference of the stream class of
258 \bt_p{trace_class} having the numeric ID \bt_p{id}, or \c NULL
259 if none.
260
261 The returned pointer remains valid as long as \bt_p{trace_class}
262 exists.
263 @endparblock
264
265@bt_pre_not_null{trace_class}
266
267@sa bt_trace_class_borrow_stream_class_by_id_const() &mdash;
268 \c const version of this function.
269*/
b19ff26f 270extern bt_stream_class *bt_trace_class_borrow_stream_class_by_id(
4c81a2b7 271 bt_trace_class *trace_class, uint64_t id) __BT_NOEXCEPT;
862ca4ed 272
43c59509
PP
273/*!
274@brief
275 Borrows the \bt_stream_cls having the numeric ID \bt_p{id} from the
276 trace class \bt_p{trace_class} (\c const version).
277
278See bt_trace_class_borrow_stream_class_by_id().
279*/
280extern const bt_stream_class *bt_trace_class_borrow_stream_class_by_id_const(
4c81a2b7 281 const bt_trace_class *trace_class, uint64_t id) __BT_NOEXCEPT;
43c59509
PP
282
283/*! @} */
284
285/*!
286@name Properties
287@{
288*/
289
290/*!
291@brief
292 Sets whether or not the trace class \bt_p{trace_class} automatically
293 assigns a numeric ID to a \bt_stream_cls you create and add to it.
294
295See the \ref api-tir-trace-cls-prop-auto-sc-id "assigns automatic stream class IDs?"
296property.
297
298@param[in] trace_class
299 Trace class of which to set whether or not it assigns automatic
300 stream class IDs.
301@param[in] assigns_automatic_stream_class_id
302 #BT_TRUE to make \bt_p{trace_class} assign automatic stream class
303 IDs.
304
305@bt_pre_not_null{trace_class}
306@bt_pre_hot{trace_class}
307
308@sa bt_trace_class_assigns_automatic_stream_class_id() &mdash;
309 Returns whether or not a trace class automatically assigns
310 stream class IDs.
311*/
312extern void bt_trace_class_set_assigns_automatic_stream_class_id(
313 bt_trace_class *trace_class,
4c81a2b7 314 bt_bool assigns_automatic_stream_class_id) __BT_NOEXCEPT;
43c59509
PP
315
316/*!
317@brief
318 Returns whether or not the trace class \bt_p{trace_class}
319 automatically assigns a numeric ID to a \bt_stream_cls you create
320 and add to it.
321
322See the \ref api-tir-trace-cls-prop-auto-sc-id "assigns automatic stream class IDs?"
323property.
324
325@param[in] trace_class
326 Trace class of which to get whether or not it assigns automatic
327 stream class IDs.
328
329@returns
330 #BT_TRUE if \bt_p{trace_class} automatically
331 assigns stream class IDs.
332
333@bt_pre_not_null{trace_class}
334
335@sa bt_trace_class_set_assigns_automatic_stream_class_id() &mdash;
336 Sets whether or not a trace class automatically assigns
337 stream class IDs.
338*/
339extern bt_bool bt_trace_class_assigns_automatic_stream_class_id(
4c81a2b7 340 const bt_trace_class *trace_class) __BT_NOEXCEPT;
43c59509
PP
341
342/*!
343@brief
344 Sets the user attributes of the trace class \bt_p{trace_class} to
345 \bt_p{user_attributes}.
346
347See the \ref api-tir-trace-cls-prop-user-attrs "user attributes"
348property.
349
350@note
351 When you create a default trace class with bt_trace_class_create()
352 or bt_trace_class_create_with_id(), the trace class's initial user
353 attributes is an empty \bt_map_val. Therefore you can borrow it with
354 bt_trace_class_borrow_user_attributes() and fill it directly
355 instead of setting a new one with this function.
356
357@param[in] trace_class
358 Trace class of which to set the user attributes to
359 \bt_p{user_attributes}.
360@param[in] user_attributes
361 New user attributes of \bt_p{trace_class}.
362
363@bt_pre_not_null{trace_class}
364@bt_pre_hot{trace_class}
365@bt_pre_not_null{user_attributes}
366@bt_pre_is_map_val{user_attributes}
367
368@sa bt_trace_class_borrow_user_attributes() &mdash;
369 Borrows the user attributes of a trace class.
370*/
371extern void bt_trace_class_set_user_attributes(
4c81a2b7
PP
372 bt_trace_class *trace_class,
373 const bt_value *user_attributes) __BT_NOEXCEPT;
43c59509
PP
374
375/*!
376@brief
377 Borrows the user attributes of the trace class \bt_p{trace_class}.
378
379See the \ref api-tir-trace-cls-prop-user-attrs "user attributes"
380property.
381
382@note
383 When you create a default trace class with bt_trace_class_create()
384 or bt_trace_class_create_with_id(), the trace class's initial user
385 attributes is an empty \bt_map_val.
386
387@param[in] trace_class
388 Trace class from which to borrow the user attributes.
389
390@returns
391 User attributes of \bt_p{trace_class} (a \bt_map_val).
392
393@bt_pre_not_null{trace_class}
394
395@sa bt_trace_class_set_user_attributes() &mdash;
396 Sets the user attributes of a trace class.
397@sa bt_trace_class_borrow_user_attributes_const() &mdash;
398 \c const version of this function.
399*/
400extern bt_value *bt_trace_class_borrow_user_attributes(
4c81a2b7 401 bt_trace_class *trace_class) __BT_NOEXCEPT;
43c59509
PP
402
403/*!
404@brief
405 Borrows the user attributes of the trace class \bt_p{trace_class}
406 (\c const version).
407
408See bt_trace_class_borrow_user_attributes().
409*/
410extern const bt_value *bt_trace_class_borrow_user_attributes_const(
4c81a2b7 411 const bt_trace_class *trace_class) __BT_NOEXCEPT;
43c59509
PP
412
413/*! @} */
414
415/*!
416@name Listeners
417@{
418*/
419
420/*!
421@brief
422 User function for bt_trace_class_add_destruction_listener().
423
424This is the user function type for a trace class destruction listener.
425
426@param[in] trace_class
427 Trace class being destroyed (\ref api-fund-freezing "frozen").
428@param[in] user_data
429 User data, as passed as the \bt_p{user_data} parameter of
430 bt_trace_class_add_destruction_listener().
431
432@bt_pre_not_null{trace_class}
433
434@post
435 The reference count of \bt_p{trace_class} is not changed.
436@bt_post_no_error
437
438@sa bt_trace_class_add_destruction_listener() &mdash;
439 Adds a destruction listener to a trace class.
440*/
441typedef void (* bt_trace_class_destruction_listener_func)(
442 const bt_trace_class *trace_class, void *user_data);
443
444/*!
445@brief
446 Status codes for bt_trace_class_add_destruction_listener().
447*/
448typedef enum bt_trace_class_add_listener_status {
449 /*!
450 @brief
451 Success.
452 */
453 BT_TRACE_CLASS_ADD_LISTENER_STATUS_OK = __BT_FUNC_STATUS_OK,
454
455 /*!
456 @brief
457 Out of memory.
458 */
459 BT_TRACE_CLASS_ADD_LISTENER_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
460} bt_trace_class_add_listener_status;
461
462/*!
463@brief
464 Adds a destruction listener having the function \bt_p{user_func}
465 to the trace class \bt_p{trace_class}.
466
467All the destruction listener user functions of a trace class are called
468when it's being destroyed.
469
470If \bt_p{listener_id} is not \c NULL, then this function, on success,
471sets \bt_p{*listener_id} to the ID of the added destruction listener
472within \bt_p{trace_class}. You can then use this ID to remove the
473added destruction listener with
474bt_trace_class_remove_destruction_listener().
475
476@param[in] trace_class
477 Trace class to add the destruction listener to.
478@param[in] user_func
479 User function of the destruction listener to add to
480 \bt_p{trace_class}.
481@param[in] user_data
482 User data to pass as the \bt_p{user_data} parameter of
483 \bt_p{user_func}.
484@param[out] listener_id
485 <strong>On success and if not \c NULL</strong>, \bt_p{*listener_id}
486 is the ID of the added destruction listener within
487 \bt_p{trace_class}.
488
489@retval #BT_TRACE_CLASS_ADD_LISTENER_STATUS_OK
490 Success.
491@retval #BT_TRACE_CLASS_ADD_LISTENER_STATUS_MEMORY_ERROR
492 Out of memory.
493
494@bt_pre_not_null{trace_class}
495@bt_pre_not_null{user_func}
496
497@sa bt_trace_class_remove_destruction_listener() &mdash;
498 Removes a destruction listener from a trace class.
499*/
500extern bt_trace_class_add_listener_status
501bt_trace_class_add_destruction_listener(
502 const bt_trace_class *trace_class,
503 bt_trace_class_destruction_listener_func user_func,
4c81a2b7 504 void *user_data, bt_listener_id *listener_id) __BT_NOEXCEPT;
43c59509
PP
505
506/*!
507@brief
508 Status codes for bt_trace_class_remove_destruction_listener().
509*/
510typedef enum bt_trace_class_remove_listener_status {
511 /*!
512 @brief
513 Success.
514 */
515 BT_TRACE_CLASS_REMOVE_LISTENER_STATUS_OK = __BT_FUNC_STATUS_OK,
516
517 /*!
518 @brief
519 Out of memory.
520 */
521 BT_TRACE_CLASS_REMOVE_LISTENER_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
522} bt_trace_class_remove_listener_status;
523
524/*!
525@brief
526 Removes the destruction listener having the ID \bt_p{listener_id}
527 from the trace class \bt_p{trace_class}.
528
529The destruction listener to remove from \bt_p{trace_class} was
530previously added with bt_trace_class_add_destruction_listener().
531
532You can call this function when \bt_p{trace_class} is
533\ref api-fund-freezing "frozen".
534
535@param[in] trace_class
536 Trace class from which to remove the destruction listener having
537 the ID \bt_p{listener_id}.
538@param[in] listener_id
539 ID of the destruction listener to remove from \bt_p{trace_class}­.
540
541@retval #BT_TRACE_CLASS_REMOVE_LISTENER_STATUS_OK
542 Success.
543@retval #BT_TRACE_CLASS_REMOVE_LISTENER_STATUS_MEMORY_ERROR
544 Out of memory.
545
546@bt_pre_not_null{trace_class}
547@pre
548 \bt_p{listener_id} is the ID of an existing destruction listener
549 in \bt_p{trace_class}.
550
551@sa bt_trace_class_add_destruction_listener() &mdash;
552 Adds a destruction listener to a trace class.
553*/
554extern bt_trace_class_remove_listener_status
555bt_trace_class_remove_destruction_listener(
4c81a2b7
PP
556 const bt_trace_class *trace_class, bt_listener_id listener_id)
557 __BT_NOEXCEPT;
43c59509
PP
558
559/*! @} */
560
561/*!
562@name Reference count
563@{
564*/
565
566/*!
567@brief
568 Increments the \ref api-fund-shared-object "reference count" of
569 the trace class \bt_p{trace_class}.
570
571@param[in] trace_class
572 @parblock
573 Trace class of which to increment the reference count.
574
575 Can be \c NULL.
576 @endparblock
577
578@sa bt_trace_class_put_ref() &mdash;
579 Decrements the reference count of a trace class.
580*/
4c81a2b7
PP
581extern void bt_trace_class_get_ref(
582 const bt_trace_class *trace_class) __BT_NOEXCEPT;
43c59509
PP
583
584/*!
585@brief
586 Decrements the \ref api-fund-shared-object "reference count" of
587 the trace class \bt_p{trace_class}.
588
589@param[in] trace_class
590 @parblock
591 Trace class of which to decrement the reference count.
592
593 Can be \c NULL.
594 @endparblock
595
596@sa bt_trace_class_get_ref() &mdash;
597 Increments the reference count of a trace class.
598*/
4c81a2b7
PP
599extern void bt_trace_class_put_ref(
600 const bt_trace_class *trace_class) __BT_NOEXCEPT;
43c59509
PP
601
602/*!
603@brief
604 Decrements the reference count of the trace class
605 \bt_p{_trace_class}, and then sets \bt_p{_trace_class} to \c NULL.
606
607@param _trace_class
608 @parblock
609 Trace class of which to decrement the reference count.
610
611 Can contain \c NULL.
612 @endparblock
613
614@bt_pre_assign_expr{_trace_class}
615*/
616#define BT_TRACE_CLASS_PUT_REF_AND_RESET(_trace_class) \
617 do { \
618 bt_trace_class_put_ref(_trace_class); \
619 (_trace_class) = NULL; \
620 } while (0)
621
622/*!
623@brief
624 Decrements the reference count of the trace class \bt_p{_dst}, sets
625 \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL.
626
627This macro effectively moves a trace class reference from the expression
628\bt_p{_src} to the expression \bt_p{_dst}, putting the existing
629\bt_p{_dst} reference.
630
631@param _dst
632 @parblock
633 Destination expression.
634
635 Can contain \c NULL.
636 @endparblock
637@param _src
638 @parblock
639 Source expression.
640
641 Can contain \c NULL.
642 @endparblock
643
644@bt_pre_assign_expr{_dst}
645@bt_pre_assign_expr{_src}
646*/
647#define BT_TRACE_CLASS_MOVE_REF(_dst, _src) \
648 do { \
649 bt_trace_class_put_ref(_dst); \
650 (_dst) = (_src); \
651 (_src) = NULL; \
652 } while (0)
653
654/*! @} */
655
656/*! @} */
657
862ca4ed
PP
658#ifdef __cplusplus
659}
660#endif
661
924dc299 662#endif /* BABELTRACE2_TRACE_IR_TRACE_CLASS_H */
This page took 0.114289 seconds and 4 git commands to generate.