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