Commit | Line | Data |
---|---|---|
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 |
35 | extern "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 | ||
45 | An <strong><em>event class</em></strong> is the class of \bt_p_ev, | |
46 | which \bt_p_ev_msg contain: | |
47 | ||
48 | @image html trace-structure.png | |
49 | ||
50 | In 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 | ||
60 | An event class is a \ref api-tir "trace IR" metadata object. | |
61 | ||
62 | An event class is a \ref api-fund-shared-object "shared object": get a | |
63 | new reference with bt_event_class_get_ref() and put an existing | |
64 | reference with bt_event_class_put_ref(). | |
65 | ||
66 | Some library functions \ref api-fund-freezing "freeze" event classes on | |
67 | success. The documentation of those functions indicate this | |
68 | postcondition. | |
69 | ||
70 | The type of an event class is #bt_event_class. | |
71 | ||
72 | A \bt_stream_cls contains event classes. All the event classes of a | |
73 | given stream class have unique | |
74 | \ref api-tir-ev-cls-prop-id "numeric IDs". Borrow the stream class | |
75 | which contains an event class with bt_event_class_borrow_stream_class() | |
76 | or bt_event_class_borrow_stream_class_const(). | |
77 | ||
78 | To 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 | ||
96 | An 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 | ||
229 | On 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() — | |
272 | Creates an event class with a specific numeric ID and adds it to a | |
273 | stream class. | |
274 | */ | |
8eee8ea2 PP |
275 | extern 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 | ||
296 | On 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() — | |
345 | Creates an event class with an automatic numeric ID and adds it to a | |
346 | stream class. | |
347 | */ | |
8eee8ea2 PP |
348 | extern 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() — | |
372 | \c const version of this function. | |
373 | */ | |
8eee8ea2 PP |
374 | extern 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 | ||
382 | See bt_event_class_borrow_stream_class(). | |
383 | */ | |
384 | extern 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 | ||
398 | See 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() — | |
409 | Creates an event class with a specific numeric ID and adds it to a | |
410 | stream class. | |
411 | */ | |
412 | extern 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 | 418 | typedef 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 | ||
437 | See 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() — | |
454 | Returns the name of an event class. | |
455 | */ | |
fb25b9e3 | 456 | extern 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 | ||
463 | See the \ref api-tir-ev-cls-prop-name "name" property. | |
464 | ||
465 | If \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() — | |
481 | Sets the name of an event class. | |
482 | */ | |
483 | extern const char *bt_event_class_get_name(const bt_event_class *event_class); | |
484 | ||
485 | /*! | |
486 | @brief | |
487 | Event class log level enumerators. | |
488 | */ | |
489 | typedef 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 | ||
591 | See 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() — | |
602 | Returns the log level of an event class. | |
603 | */ | |
ee78f405 PP |
604 | extern 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 | ||
611 | See 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() — | |
629 | Sets the log level of an event class. | |
630 | */ | |
631 | extern 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 | 639 | typedef 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 | ||
658 | See 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() — | |
675 | Returns the EMF URI of an event class. | |
676 | */ | |
fb25b9e3 | 677 | extern 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 | ||
685 | See the \ref api-tir-ev-cls-prop-emf-uri "EMF URI" property. | |
686 | ||
687 | If \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() — | |
703 | Sets the EMF URI of an event class. | |
704 | */ | |
705 | extern 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 | 713 | typedef 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 | ||
732 | See 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() — | |
761 | Borrows the payload field class of an event class. | |
762 | @sa bt_event_class_borrow_payload_field_class_const() — | |
763 | Borrows the payload field class of an event class | |
764 | (\c const version). | |
765 | */ | |
766 | extern bt_event_class_set_field_class_status | |
767 | bt_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 | ||
774 | See the \ref api-tir-ev-cls-prop-p-fc "payload field class" property. | |
775 | ||
776 | If \bt_p{event_class} has no payload field class, this function | |
777 | returns \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() — | |
789 | Sets the payload field class of an event class. | |
790 | @sa bt_event_class_borrow_payload_field_class_const() — | |
791 | \c const version of this function. | |
792 | */ | |
793 | extern 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 | ||
801 | See bt_event_class_borrow_payload_field_class(). | |
802 | */ | |
803 | extern 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 | ||
811 | See the \ref api-tir-ev-cls-prop-sc-fc "specific context field class" | |
812 | property. | |
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() — | |
841 | Borrows the specific context field class of an event class. | |
842 | @sa bt_event_class_borrow_specific_context_field_class_const() — | |
843 | Borrows the specific context field class of an event class | |
844 | (\c const version). | |
845 | */ | |
fb25b9e3 | 846 | extern bt_event_class_set_field_class_status |
4caa7d56 | 847 | bt_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 | ||
855 | See the \ref api-tir-ev-cls-prop-sc-fc "specific context field class" | |
856 | property. | |
857 | ||
858 | If \bt_p{event_class} has no specific context field class, this function | |
859 | returns \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() — | |
871 | Sets the specific context field class of an event class. | |
872 | @sa bt_event_class_borrow_specific_context_field_class_const() — | |
873 | \c const version of this function. | |
874 | */ | |
909d0a89 PP |
875 | extern bt_field_class * |
876 | bt_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 |
883 | See bt_event_class_borrow_specific_context_field_class(). |
884 | */ | |
885 | extern const bt_field_class * | |
886 | bt_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 | ||
894 | See 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() — | |
915 | Borrows the user attributes of an event class. | |
916 | */ | |
917 | extern 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 | ||
924 | See 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() — | |
940 | Sets the user attributes of an event class. | |
941 | @sa bt_event_class_borrow_user_attributes_const() — | |
942 | \c const version of this function. | |
943 | */ | |
944 | extern 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 | ||
952 | See bt_event_class_borrow_user_attributes(). | |
953 | */ | |
954 | extern 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() — | |
977 | Decrements the reference count of an event class. | |
978 | */ | |
979 | extern 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() — | |
994 | Increments the reference count of an event class. | |
995 | */ | |
996 | extern 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 | ||
1023 | This 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 */ |