Document libbabeltrace2's C API
[babeltrace.git] / include / babeltrace2 / trace-ir / trace-class.h
CommitLineData
7704a0af 1 #ifndef BABELTRACE2_TRACE_IR_TRACE_CLASS_H
3fd40f46 2#define BABELTRACE2_TRACE_IR_TRACE_CLASS_H
10b7a2e4
PP
3
4/*
0dcb770f 5 * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
10b7a2e4 6 *
10b7a2e4
PP
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.
10b7a2e4
PP
24 */
25
9df34b44
PP
26#ifndef __BT_IN_BABELTRACE_H
27# error "Please include <babeltrace2/babeltrace.h> instead."
28#endif
29
fb25b9e3
PP
30#include <stdint.h>
31
71c5da58 32#include <babeltrace2/types.h>
10b7a2e4 33
10b7a2e4
PP
34#ifdef __cplusplus
35extern "C" {
36#endif
37
7704a0af
PP
38/*!
39@defgroup api-tir-trace-cls Trace class
40@ingroup api-tir
10b7a2e4 41
7704a0af
PP
42@brief
43 Class of \bt_p_trace.
af90138b 44
7704a0af 45A <strong><em>trace class</em></strong> is the class of \bt_p_trace:
af90138b 46
7704a0af
PP
47@image html trace-structure.png
48
49In the illustration above, notice that a trace is an instance of a
50trace class.
51
52A trace class is a \ref api-tir "trace IR" metadata object.
53
54A trace class is a \ref api-fund-shared-object "shared object": get a
55new reference with bt_trace_class_get_ref() and put an existing
56reference with bt_trace_class_put_ref().
57
58Some library functions \ref api-fund-freezing "freeze" trace classes on
59success. The documentation of those functions indicate this
60postcondition. 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
67The type of a trace class is #bt_trace_class.
68
69A trace class contains \bt_p_stream_cls. All the stream classes of a
70given trace class have unique
71\ref api-tir-stream-cls-prop-id "numeric IDs". Get the number of stream
72classes in a trace class with bt_trace_class_get_stream_class_count().
73Borrow a specific stream class from a trace class with
74bt_trace_class_borrow_stream_class_by_index(),
75bt_trace_class_borrow_stream_class_by_index_const(),
76bt_trace_class_borrow_stream_class_by_id(), or
77bt_trace_class_borrow_stream_class_by_id_const().
78
79Set whether or not the \bt_p_stream_cls you create for a trace class get
80automatic numeric IDs with
81bt_trace_class_set_assigns_automatic_stream_class_id().
82
83Create a default trace class from a \bt_self_comp with
84bt_trace_class_create().
85
86Add to and remove a destruction listener from a trace class with
87bt_trace_class_add_destruction_listener() and
88bt_trace_class_remove_destruction_listener().
89
90<h1>Properties</h1>
91
92A 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
163On 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.
10b7a2e4 179
7704a0af
PP
180@returns
181 New trace class reference, or \c NULL on memory error.
182*/
183extern 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*/
205extern 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*/
8eee8ea2
PP
239extern bt_stream_class *bt_trace_class_borrow_stream_class_by_index(
240 bt_trace_class *trace_class, uint64_t index);
10b7a2e4 241
7704a0af
PP
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
247See bt_trace_class_borrow_stream_class_by_index().
248*/
249extern const bt_stream_class *
250bt_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
258If 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*/
8eee8ea2
PP
282extern bt_stream_class *bt_trace_class_borrow_stream_class_by_id(
283 bt_trace_class *trace_class, uint64_t id);
10b7a2e4 284
7704a0af
PP
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
290See bt_trace_class_borrow_stream_class_by_id().
291*/
292extern 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
307See the \ref api-tir-trace-cls-prop-auto-sc-id "assigns automatic stream class IDs?"
308property.
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*/
324extern 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
334See the \ref api-tir-trace-cls-prop-auto-sc-id "assigns automatic stream class IDs?"
335property.
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*/
351extern 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
359See the \ref api-tir-trace-cls-prop-user-attrs "user attributes"
360property.
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*/
383extern 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
390See the \ref api-tir-trace-cls-prop-user-attrs "user attributes"
391property.
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*/
411extern 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
419See bt_trace_class_borrow_user_attributes().
420*/
421extern 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
435This 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*/
452typedef 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*/
459typedef 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
478All the destruction listener user functions of a trace class are called
479when it's being destroyed.
480
481If \bt_p{listener_id} is not \c NULL, then this function, on success,
482sets \bt_p{*listener_id} to the ID of the added destruction listener
483within \bt_p{trace_class}. You can then use this ID to remove the
484added destruction listener with
485bt_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*/
511extern bt_trace_class_add_listener_status
512bt_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*/
521typedef 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
540The destruction listener to remove from \bt_p{trace_class} was
541previously added with bt_trace_class_add_destruction_listener().
542
543You 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*/
565extern bt_trace_class_remove_listener_status
566bt_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*/
591extern 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*/
608extern 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
635This 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
10b7a2e4
PP
666#ifdef __cplusplus
667}
668#endif
669
3fd40f46 670#endif /* BABELTRACE2_TRACE_IR_TRACE_CLASS_H */
This page took 0.077096 seconds and 4 git commands to generate.