include: add IWYU pragmas in private header files
[babeltrace.git] / include / babeltrace2 / trace-ir / event-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_EVENT_CLASS_H
8 #define BABELTRACE2_TRACE_IR_EVENT_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-ev-cls Event class
26 @ingroup api-tir
27
28 @brief
29 Class of \bt_p_ev.
30
31 An <strong><em>event class</em></strong> is the class of \bt_p_ev,
32 which \bt_p_ev_msg contain:
33
34 @image html trace-structure.png
35
36 In the illustration above, notice that:
37
38 - A \bt_stream is a conceptual \ref api-msg-seq "sequence of messages",
39 some of which are \bt_p_ev_msg.
40 - An event message contains an \bt_ev.
41 - An event is an instance of an event class.
42 - The \ref api-tir-ev-prop-payload "payload field" of an event is an
43 instance of the \ref api-tir-ev-cls-prop-p-fc "payload field class"
44 which an event class contains.
45
46 An event class is a \ref api-tir "trace IR" metadata object.
47
48 An event class is a \ref api-fund-shared-object "shared object": get a
49 new reference with bt_event_class_get_ref() and put an existing
50 reference with bt_event_class_put_ref().
51
52 Some library functions \ref api-fund-freezing "freeze" event classes on
53 success. The documentation of those functions indicate this
54 postcondition.
55
56 The type of an event class is #bt_event_class.
57
58 A \bt_stream_cls contains event classes. All the event classes of a
59 given stream class have unique
60 \ref api-tir-ev-cls-prop-id "numeric IDs". Borrow the stream class
61 which contains an event class with bt_event_class_borrow_stream_class()
62 or bt_event_class_borrow_stream_class_const().
63
64 To create a default event class:
65
66 <dl>
67 <dt>
68 If bt_stream_class_assigns_automatic_event_class_id() returns
69 #BT_TRUE (the default) for the stream class to use
70 </dt>
71 <dd>Use bt_event_class_create().</dd>
72
73 <dt>
74 If bt_stream_class_assigns_automatic_event_class_id() returns
75 #BT_FALSE for the stream class to use
76 </dt>
77 <dd>Use bt_event_class_create_with_id().</dd>
78 </dl>
79
80 <h1>Properties</h1>
81
82 An event class has the following properties:
83
84 <dl>
85 <dt>\anchor api-tir-ev-cls-prop-id Numeric ID</dt>
86 <dd>
87 Numeric ID, unique amongst the numeric IDs of the event class's
88 \bt_stream_cls's event classes.
89
90 Depending on whether or not the event class's stream class
91 automatically assigns event class IDs
92 (see bt_stream_class_assigns_automatic_event_class_id()),
93 set the event class's numeric ID on creation with
94 bt_event_class_create() or
95 bt_event_class_create_with_id().
96
97 You cannot change the numeric ID once the event class is created.
98
99 Get an event class's numeric ID with bt_event_class_get_id().
100 </dd>
101
102 <dt>\anchor api-tir-ev-cls-prop-name \bt_dt_opt Name</dt>
103 <dd>
104 Name of the event class.
105
106 Use bt_event_class_set_name() and bt_event_class_get_name().
107 </dd>
108
109 <dt>\anchor api-tir-ev-cls-prop-log-lvl \bt_dt_opt Log level</dt>
110 <dd>
111 Log level of the event class.
112
113 The event class's log level corresponds to the log level of the
114 tracer's original instrumentation point.
115
116 Use bt_event_class_set_log_level() and
117 bt_event_class_get_log_level().
118 </dd>
119
120 <dt>
121 \anchor api-tir-ev-cls-prop-emf-uri
122 \bt_dt_opt Eclipse Modeling Framework (EMF) URI
123 </dt>
124 <dd>
125 EMF URI of the event class.
126
127 Use bt_event_class_set_emf_uri() and
128 bt_event_class_get_emf_uri().
129 </dd>
130
131 <dt>
132 \anchor api-tir-ev-cls-prop-p-fc
133 \bt_dt_opt Payload field class
134 </dt>
135 <dd>
136 Payload \bt_fc of the event class.
137
138 The payload of an event class instance (\bt_ev) contains the
139 event's main data.
140
141 Use bt_event_class_set_payload_field_class()
142 bt_event_class_borrow_payload_field_class(),
143 and bt_event_class_borrow_payload_field_class_const().
144 </dd>
145
146 <dt>
147 \anchor api-tir-ev-cls-prop-sc-fc
148 \bt_dt_opt Specific context field class
149 </dt>
150 <dd>
151 Specific context \bt_fc of the event class.
152
153 The specific context of an event class instance (\bt_ev) contains
154 any contextual data of which the layout is specific to the
155 event's class and which does not belong to the payload.
156
157 Use bt_event_class_set_specific_context_field_class()
158 bt_event_class_borrow_specific_context_field_class(),
159 and bt_event_class_borrow_specific_context_field_class_const().
160 </dd>
161
162 <dt>
163 \anchor api-tir-ev-cls-prop-user-attrs
164 \bt_dt_opt User attributes
165 </dt>
166 <dd>
167 User attributes of the event class.
168
169 User attributes are custom attributes attached to an event class.
170
171 Use bt_event_class_set_user_attributes(),
172 bt_event_class_borrow_user_attributes(), and
173 bt_event_class_borrow_user_attributes_const().
174 </dd>
175 </dl>
176 */
177
178 /*! @{ */
179
180 /*!
181 @name Type
182 @{
183
184 @typedef struct bt_event_class bt_event_class;
185
186 @brief
187 Event class.
188
189 @}
190 */
191
192 /*!
193 @name Creation
194 @{
195 */
196
197 /*!
198 @brief
199 Creates a default event class and adds it to the \bt_stream_cls
200 \bt_p{stream_class}.
201
202 @attention
203 @parblock
204 Only use this function if
205
206 @code
207 bt_stream_class_assigns_automatic_event_class_id(stream_class)
208 @endcode
209
210 returns #BT_TRUE.
211
212 Otherwise, use bt_event_class_create_with_id().
213 @endparblock
214
215 On success, the returned event class has the following property values:
216
217 <table>
218 <tr>
219 <th>Property
220 <th>Value
221 <tr>
222 <td>\ref api-tir-ev-cls-prop-id "Numeric ID"
223 <td>Automatically assigned by \bt_p{stream_class}
224 <tr>
225 <td>\ref api-tir-ev-cls-prop-name "Name"
226 <td>\em None
227 <tr>
228 <td>\ref api-tir-ev-cls-prop-log-lvl "Log level"
229 <td>\em None
230 <tr>
231 <td>\ref api-tir-ev-cls-prop-emf-uri "EMF URI"
232 <td>\em None
233 <tr>
234 <td>\ref api-tir-ev-cls-prop-p-fc "Payload field class"
235 <td>\em None
236 <tr>
237 <td>\ref api-tir-ev-cls-prop-sc-fc "Specific context field class"
238 <td>\em None
239 <tr>
240 <td>\ref api-tir-ev-cls-prop-user-attrs "User attributes"
241 <td>Empty \bt_map_val
242 </table>
243
244 @param[in] stream_class
245 Stream class to add the created event class to.
246
247 @returns
248 New event class reference, or \c NULL on memory error.
249
250 @bt_pre_not_null{stream_class}
251 @pre
252 <code>bt_stream_class_assigns_automatic_event_class_id(stream_class)</code>
253 returns #BT_TRUE.
254
255 @bt_post_success_frozen{stream_class}
256
257 @sa bt_event_class_create_with_id() &mdash;
258 Creates an event class with a specific numeric ID and adds it to a
259 stream class.
260 */
261 extern bt_event_class *bt_event_class_create(
262 bt_stream_class *stream_class);
263
264 /*!
265 @brief
266 Creates a default event class with the numeric ID \bt_p{id} and adds
267 it to the \bt_stream_cls \bt_p{stream_class}.
268
269 @attention
270 @parblock
271 Only use this function if
272
273 @code
274 bt_stream_class_assigns_automatic_event_class_id(stream_class)
275 @endcode
276
277 returns #BT_FALSE.
278
279 Otherwise, use bt_event_class_create().
280 @endparblock
281
282 On success, the returned event class has the following property values:
283
284 <table>
285 <tr>
286 <th>Property
287 <th>Value
288 <tr>
289 <td>\ref api-tir-ev-cls-prop-id "Numeric ID"
290 <td>\bt_p{id}
291 <tr>
292 <td>\ref api-tir-ev-cls-prop-name "Name"
293 <td>\em None
294 <tr>
295 <td>\ref api-tir-ev-cls-prop-log-lvl "Log level"
296 <td>\em None
297 <tr>
298 <td>\ref api-tir-ev-cls-prop-emf-uri "EMF URI"
299 <td>\em None
300 <tr>
301 <td>\ref api-tir-ev-cls-prop-p-fc "Payload field class"
302 <td>\em None
303 <tr>
304 <td>\ref api-tir-ev-cls-prop-sc-fc "Specific context field class"
305 <td>\em None
306 <tr>
307 <td>\ref api-tir-ev-cls-prop-user-attrs "User attributes"
308 <td>Empty \bt_map_val
309 </table>
310
311 @param[in] stream_class
312 Stream class to add the created event class to.
313 @param[in] id
314 Numeric ID of the event class to create and add to
315 \bt_p{stream_class}.
316
317 @returns
318 New event class reference, or \c NULL on memory error.
319
320 @bt_pre_not_null{stream_class}
321 @pre
322 <code>bt_stream_class_assigns_automatic_event_class_id(stream_class)</code>
323 returns #BT_FALSE.
324 @pre
325 \bt_p{stream_class} does not contain an event class with the numeric
326 ID \bt_p{id}.
327
328 @bt_post_success_frozen{stream_class}
329
330 @sa bt_event_class_create() &mdash;
331 Creates an event class with an automatic numeric ID and adds it to a
332 stream class.
333 */
334 extern bt_event_class *bt_event_class_create_with_id(
335 bt_stream_class *stream_class, uint64_t id);
336
337 /*! @} */
338
339 /*!
340 @name Stream class access
341 @{
342 */
343
344 /*!
345 @brief
346 Borrows the \bt_stream_cls which contains the event class
347 \bt_p{event_class}.
348
349 @param[in] event_class
350 Event class from which to borrow the stream class which contains it.
351
352 @returns
353 Stream class which contains \bt_p{event_class}.
354
355 @bt_pre_not_null{event_class}
356
357 @sa bt_event_class_borrow_stream_class_const() &mdash;
358 \c const version of this function.
359 */
360 extern bt_stream_class *bt_event_class_borrow_stream_class(
361 bt_event_class *event_class);
362
363 /*!
364 @brief
365 Borrows the \bt_stream_cls which contains the event class
366 \bt_p{event_class} (\c const version).
367
368 See bt_event_class_borrow_stream_class().
369 */
370 extern const bt_stream_class *bt_event_class_borrow_stream_class_const(
371 const bt_event_class *event_class);
372
373 /*! @} */
374
375 /*!
376 @name Properties
377 @{
378 */
379
380 /*!
381 @brief
382 Returns the numeric ID of the event class \bt_p{event_class}.
383
384 See the \ref api-tir-ev-cls-prop-id "numeric ID" property.
385
386 @param[in] event_class
387 Event class of which to get the numeric ID.
388
389 @returns
390 Numeric ID of \bt_p{event_class}.
391
392 @bt_pre_not_null{event_class}
393
394 @sa bt_event_class_create_with_id() &mdash;
395 Creates an event class with a specific numeric ID and adds it to a
396 stream class.
397 */
398 extern uint64_t bt_event_class_get_id(const bt_event_class *event_class);
399
400 /*!
401 @brief
402 Status codes for bt_event_class_set_name().
403 */
404 typedef enum bt_event_class_set_name_status {
405 /*!
406 @brief
407 Success.
408 */
409 BT_EVENT_CLASS_SET_NAME_STATUS_OK = __BT_FUNC_STATUS_OK,
410
411 /*!
412 @brief
413 Out of memory.
414 */
415 BT_EVENT_CLASS_SET_NAME_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
416 } bt_event_class_set_name_status;
417
418 /*!
419 @brief
420 Sets the name of the event class \bt_p{event_class} to
421 a copy of \bt_p{name}.
422
423 See the \ref api-tir-ev-cls-prop-name "name" property.
424
425 @param[in] event_class
426 Event class of which to set the name to \bt_p{name}.
427 @param[in] name
428 New name of \bt_p{event_class} (copied).
429
430 @retval #BT_EVENT_CLASS_SET_NAME_STATUS_OK
431 Success.
432 @retval #BT_EVENT_CLASS_SET_NAME_STATUS_MEMORY_ERROR
433 Out of memory.
434
435 @bt_pre_not_null{event_class}
436 @bt_pre_hot{event_class}
437 @bt_pre_not_null{name}
438
439 @sa bt_event_class_get_name() &mdash;
440 Returns the name of an event class.
441 */
442 extern bt_event_class_set_name_status bt_event_class_set_name(
443 bt_event_class *event_class, const char *name);
444
445 /*!
446 @brief
447 Returns the name of the event class \bt_p{event_class}.
448
449 See the \ref api-tir-ev-cls-prop-name "name" property.
450
451 If \bt_p{event_class} has no name, this function returns \c NULL.
452
453 @param[in] event_class
454 Event class of which to get the name.
455
456 @returns
457 @parblock
458 Name of \bt_p{event_class}, or \c NULL if none.
459
460 The returned pointer remains valid as long as \bt_p{event_class}
461 is not modified.
462 @endparblock
463
464 @bt_pre_not_null{event_class}
465
466 @sa bt_event_class_set_name() &mdash;
467 Sets the name of an event class.
468 */
469 extern const char *bt_event_class_get_name(const bt_event_class *event_class);
470
471 /*!
472 @brief
473 Event class log level enumerators.
474 */
475 typedef enum bt_event_class_log_level {
476 /*!
477 @brief
478 System is unusable.
479 */
480 BT_EVENT_CLASS_LOG_LEVEL_EMERGENCY = 0,
481
482 /*!
483 @brief
484 Action must be taken immediately.
485 */
486 BT_EVENT_CLASS_LOG_LEVEL_ALERT = 1,
487
488 /*!
489 @brief
490 Critical conditions.
491 */
492 BT_EVENT_CLASS_LOG_LEVEL_CRITICAL = 2,
493
494 /*!
495 @brief
496 Error conditions.
497 */
498 BT_EVENT_CLASS_LOG_LEVEL_ERROR = 3,
499
500 /*!
501 @brief
502 Warning conditions.
503 */
504 BT_EVENT_CLASS_LOG_LEVEL_WARNING = 4,
505
506 /*!
507 @brief
508 Normal, but significant, condition.
509 */
510 BT_EVENT_CLASS_LOG_LEVEL_NOTICE = 5,
511
512 /*!
513 @brief
514 Informational message.
515 */
516 BT_EVENT_CLASS_LOG_LEVEL_INFO = 6,
517
518 /*!
519 @brief
520 Debugging information with system-level scope
521 (set of programs).
522 */
523 BT_EVENT_CLASS_LOG_LEVEL_DEBUG_SYSTEM = 7,
524
525 /*!
526 @brief
527 Debugging information with program-level scope
528 (set of processes).
529 */
530 BT_EVENT_CLASS_LOG_LEVEL_DEBUG_PROGRAM = 8,
531
532 /*!
533 @brief
534 Debugging information with process-level scope
535 (set of modules).
536 */
537 BT_EVENT_CLASS_LOG_LEVEL_DEBUG_PROCESS = 9,
538
539 /*!
540 @brief
541 Debugging information with module (executable/library) scope
542 (set of units).
543 */
544 BT_EVENT_CLASS_LOG_LEVEL_DEBUG_MODULE = 10,
545
546 /*!
547 @brief
548 Debugging information with compilation unit scope
549 (set of functions).
550 */
551 BT_EVENT_CLASS_LOG_LEVEL_DEBUG_UNIT = 11,
552
553 /*!
554 @brief
555 Debugging information with function-level scope.
556 */
557 BT_EVENT_CLASS_LOG_LEVEL_DEBUG_FUNCTION = 12,
558
559 /*!
560 @brief
561 Debugging information with function-level scope.
562 */
563 BT_EVENT_CLASS_LOG_LEVEL_DEBUG_LINE = 13,
564
565 /*!
566 @brief
567 Debugging-level message.
568 */
569 BT_EVENT_CLASS_LOG_LEVEL_DEBUG = 14,
570 } bt_event_class_log_level;
571
572 /*!
573 @brief
574 Sets the log level of the event class \bt_p{event_class} to
575 \bt_p{log_level}.
576
577 See the \ref api-tir-ev-cls-prop-log-lvl "log level" property.
578
579 @param[in] event_class
580 Event class of which to set the log level to \bt_p{log_level}.
581 @param[in] log_level
582 New log level of \bt_p{event_class}.
583
584 @bt_pre_not_null{event_class}
585 @bt_pre_hot{event_class}
586
587 @sa bt_event_class_get_log_level() &mdash;
588 Returns the log level of an event class.
589 */
590 extern void bt_event_class_set_log_level(bt_event_class *event_class,
591 bt_event_class_log_level log_level);
592
593 /*!
594 @brief
595 Returns the log level of the event class \bt_p{event_class}.
596
597 See the \ref api-tir-ev-cls-prop-log-lvl "log level" property.
598
599 @param[in] event_class
600 Event class of which to get the log level.
601 @param[out] log_level
602 <strong>If this function returns
603 #BT_PROPERTY_AVAILABILITY_AVAILABLE</strong>, \bt_p{*log_level} is
604 the log level of \bt_p{event_class}.
605
606 @retval #BT_PROPERTY_AVAILABILITY_AVAILABLE
607 The log level of \bt_p{event_class} is available.
608 @retval #BT_PROPERTY_AVAILABILITY_NOT_AVAILABLE
609 The log level of \bt_p{event_class} is not available.
610
611 @bt_pre_not_null{event_class}
612 @bt_pre_not_null{log_level}
613
614 @sa bt_event_class_set_log_level() &mdash;
615 Sets the log level of an event class.
616 */
617 extern bt_property_availability bt_event_class_get_log_level(
618 const bt_event_class *event_class,
619 bt_event_class_log_level *log_level);
620
621 /*!
622 @brief
623 Status codes for bt_event_class_set_emf_uri().
624 */
625 typedef enum bt_event_class_set_emf_uri_status {
626 /*!
627 @brief
628 Success.
629 */
630 BT_EVENT_CLASS_SET_EMF_URI_STATUS_OK = __BT_FUNC_STATUS_OK,
631
632 /*!
633 @brief
634 Out of memory.
635 */
636 BT_EVENT_CLASS_SET_EMF_URI_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
637 } bt_event_class_set_emf_uri_status;
638
639 /*!
640 @brief
641 Sets the Eclipse Modeling Framework (EMF) URI of the event class
642 \bt_p{event_class} to a copy of \bt_p{emf_uri}.
643
644 See the \ref api-tir-ev-cls-prop-emf-uri "EMF URI" property.
645
646 @param[in] event_class
647 Event class of which to set the EMF URI to \bt_p{emf_uri}.
648 @param[in] emf_uri
649 New EMF URI of \bt_p{event_class} (copied).
650
651 @retval #BT_EVENT_CLASS_SET_EMF_URI_STATUS_OK
652 Success.
653 @retval #BT_EVENT_CLASS_SET_EMF_URI_STATUS_MEMORY_ERROR
654 Out of memory.
655
656 @bt_pre_not_null{event_class}
657 @bt_pre_hot{event_class}
658 @bt_pre_not_null{emf_uri}
659
660 @sa bt_event_class_get_emf_uri() &mdash;
661 Returns the EMF URI of an event class.
662 */
663 extern bt_event_class_set_emf_uri_status bt_event_class_set_emf_uri(
664 bt_event_class *event_class, const char *emf_uri);
665
666 /*!
667 @brief
668 Returns the Eclipse Modeling Framework (EMF) URI of the event
669 class \bt_p{event_class}.
670
671 See the \ref api-tir-ev-cls-prop-emf-uri "EMF URI" property.
672
673 If \bt_p{event_class} has no EMF URI, this function returns \c NULL.
674
675 @param[in] event_class
676 Event class of which to get the EMF URI.
677
678 @returns
679 @parblock
680 EMF URI of \bt_p{event_class}, or \c NULL if none.
681
682 The returned pointer remains valid as long as \bt_p{event_class}
683 is not modified.
684 @endparblock
685
686 @bt_pre_not_null{event_class}
687
688 @sa bt_event_class_set_emf_uri() &mdash;
689 Sets the EMF URI of an event class.
690 */
691 extern const char *bt_event_class_get_emf_uri(
692 const bt_event_class *event_class);
693
694 /*!
695 @brief
696 Status codes for bt_event_class_set_payload_field_class() and
697 bt_event_class_set_specific_context_field_class().
698 */
699 typedef enum bt_event_class_set_field_class_status {
700 /*!
701 @brief
702 Success.
703 */
704 BT_EVENT_CLASS_SET_FIELD_CLASS_STATUS_OK = __BT_FUNC_STATUS_OK,
705
706 /*!
707 @brief
708 Out of memory.
709 */
710 BT_EVENT_CLASS_SET_FIELD_CLASS_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
711 } bt_event_class_set_field_class_status;
712
713 /*!
714 @brief
715 Sets the payload \bt_fc of the event class
716 \bt_p{event_class} to \bt_p{field_class}.
717
718 See the \ref api-tir-ev-cls-prop-p-fc "payload field class" property.
719
720 @param[in] event_class
721 Event class of which to set the payload field class to
722 \bt_p{field_class}.
723 @param[in] field_class
724 New payload field class of \bt_p{event_class}.
725
726 @retval #BT_EVENT_CLASS_SET_FIELD_CLASS_STATUS_OK
727 Success.
728 @retval #BT_EVENT_CLASS_SET_FIELD_CLASS_STATUS_MEMORY_ERROR
729 Out of memory.
730
731 @bt_pre_not_null{event_class}
732 @bt_pre_hot{event_class}
733 @bt_pre_not_null{field_class}
734 @bt_pre_is_struct_fc{field_class}
735 @pre
736 \bt_p{field_class}, or any of its contained field classes,
737 is not already part of a \bt_stream_cls or of an event class.
738 @pre
739 If any of the field classes recursively contained in
740 \bt_p{field_class} has a
741 \ref api-tir-fc-link "link to another field class", it must honor
742 the field class link rules.
743
744 @bt_post_success_frozen{field_class}
745
746 @sa bt_event_class_borrow_payload_field_class() &mdash;
747 Borrows the payload field class of an event class.
748 @sa bt_event_class_borrow_payload_field_class_const() &mdash;
749 Borrows the payload field class of an event class
750 (\c const version).
751 */
752 extern bt_event_class_set_field_class_status
753 bt_event_class_set_payload_field_class(bt_event_class *event_class,
754 bt_field_class *field_class);
755
756 /*!
757 @brief
758 Borrows the payload \bt_fc from the event class \bt_p{event_class}.
759
760 See the \ref api-tir-ev-cls-prop-p-fc "payload field class" property.
761
762 If \bt_p{event_class} has no payload field class, this function
763 returns \c NULL.
764
765 @param[in] event_class
766 Event class from which to borrow the payload field class.
767
768 @returns
769 \em Borrowed reference of the payload field class of
770 \bt_p{event_class}, or \c NULL if none.
771
772 @bt_pre_not_null{event_class}
773
774 @sa bt_event_class_set_payload_field_class() &mdash;
775 Sets the payload field class of an event class.
776 @sa bt_event_class_borrow_payload_field_class_const() &mdash;
777 \c const version of this function.
778 */
779 extern bt_field_class *bt_event_class_borrow_payload_field_class(
780 bt_event_class *event_class);
781
782 /*!
783 @brief
784 Borrows the payload \bt_fc from the event class \bt_p{event_class}
785 (\c const version).
786
787 See bt_event_class_borrow_payload_field_class().
788 */
789 extern const bt_field_class *bt_event_class_borrow_payload_field_class_const(
790 const bt_event_class *event_class);
791
792 /*!
793 @brief
794 Sets the specific context \bt_fc of the event class
795 \bt_p{event_class} to \bt_p{field_class}.
796
797 See the \ref api-tir-ev-cls-prop-sc-fc "specific context field class"
798 property.
799
800 @param[in] event_class
801 Event class of which to set the specific context field class to
802 \bt_p{field_class}.
803 @param[in] field_class
804 New specific context field class of \bt_p{event_class}.
805
806 @retval #BT_EVENT_CLASS_SET_FIELD_CLASS_STATUS_OK
807 Success.
808 @retval #BT_EVENT_CLASS_SET_FIELD_CLASS_STATUS_MEMORY_ERROR
809 Out of memory.
810
811 @bt_pre_not_null{event_class}
812 @bt_pre_hot{event_class}
813 @bt_pre_not_null{field_class}
814 @bt_pre_is_struct_fc{field_class}
815 @pre
816 \bt_p{field_class}, or any of its contained field classes,
817 is not already part of a \bt_stream_cls or of an event class.
818 @pre
819 If any of the field classes recursively contained in
820 \bt_p{field_class} has a
821 \ref api-tir-fc-link "link to another field class", it must honor
822 the field class link rules.
823
824 @bt_post_success_frozen{field_class}
825
826 @sa bt_event_class_borrow_specific_context_field_class() &mdash;
827 Borrows the specific context field class of an event class.
828 @sa bt_event_class_borrow_specific_context_field_class_const() &mdash;
829 Borrows the specific context field class of an event class
830 (\c const version).
831 */
832 extern bt_event_class_set_field_class_status
833 bt_event_class_set_specific_context_field_class(bt_event_class *event_class,
834 bt_field_class *field_class);
835
836 /*!
837 @brief
838 Borrows the specific context \bt_fc from the event class
839 \bt_p{event_class}.
840
841 See the \ref api-tir-ev-cls-prop-sc-fc "specific context field class"
842 property.
843
844 If \bt_p{event_class} has no specific context field class, this function
845 returns \c NULL.
846
847 @param[in] event_class
848 Event class from which to borrow the specific context field class.
849
850 @returns
851 \em Borrowed reference of the specific context field class of
852 \bt_p{event_class}, or \c NULL if none.
853
854 @bt_pre_not_null{event_class}
855
856 @sa bt_event_class_set_specific_context_field_class() &mdash;
857 Sets the specific context field class of an event class.
858 @sa bt_event_class_borrow_specific_context_field_class_const() &mdash;
859 \c const version of this function.
860 */
861 extern bt_field_class *
862 bt_event_class_borrow_specific_context_field_class(bt_event_class *event_class);
863
864 /*!
865 @brief
866 Borrows the specific context \bt_fc from the event class
867 \bt_p{event_class} (\c const version).
868
869 See bt_event_class_borrow_specific_context_field_class().
870 */
871 extern const bt_field_class *
872 bt_event_class_borrow_specific_context_field_class_const(
873 const bt_event_class *event_class);
874
875 /*!
876 @brief
877 Sets the user attributes of the event class \bt_p{event_class} to
878 \bt_p{user_attributes}.
879
880 See the \ref api-tir-ev-cls-prop-user-attrs "user attributes" property.
881
882 @note
883 When you create a default event class with bt_event_class_create()
884 or bt_event_class_create_with_id(), the event class's initial user
885 attributes is an empty \bt_map_val. Therefore you can borrow it with
886 bt_event_class_borrow_user_attributes() and fill it directly instead
887 of setting a new one with this function.
888
889 @param[in] event_class
890 Event class of which to set the user attributes to
891 \bt_p{user_attributes}.
892 @param[in] user_attributes
893 New user attributes of \bt_p{event_class}.
894
895 @bt_pre_not_null{event_class}
896 @bt_pre_hot{event_class}
897 @bt_pre_not_null{user_attributes}
898 @bt_pre_is_map_val{user_attributes}
899
900 @sa bt_event_class_borrow_user_attributes() &mdash;
901 Borrows the user attributes of an event class.
902 */
903 extern void bt_event_class_set_user_attributes(
904 bt_event_class *event_class, const bt_value *user_attributes);
905
906 /*!
907 @brief
908 Borrows the user attributes of the event class \bt_p{event_class}.
909
910 See the \ref api-tir-ev-cls-prop-user-attrs "user attributes" property.
911
912 @note
913 When you create a default event class with bt_event_class_create()
914 or bt_event_class_create_with_id(), the event class's initial user
915 attributes is an empty \bt_map_val.
916
917 @param[in] event_class
918 Event class from which to borrow the user attributes.
919
920 @returns
921 User attributes of \bt_p{event_class} (a \bt_map_val).
922
923 @bt_pre_not_null{event_class}
924
925 @sa bt_event_class_set_user_attributes() &mdash;
926 Sets the user attributes of an event class.
927 @sa bt_event_class_borrow_user_attributes_const() &mdash;
928 \c const version of this function.
929 */
930 extern bt_value *bt_event_class_borrow_user_attributes(
931 bt_event_class *event_class);
932
933 /*!
934 @brief
935 Borrows the user attributes of the event class \bt_p{event_class}
936 (\c const version).
937
938 See bt_event_class_borrow_user_attributes().
939 */
940 extern const bt_value *bt_event_class_borrow_user_attributes_const(
941 const bt_event_class *event_class);
942
943 /*! @} */
944
945 /*!
946 @name Reference count
947 @{
948 */
949
950 /*!
951 @brief
952 Increments the \ref api-fund-shared-object "reference count" of
953 the event class \bt_p{event_class}.
954
955 @param[in] event_class
956 @parblock
957 Event class of which to increment the reference count.
958
959 Can be \c NULL.
960 @endparblock
961
962 @sa bt_event_class_put_ref() &mdash;
963 Decrements the reference count of an event class.
964 */
965 extern void bt_event_class_get_ref(const bt_event_class *event_class);
966
967 /*!
968 @brief
969 Decrements the \ref api-fund-shared-object "reference count" of
970 the event class \bt_p{event_class}.
971
972 @param[in] event_class
973 @parblock
974 Event class of which to decrement the reference count.
975
976 Can be \c NULL.
977 @endparblock
978
979 @sa bt_event_class_get_ref() &mdash;
980 Increments the reference count of an event class.
981 */
982 extern void bt_event_class_put_ref(const bt_event_class *event_class);
983
984 /*!
985 @brief
986 Decrements the reference count of the event class
987 \bt_p{_event_class}, and then sets \bt_p{_event_class} to \c NULL.
988
989 @param _event_class
990 @parblock
991 Event class of which to decrement the reference count.
992
993 Can contain \c NULL.
994 @endparblock
995
996 @bt_pre_assign_expr{_event_class}
997 */
998 #define BT_EVENT_CLASS_PUT_REF_AND_RESET(_event_class) \
999 do { \
1000 bt_event_class_put_ref(_event_class); \
1001 (_event_class) = NULL; \
1002 } while (0)
1003
1004 /*!
1005 @brief
1006 Decrements the reference count of the event class \bt_p{_dst}, sets
1007 \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL.
1008
1009 This macro effectively moves an event class reference from the expression
1010 \bt_p{_src} to the expression \bt_p{_dst}, putting the existing
1011 \bt_p{_dst} reference.
1012
1013 @param _dst
1014 @parblock
1015 Destination expression.
1016
1017 Can contain \c NULL.
1018 @endparblock
1019 @param _src
1020 @parblock
1021 Source expression.
1022
1023 Can contain \c NULL.
1024 @endparblock
1025
1026 @bt_pre_assign_expr{_dst}
1027 @bt_pre_assign_expr{_src}
1028 */
1029 #define BT_EVENT_CLASS_MOVE_REF(_dst, _src) \
1030 do { \
1031 bt_event_class_put_ref(_dst); \
1032 (_dst) = (_src); \
1033 (_src) = NULL; \
1034 } while (0)
1035
1036 /*! @} */
1037
1038 /*! @} */
1039
1040 #ifdef __cplusplus
1041 }
1042 #endif
1043
1044 #endif /* BABELTRACE2_TRACE_IR_EVENT_CLASS_H */
This page took 0.060904 seconds and 4 git commands to generate.