include/babeltrace2: add `noexcept` specifier for C++ ≥ 11
[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 __BT_NOEXCEPT;
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 */
192 extern uint64_t bt_trace_class_get_stream_class_count(
193 const bt_trace_class *trace_class) __BT_NOEXCEPT;
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 */
226 extern bt_stream_class *bt_trace_class_borrow_stream_class_by_index(
227 bt_trace_class *trace_class, uint64_t index) __BT_NOEXCEPT;
228
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
234 See bt_trace_class_borrow_stream_class_by_index().
235 */
236 extern const bt_stream_class *
237 bt_trace_class_borrow_stream_class_by_index_const(
238 const bt_trace_class *trace_class,
239 uint64_t index) __BT_NOEXCEPT;
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
246 If 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 */
270 extern bt_stream_class *bt_trace_class_borrow_stream_class_by_id(
271 bt_trace_class *trace_class, uint64_t id) __BT_NOEXCEPT;
272
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
278 See bt_trace_class_borrow_stream_class_by_id().
279 */
280 extern const bt_stream_class *bt_trace_class_borrow_stream_class_by_id_const(
281 const bt_trace_class *trace_class, uint64_t id) __BT_NOEXCEPT;
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
295 See the \ref api-tir-trace-cls-prop-auto-sc-id "assigns automatic stream class IDs?"
296 property.
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 */
312 extern void bt_trace_class_set_assigns_automatic_stream_class_id(
313 bt_trace_class *trace_class,
314 bt_bool assigns_automatic_stream_class_id) __BT_NOEXCEPT;
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
322 See the \ref api-tir-trace-cls-prop-auto-sc-id "assigns automatic stream class IDs?"
323 property.
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 */
339 extern bt_bool bt_trace_class_assigns_automatic_stream_class_id(
340 const bt_trace_class *trace_class) __BT_NOEXCEPT;
341
342 /*!
343 @brief
344 Sets the user attributes of the trace class \bt_p{trace_class} to
345 \bt_p{user_attributes}.
346
347 See the \ref api-tir-trace-cls-prop-user-attrs "user attributes"
348 property.
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 */
371 extern void bt_trace_class_set_user_attributes(
372 bt_trace_class *trace_class,
373 const bt_value *user_attributes) __BT_NOEXCEPT;
374
375 /*!
376 @brief
377 Borrows the user attributes of the trace class \bt_p{trace_class}.
378
379 See the \ref api-tir-trace-cls-prop-user-attrs "user attributes"
380 property.
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 */
400 extern bt_value *bt_trace_class_borrow_user_attributes(
401 bt_trace_class *trace_class) __BT_NOEXCEPT;
402
403 /*!
404 @brief
405 Borrows the user attributes of the trace class \bt_p{trace_class}
406 (\c const version).
407
408 See bt_trace_class_borrow_user_attributes().
409 */
410 extern const bt_value *bt_trace_class_borrow_user_attributes_const(
411 const bt_trace_class *trace_class) __BT_NOEXCEPT;
412
413 /*! @} */
414
415 /*!
416 @name Listeners
417 @{
418 */
419
420 /*!
421 @brief
422 User function for bt_trace_class_add_destruction_listener().
423
424 This 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 */
441 typedef 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 */
448 typedef 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
467 All the destruction listener user functions of a trace class are called
468 when it's being destroyed.
469
470 If \bt_p{listener_id} is not \c NULL, then this function, on success,
471 sets \bt_p{*listener_id} to the ID of the added destruction listener
472 within \bt_p{trace_class}. You can then use this ID to remove the
473 added destruction listener with
474 bt_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 */
500 extern bt_trace_class_add_listener_status
501 bt_trace_class_add_destruction_listener(
502 const bt_trace_class *trace_class,
503 bt_trace_class_destruction_listener_func user_func,
504 void *user_data, bt_listener_id *listener_id) __BT_NOEXCEPT;
505
506 /*!
507 @brief
508 Status codes for bt_trace_class_remove_destruction_listener().
509 */
510 typedef 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
529 The destruction listener to remove from \bt_p{trace_class} was
530 previously added with bt_trace_class_add_destruction_listener().
531
532 You 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 */
554 extern bt_trace_class_remove_listener_status
555 bt_trace_class_remove_destruction_listener(
556 const bt_trace_class *trace_class, bt_listener_id listener_id)
557 __BT_NOEXCEPT;
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 */
581 extern void bt_trace_class_get_ref(
582 const bt_trace_class *trace_class) __BT_NOEXCEPT;
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 */
599 extern void bt_trace_class_put_ref(
600 const bt_trace_class *trace_class) __BT_NOEXCEPT;
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
627 This 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
658 #ifdef __cplusplus
659 }
660 #endif
661
662 #endif /* BABELTRACE2_TRACE_IR_TRACE_CLASS_H */
This page took 0.0441 seconds and 4 git commands to generate.