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