Document libbabeltrace2's C API
[babeltrace.git] / include / babeltrace2 / trace-ir / trace-class.h
1 #ifndef BABELTRACE2_TRACE_IR_TRACE_CLASS_H
2 #define BABELTRACE2_TRACE_IR_TRACE_CLASS_H
3
4 /*
5 * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
6 *
7 * Permission is hereby granted, free of charge, to any person obtaining a copy
8 * of this software and associated documentation files (the "Software"), to deal
9 * in the Software without restriction, including without limitation the rights
10 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
11 * copies of the Software, and to permit persons to whom the Software is
12 * furnished to do so, subject to the following conditions:
13 *
14 * The above copyright notice and this permission notice shall be included in
15 * all copies or substantial portions of the Software.
16 *
17 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
18 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
19 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
20 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
21 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
22 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
23 * SOFTWARE.
24 */
25
26 #ifndef __BT_IN_BABELTRACE_H
27 # error "Please include <babeltrace2/babeltrace.h> instead."
28 #endif
29
30 #include <stdint.h>
31
32 #include <babeltrace2/types.h>
33
34 #ifdef __cplusplus
35 extern "C" {
36 #endif
37
38 /*!
39 @defgroup api-tir-trace-cls Trace class
40 @ingroup api-tir
41
42 @brief
43 Class of \bt_p_trace.
44
45 A <strong><em>trace class</em></strong> is the class of \bt_p_trace:
46
47 @image html trace-structure.png
48
49 In the illustration above, notice that a trace is an instance of a
50 trace class.
51
52 A trace class is a \ref api-tir "trace IR" metadata object.
53
54 A trace class is a \ref api-fund-shared-object "shared object": get a
55 new reference with bt_trace_class_get_ref() and put an existing
56 reference with bt_trace_class_put_ref().
57
58 Some library functions \ref api-fund-freezing "freeze" trace classes on
59 success. The documentation of those functions indicate this
60 postcondition. With a frozen trace class, you can still:
61
62 - Create and add a \bt_p_stream_cls to it with
63 bt_stream_class_create() or bt_stream_class_create_with_id().
64 - Add a destruction listener to it with
65 bt_trace_class_add_destruction_listener().
66
67 The type of a trace class is #bt_trace_class.
68
69 A trace class contains \bt_p_stream_cls. All the stream classes of a
70 given trace class have unique
71 \ref api-tir-stream-cls-prop-id "numeric IDs". Get the number of stream
72 classes in a trace class with bt_trace_class_get_stream_class_count().
73 Borrow a specific stream class from a trace class with
74 bt_trace_class_borrow_stream_class_by_index(),
75 bt_trace_class_borrow_stream_class_by_index_const(),
76 bt_trace_class_borrow_stream_class_by_id(), or
77 bt_trace_class_borrow_stream_class_by_id_const().
78
79 Set whether or not the \bt_p_stream_cls you create for a trace class get
80 automatic numeric IDs with
81 bt_trace_class_set_assigns_automatic_stream_class_id().
82
83 Create a default trace class from a \bt_self_comp with
84 bt_trace_class_create().
85
86 Add to and remove a destruction listener from a trace class with
87 bt_trace_class_add_destruction_listener() and
88 bt_trace_class_remove_destruction_listener().
89
90 <h1>Properties</h1>
91
92 A trace class has the following properties:
93
94 <dl>
95 <dt>
96 \anchor api-tir-trace-cls-prop-auto-sc-id
97 Assigns automatic stream class IDs?
98 </dt>
99 <dd>
100 Whether or not the stream classes you create and add to the trace
101 class get \ref api-tir-stream-cls-prop-id "numeric IDs"
102 automatically.
103
104 Depending on the value of this property, to create a stream class
105 and add it to the trace class:
106
107 <dl>
108 <dt>#BT_TRUE</dt>
109 <dd>
110 Use bt_stream_class_create().
111 </dd>
112
113 <dt>#BT_FALSE</dt>
114 <dd>
115 Use bt_stream_class_create_with_id().
116 </dd>
117 </dl>
118
119 Use bt_trace_class_set_assigns_automatic_stream_class_id()
120 and bt_trace_class_assigns_automatic_stream_class_id().
121 </dd>
122
123 <dt>
124 \anchor api-tir-trace-cls-prop-user-attrs
125 \bt_dt_opt User attributes
126 </dt>
127 <dd>
128 User attributes of the trace class.
129
130 User attributes are custom attributes attached to a trace class.
131
132 Use bt_trace_class_set_user_attributes(),
133 bt_trace_class_borrow_user_attributes(), and
134 bt_trace_class_borrow_user_attributes_const().
135 </dd>
136 </dl>
137 */
138
139 /*! @{ */
140
141 /*!
142 @name Type
143 @{
144
145 @typedef struct bt_trace_class bt_trace_class;
146
147 @brief
148 Trace class.
149
150 @}
151 */
152
153 /*!
154 @name Creation
155 @{
156 */
157
158 /*!
159 @brief
160 Creates a default trace class from the \bt_self_comp
161 \bt_p{self_component}.
162
163 On success, the returned trace class has the following property values:
164
165 <table>
166 <tr>
167 <th>Property
168 <th>Value
169 <tr>
170 <td>\ref api-tir-trace-cls-prop-auto-sc-id "Assigns automatic stream class IDs?"
171 <td>Yes
172 <tr>
173 <td>\ref api-tir-trace-cls-prop-user-attrs "User attributes"
174 <td>Empty \bt_map_val
175 </table>
176
177 @param[in] self_component
178 Self component from which to create the default trace class.
179
180 @returns
181 New trace class reference, or \c NULL on memory error.
182 */
183 extern bt_trace_class *bt_trace_class_create(bt_self_component *self_component);
184
185 /*! @} */
186
187 /*!
188 @name Stream class access
189 @{
190 */
191
192 /*!
193 @brief
194 Returns the number of \bt_p_stream_cls contained in the trace
195 class \bt_p{trace_class}.
196
197 @param[in] trace_class
198 Trace class of which to get the number of contained stream classes.
199
200 @returns
201 Number of contained stream classes in \bt_p{trace_class}.
202
203 @bt_pre_not_null{trace_class}
204 */
205 extern uint64_t bt_trace_class_get_stream_class_count(
206 const bt_trace_class *trace_class);
207
208 /*!
209 @brief
210 Borrows the \bt_stream_cls at index \bt_p{index} from the
211 trace class \bt_p{trace_class}.
212
213 @param[in] trace_class
214 Trace class from which to borrow the stream class at index
215 \bt_p{index}.
216 @param[in] index
217 Index of the stream class to borrow from \bt_p{trace_class}.
218
219 @returns
220 @parblock
221 \em Borrowed reference of the stream class of
222 \bt_p{trace_class} at index \bt_p{index}.
223
224 The returned pointer remains valid as long as \bt_p{trace_class}
225 exists.
226 @endparblock
227
228 @bt_pre_not_null{trace_class}
229 @pre
230 \bt_p{index} is less than the number of stream classes in
231 \bt_p{trace_class} (as returned by
232 bt_trace_class_get_stream_class_count()).
233
234 @sa bt_trace_class_get_stream_class_count() &mdash;
235 Returns the number of stream classes contained in a trace class.
236 @sa bt_trace_class_borrow_stream_class_by_index_const() &mdash;
237 \c const version of this function.
238 */
239 extern bt_stream_class *bt_trace_class_borrow_stream_class_by_index(
240 bt_trace_class *trace_class, uint64_t index);
241
242 /*!
243 @brief
244 Borrows the \bt_stream_cls at index \bt_p{index} from the
245 trace class \bt_p{trace_class} (\c const version).
246
247 See bt_trace_class_borrow_stream_class_by_index().
248 */
249 extern const bt_stream_class *
250 bt_trace_class_borrow_stream_class_by_index_const(
251 const bt_trace_class *trace_class, uint64_t index);
252
253 /*!
254 @brief
255 Borrows the \bt_stream_cls having the numeric ID \bt_p{id} from the
256 trace class \bt_p{trace_class}.
257
258 If there's no stream class having the numeric ID \bt_p{id} in
259 \bt_p{trace_class}, this function returns \c NULL.
260
261 @param[in] trace_class
262 Trace class from which to borrow the stream class having the
263 numeric ID \bt_p{id}.
264 @param[in] id
265 ID of the stream class to borrow from \bt_p{trace_class}.
266
267 @returns
268 @parblock
269 \em Borrowed reference of the stream class of
270 \bt_p{trace_class} having the numeric ID \bt_p{id}, or \c NULL
271 if none.
272
273 The returned pointer remains valid as long as \bt_p{trace_class}
274 exists.
275 @endparblock
276
277 @bt_pre_not_null{trace_class}
278
279 @sa bt_trace_class_borrow_stream_class_by_id_const() &mdash;
280 \c const version of this function.
281 */
282 extern bt_stream_class *bt_trace_class_borrow_stream_class_by_id(
283 bt_trace_class *trace_class, uint64_t id);
284
285 /*!
286 @brief
287 Borrows the \bt_stream_cls having the numeric ID \bt_p{id} from the
288 trace class \bt_p{trace_class} (\c const version).
289
290 See bt_trace_class_borrow_stream_class_by_id().
291 */
292 extern const bt_stream_class *bt_trace_class_borrow_stream_class_by_id_const(
293 const bt_trace_class *trace_class, uint64_t id);
294
295 /*! @} */
296
297 /*!
298 @name Properties
299 @{
300 */
301
302 /*!
303 @brief
304 Sets whether or not the trace class \bt_p{trace_class} automatically
305 assigns a numeric ID to a \bt_stream_cls you create and add to it.
306
307 See the \ref api-tir-trace-cls-prop-auto-sc-id "assigns automatic stream class IDs?"
308 property.
309
310 @param[in] trace_class
311 Trace class of which to set whether or not it assigns automatic
312 stream class IDs.
313 @param[in] assigns_automatic_stream_class_id
314 #BT_TRUE to make \bt_p{trace_class} assign automatic stream class
315 IDs.
316
317 @bt_pre_not_null{trace_class}
318 @bt_pre_hot{trace_class}
319
320 @sa bt_trace_class_assigns_automatic_stream_class_id() &mdash;
321 Returns whether or not a trace class automatically assigns
322 stream class IDs.
323 */
324 extern void bt_trace_class_set_assigns_automatic_stream_class_id(
325 bt_trace_class *trace_class,
326 bt_bool assigns_automatic_stream_class_id);
327
328 /*!
329 @brief
330 Returns whether or not the trace class \bt_p{trace_class}
331 automatically assigns a numeric ID to a \bt_stream_cls you create
332 and add to it.
333
334 See the \ref api-tir-trace-cls-prop-auto-sc-id "assigns automatic stream class IDs?"
335 property.
336
337 @param[in] trace_class
338 Trace class of which to get whether or not it assigns automatic
339 stream class IDs.
340
341 @returns
342 #BT_TRUE if \bt_p{trace_class} automatically
343 assigns stream class IDs.
344
345 @bt_pre_not_null{trace_class}
346
347 @sa bt_trace_class_set_assigns_automatic_stream_class_id() &mdash;
348 Sets whether or not a trace class automatically assigns
349 stream class IDs.
350 */
351 extern bt_bool bt_trace_class_assigns_automatic_stream_class_id(
352 const bt_trace_class *trace_class);
353
354 /*!
355 @brief
356 Sets the user attributes of the trace class \bt_p{trace_class} to
357 \bt_p{user_attributes}.
358
359 See the \ref api-tir-trace-cls-prop-user-attrs "user attributes"
360 property.
361
362 @note
363 When you create a default trace class with bt_trace_class_create()
364 or bt_trace_class_create_with_id(), the trace class's initial user
365 attributes is an empty \bt_map_val. Therefore you can borrow it with
366 bt_trace_class_borrow_user_attributes() and fill it directly
367 instead of setting a new one with this function.
368
369 @param[in] trace_class
370 Trace class of which to set the user attributes to
371 \bt_p{user_attributes}.
372 @param[in] user_attributes
373 New user attributes of \bt_p{trace_class}.
374
375 @bt_pre_not_null{trace_class}
376 @bt_pre_hot{trace_class}
377 @bt_pre_not_null{user_attributes}
378 @bt_pre_is_map_val{user_attributes}
379
380 @sa bt_trace_class_borrow_user_attributes() &mdash;
381 Borrows the user attributes of a trace class.
382 */
383 extern void bt_trace_class_set_user_attributes(
384 bt_trace_class *trace_class, const bt_value *user_attributes);
385
386 /*!
387 @brief
388 Borrows the user attributes of the trace class \bt_p{trace_class}.
389
390 See the \ref api-tir-trace-cls-prop-user-attrs "user attributes"
391 property.
392
393 @note
394 When you create a default trace class with bt_trace_class_create()
395 or bt_trace_class_create_with_id(), the trace class's initial user
396 attributes is an empty \bt_map_val.
397
398 @param[in] trace_class
399 Trace class from which to borrow the user attributes.
400
401 @returns
402 User attributes of \bt_p{trace_class} (a \bt_map_val).
403
404 @bt_pre_not_null{trace_class}
405
406 @sa bt_trace_class_set_user_attributes() &mdash;
407 Sets the user attributes of a trace class.
408 @sa bt_trace_class_borrow_user_attributes_const() &mdash;
409 \c const version of this function.
410 */
411 extern bt_value *bt_trace_class_borrow_user_attributes(
412 bt_trace_class *trace_class);
413
414 /*!
415 @brief
416 Borrows the user attributes of the trace class \bt_p{trace_class}
417 (\c const version).
418
419 See bt_trace_class_borrow_user_attributes().
420 */
421 extern const bt_value *bt_trace_class_borrow_user_attributes_const(
422 const bt_trace_class *trace_class);
423
424 /*! @} */
425
426 /*!
427 @name Listeners
428 @{
429 */
430
431 /*!
432 @brief
433 User function for bt_trace_class_add_destruction_listener().
434
435 This is the user function type for a trace class destruction listener.
436
437 @param[in] trace_class
438 Trace class being destroyed (\ref api-fund-freezing "frozen").
439 @param[in] user_data
440 User data, as passed as the \bt_p{user_data} parameter of
441 bt_trace_class_add_destruction_listener().
442
443 @bt_pre_not_null{trace_class}
444
445 @post
446 The reference count of \bt_p{trace_class} is not changed.
447 @bt_post_no_error
448
449 @sa bt_trace_class_add_destruction_listener() &mdash;
450 Adds a destruction listener to a trace class.
451 */
452 typedef void (* bt_trace_class_destruction_listener_func)(
453 const bt_trace_class *trace_class, void *user_data);
454
455 /*!
456 @brief
457 Status codes for bt_trace_class_add_destruction_listener().
458 */
459 typedef enum bt_trace_class_add_listener_status {
460 /*!
461 @brief
462 Success.
463 */
464 BT_TRACE_CLASS_ADD_LISTENER_STATUS_OK = __BT_FUNC_STATUS_OK,
465
466 /*!
467 @brief
468 Out of memory.
469 */
470 BT_TRACE_CLASS_ADD_LISTENER_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
471 } bt_trace_class_add_listener_status;
472
473 /*!
474 @brief
475 Adds a destruction listener having the function \bt_p{user_func}
476 to the trace class \bt_p{trace_class}.
477
478 All the destruction listener user functions of a trace class are called
479 when it's being destroyed.
480
481 If \bt_p{listener_id} is not \c NULL, then this function, on success,
482 sets \bt_p{*listener_id} to the ID of the added destruction listener
483 within \bt_p{trace_class}. You can then use this ID to remove the
484 added destruction listener with
485 bt_trace_class_remove_destruction_listener().
486
487 @param[in] trace_class
488 Trace class to add the destruction listener to.
489 @param[in] user_func
490 User function of the destruction listener to add to
491 \bt_p{trace_class}.
492 @param[in] user_data
493 User data to pass as the \bt_p{user_data} parameter of
494 \bt_p{user_func}.
495 @param[out] listener_id
496 <strong>On success and if not \c NULL</strong>, \bt_p{*listener_id}
497 is the ID of the added destruction listener within
498 \bt_p{trace_class}.
499
500 @retval #BT_TRACE_CLASS_ADD_LISTENER_STATUS_OK
501 Success.
502 @retval #BT_TRACE_CLASS_ADD_LISTENER_STATUS_MEMORY_ERROR
503 Out of memory.
504
505 @bt_pre_not_null{trace_class}
506 @bt_pre_not_null{user_func}
507
508 @sa bt_trace_class_remove_destruction_listener() &mdash;
509 Removes a destruction listener from a trace class.
510 */
511 extern bt_trace_class_add_listener_status
512 bt_trace_class_add_destruction_listener(
513 const bt_trace_class *trace_class,
514 bt_trace_class_destruction_listener_func user_func,
515 void *user_data, bt_listener_id *listener_id);
516
517 /*!
518 @brief
519 Status codes for bt_trace_class_remove_destruction_listener().
520 */
521 typedef enum bt_trace_class_remove_listener_status {
522 /*!
523 @brief
524 Success.
525 */
526 BT_TRACE_CLASS_REMOVE_LISTENER_STATUS_OK = __BT_FUNC_STATUS_OK,
527
528 /*!
529 @brief
530 Out of memory.
531 */
532 BT_TRACE_CLASS_REMOVE_LISTENER_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
533 } bt_trace_class_remove_listener_status;
534
535 /*!
536 @brief
537 Removes the destruction listener having the ID \bt_p{listener_id}
538 from the trace class \bt_p{trace_class}.
539
540 The destruction listener to remove from \bt_p{trace_class} was
541 previously added with bt_trace_class_add_destruction_listener().
542
543 You can call this function when \bt_p{trace_class} is
544 \ref api-fund-freezing "frozen".
545
546 @param[in] trace_class
547 Trace class from which to remove the destruction listener having
548 the ID \bt_p{listener_id}.
549 @param[in] listener_id
550 ID of the destruction listener to remove from \bt_p{trace_class}­.
551
552 @retval #BT_TRACE_CLASS_REMOVE_LISTENER_STATUS_OK
553 Success.
554 @retval #BT_TRACE_CLASS_REMOVE_LISTENER_STATUS_MEMORY_ERROR
555 Out of memory.
556
557 @bt_pre_not_null{trace_class}
558 @pre
559 \bt_p{listener_id} is the ID of an existing destruction listener
560 in \bt_p{trace_class}.
561
562 @sa bt_trace_class_add_destruction_listener() &mdash;
563 Adds a destruction listener to a trace class.
564 */
565 extern bt_trace_class_remove_listener_status
566 bt_trace_class_remove_destruction_listener(
567 const bt_trace_class *trace_class, bt_listener_id listener_id);
568
569 /*! @} */
570
571 /*!
572 @name Reference count
573 @{
574 */
575
576 /*!
577 @brief
578 Increments the \ref api-fund-shared-object "reference count" of
579 the trace class \bt_p{trace_class}.
580
581 @param[in] trace_class
582 @parblock
583 Trace class of which to increment the reference count.
584
585 Can be \c NULL.
586 @endparblock
587
588 @sa bt_trace_class_put_ref() &mdash;
589 Decrements the reference count of a trace class.
590 */
591 extern void bt_trace_class_get_ref(const bt_trace_class *trace_class);
592
593 /*!
594 @brief
595 Decrements the \ref api-fund-shared-object "reference count" of
596 the trace class \bt_p{trace_class}.
597
598 @param[in] trace_class
599 @parblock
600 Trace class of which to decrement the reference count.
601
602 Can be \c NULL.
603 @endparblock
604
605 @sa bt_trace_class_get_ref() &mdash;
606 Increments the reference count of a trace class.
607 */
608 extern void bt_trace_class_put_ref(const bt_trace_class *trace_class);
609
610 /*!
611 @brief
612 Decrements the reference count of the trace class
613 \bt_p{_trace_class}, and then sets \bt_p{_trace_class} to \c NULL.
614
615 @param _trace_class
616 @parblock
617 Trace class of which to decrement the reference count.
618
619 Can contain \c NULL.
620 @endparblock
621
622 @bt_pre_assign_expr{_trace_class}
623 */
624 #define BT_TRACE_CLASS_PUT_REF_AND_RESET(_trace_class) \
625 do { \
626 bt_trace_class_put_ref(_trace_class); \
627 (_trace_class) = NULL; \
628 } while (0)
629
630 /*!
631 @brief
632 Decrements the reference count of the trace class \bt_p{_dst}, sets
633 \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL.
634
635 This macro effectively moves a trace class reference from the expression
636 \bt_p{_src} to the expression \bt_p{_dst}, putting the existing
637 \bt_p{_dst} reference.
638
639 @param _dst
640 @parblock
641 Destination expression.
642
643 Can contain \c NULL.
644 @endparblock
645 @param _src
646 @parblock
647 Source expression.
648
649 Can contain \c NULL.
650 @endparblock
651
652 @bt_pre_assign_expr{_dst}
653 @bt_pre_assign_expr{_src}
654 */
655 #define BT_TRACE_CLASS_MOVE_REF(_dst, _src) \
656 do { \
657 bt_trace_class_put_ref(_dst); \
658 (_dst) = (_src); \
659 (_src) = NULL; \
660 } while (0)
661
662 /*! @} */
663
664 /*! @} */
665
666 #ifdef __cplusplus
667 }
668 #endif
669
670 #endif /* BABELTRACE2_TRACE_IR_TRACE_CLASS_H */
This page took 0.046959 seconds and 4 git commands to generate.