Commit | Line | Data |
---|---|---|
fc11e32c | 1 | /* |
0235b0db | 2 | * SPDX-License-Identifier: MIT |
fc11e32c | 3 | * |
0235b0db | 4 | * Copyright (C) 2010-2019 EfficiOS Inc. and Linux Foundation |
fc11e32c JG |
5 | */ |
6 | ||
0235b0db MJ |
7 | #ifndef BABELTRACE2_GRAPH_COMPONENT_CLASS_H |
8 | #define BABELTRACE2_GRAPH_COMPONENT_CLASS_H | |
9 | ||
4fa90f32 PP |
10 | #ifndef __BT_IN_BABELTRACE_H |
11 | # error "Please include <babeltrace2/babeltrace.h> instead." | |
12 | #endif | |
13 | ||
3fadfbc0 | 14 | #include <babeltrace2/types.h> |
b19ff26f | 15 | |
fc11e32c JG |
16 | #ifdef __cplusplus |
17 | extern "C" { | |
18 | #endif | |
19 | ||
43c59509 PP |
20 | /*! |
21 | @defgroup api-comp-cls Component classes | |
22 | @ingroup api-graph | |
23 | ||
24 | @brief | |
25 | Source, filter, and sink component classes (non-development). | |
26 | ||
27 | A <strong><em>component class</em></strong> is the class of a \bt_comp: | |
28 | ||
29 | @image html component.png | |
30 | ||
31 | @attention | |
32 | This module (component class API) offers basic, read-only functions | |
33 | to get component class properties. To \em create a component class, | |
34 | see \ref api-comp-cls-dev or \ref api-plugin-dev. | |
35 | ||
36 | You can instantiate a given component class many times, with different | |
37 | initialization parameters, to create many components with the | |
38 | <code>bt_graph_add_*_component*()</code> functions (see \ref api-graph). | |
39 | ||
40 | There are two ways to obtain a component class: | |
41 | ||
42 | - Create one programatically: see \ref api-comp-cls-dev. | |
43 | ||
44 | - Borrow one from a \bt_plugin. | |
45 | ||
46 | Note that, as of \bt_name_version_min_maj, you cannot access a | |
47 | component class's plugin, if any. | |
48 | ||
49 | A component class is a \ref api-fund-shared-object "shared object": get | |
50 | a new reference with bt_component_class_get_ref() and put an existing | |
51 | reference with bt_component_class_put_ref(). | |
52 | ||
53 | The common C type of a component class is #bt_component_class. | |
54 | ||
55 | There are three types of component classes: | |
56 | ||
57 | <dl> | |
58 | <dt>\anchor api-comp-cls-src Source component class</dt> | |
59 | <dd> | |
60 | A source component class instance (a \bt_src_comp) \bt_msg_iter | |
61 | emits fresh \bt_p_msg. | |
62 | ||
63 | A source component class's specific type is | |
64 | #bt_component_class_source and its type enumerator is | |
65 | #BT_COMPONENT_CLASS_TYPE_SOURCE. | |
66 | ||
67 | \ref api-fund-c-typing "Upcast" the #bt_component_class_source type | |
68 | to the #bt_component_class type with | |
69 | bt_component_class_source_as_component_class_const(). | |
70 | ||
71 | Get a new source component class reference with Use | |
72 | bt_component_class_source_get_ref() and put an existing one with | |
73 | bt_component_class_source_put_ref(). | |
74 | </dd> | |
75 | ||
76 | <dt>\anchor api-comp-cls-flt Filter component class</dt> | |
77 | <dd> | |
78 | A filter component class instance (a \bt_flt_comp) message iterator | |
79 | emits fresh and transformed messages. It can also discard | |
80 | existing messages. | |
81 | ||
82 | A filter component class's specific type is | |
83 | #bt_component_class_filter and its type enumerator is | |
84 | #BT_COMPONENT_CLASS_TYPE_FILTER. | |
85 | ||
86 | \ref api-fund-c-typing "Upcast" the #bt_component_class_filter type | |
87 | to the #bt_component_class type with | |
88 | bt_component_class_filter_as_component_class_const(). | |
89 | ||
90 | Get a new filter component class reference with | |
91 | bt_component_class_filter_get_ref() and put an existing one with | |
92 | bt_component_class_filter_put_ref(). | |
93 | </dd> | |
94 | ||
95 | <dt>\anchor api-comp-cls-sink Sink component class</dt> | |
96 | <dd> | |
97 | A sink component class instance (a \bt_sink_comp) consumes messages | |
98 | from a source or filter message iterator. | |
99 | ||
100 | A filter component class's specific type is #bt_component_class_sink | |
101 | and its type enumerator is #BT_COMPONENT_CLASS_TYPE_SINK. | |
102 | ||
103 | \ref api-fund-c-typing "Upcast" the #bt_component_class_sink type to | |
104 | the #bt_component_class type with | |
105 | bt_component_class_sink_as_component_class_const(). | |
106 | ||
107 | Get a new sink component class reference with | |
108 | bt_component_class_sink_get_ref() and put an existing one with | |
109 | bt_component_class_sink_put_ref(). | |
110 | </dd> | |
111 | </dl> | |
112 | ||
113 | Get a component's class type enumerator with | |
114 | bt_component_class_get_type(). You can also use the | |
115 | bt_component_class_is_source(), bt_component_class_is_filter(), and | |
116 | bt_component_class_is_sink() helper functions. | |
117 | ||
118 | <h1>Properties</h1> | |
119 | ||
120 | A component class has the following common properties: | |
121 | ||
122 | <dl> | |
123 | <dt> | |
124 | \anchor api-comp-cls-prop-name | |
125 | Name | |
126 | </dt> | |
127 | <dd> | |
128 | Name of the component class. | |
129 | ||
130 | Within a \bt_plugin, for a given component class type, each | |
131 | component class has a unique name. | |
132 | ||
133 | Get a component class's name with bt_component_class_get_name(). | |
134 | </dd> | |
135 | ||
136 | <dt> | |
137 | \anchor api-comp-cls-prop-descr | |
138 | \bt_dt_opt Description | |
139 | </dt> | |
140 | <dd> | |
141 | Textual description of the component class. | |
142 | ||
143 | Get a component class's description with | |
144 | bt_component_class_get_description(). | |
145 | </dd> | |
146 | ||
147 | <dt> | |
148 | \anchor api-comp-cls-prop-help | |
149 | \bt_dt_opt Help text | |
150 | </dt> | |
151 | <dd> | |
152 | Help text of the component class. | |
153 | ||
154 | Get a component class's help text with | |
155 | bt_component_class_get_help(). | |
156 | </dd> | |
157 | </dl> | |
158 | */ | |
159 | ||
160 | /*! @{ */ | |
161 | ||
162 | /*! | |
163 | @name Types | |
164 | @{ | |
165 | ||
166 | @typedef struct bt_component_class bt_component_class; | |
167 | ||
168 | @brief | |
169 | Component class. | |
170 | ||
171 | @typedef struct bt_component_class_source bt_component_class_source; | |
172 | ||
173 | @brief | |
174 | \bt_c_src_comp_cls. | |
175 | ||
176 | @typedef struct bt_component_class_filter bt_component_class_filter; | |
177 | ||
178 | @brief | |
179 | \bt_c_flt_comp_cls. | |
180 | ||
181 | @typedef struct bt_component_class_sink bt_component_class_sink; | |
182 | ||
183 | @brief | |
184 | \bt_c_sink_comp_cls. | |
185 | ||
186 | @} | |
187 | */ | |
188 | ||
189 | /*! | |
190 | @name Type query | |
191 | @{ | |
192 | */ | |
193 | ||
194 | /*! | |
195 | @brief | |
196 | Component class type enumerators. | |
197 | */ | |
198 | typedef enum bt_component_class_type { | |
199 | /*! | |
200 | @brief | |
201 | \bt_c_src_comp_cls. | |
202 | */ | |
203 | BT_COMPONENT_CLASS_TYPE_SOURCE = 1 << 0, | |
204 | ||
205 | /*! | |
206 | @brief | |
207 | \bt_c_flt_comp_cls. | |
208 | */ | |
209 | BT_COMPONENT_CLASS_TYPE_FILTER = 1 << 1, | |
210 | ||
211 | /*! | |
212 | @brief | |
213 | \bt_c_sink_comp_cls. | |
214 | */ | |
215 | BT_COMPONENT_CLASS_TYPE_SINK = 1 << 2, | |
216 | } bt_component_class_type; | |
217 | ||
218 | /*! | |
219 | @brief | |
220 | Returns the type enumerator of the component class | |
221 | \bt_p{component_class}. | |
222 | ||
223 | @param[in] component_class | |
224 | Component class of which to get the type enumerator. | |
225 | ||
226 | @returns | |
227 | Type enumerator of \bt_p{component_class}. | |
228 | ||
229 | @bt_pre_not_null{component_class} | |
230 | ||
231 | @sa bt_component_class_is_source() — | |
232 | Returns whether or not a component class is a \bt_src_comp_cls. | |
233 | @sa bt_component_class_is_filter() — | |
234 | Returns whether or not a component class is a \bt_flt_comp_cls. | |
235 | @sa bt_component_class_is_sink() — | |
236 | Returns whether or not a component class is a \bt_sink_comp_cls. | |
237 | */ | |
238 | extern bt_component_class_type bt_component_class_get_type( | |
239 | const bt_component_class *component_class); | |
240 | ||
241 | /*! | |
242 | @brief | |
243 | Returns whether or not the component class \bt_p{component_class} | |
244 | is a \bt_src_comp_cls. | |
245 | ||
246 | @param[in] component_class | |
247 | Component class to check. | |
248 | ||
249 | @returns | |
250 | #BT_TRUE if \bt_p{component_class} is a source component class. | |
251 | ||
252 | @bt_pre_not_null{component_class} | |
253 | ||
254 | @sa bt_component_class_get_type() — | |
255 | Returns the type enumerator of a component class. | |
256 | */ | |
257 | static inline | |
258 | bt_bool bt_component_class_is_source( | |
259 | const bt_component_class *component_class) | |
260 | { | |
261 | return bt_component_class_get_type(component_class) == | |
262 | BT_COMPONENT_CLASS_TYPE_SOURCE; | |
263 | } | |
264 | ||
265 | /*! | |
266 | @brief | |
267 | Returns whether or not the component class \bt_p{component_class} | |
268 | is a \bt_flt_comp_cls. | |
269 | ||
270 | @param[in] component_class | |
271 | Component class to check. | |
272 | ||
273 | @returns | |
274 | #BT_TRUE if \bt_p{component_class} is a filter component class. | |
275 | ||
276 | @bt_pre_not_null{component_class} | |
277 | ||
278 | @sa bt_component_class_get_type() — | |
279 | Returns the type enumerator of a component class. | |
280 | */ | |
281 | static inline | |
282 | bt_bool bt_component_class_is_filter( | |
283 | const bt_component_class *component_class) | |
284 | { | |
285 | return bt_component_class_get_type(component_class) == | |
286 | BT_COMPONENT_CLASS_TYPE_FILTER; | |
287 | } | |
288 | ||
289 | /*! | |
290 | @brief | |
291 | Returns whether or not the component class \bt_p{component_class} | |
292 | is a \bt_sink_comp_cls. | |
293 | ||
294 | @param[in] component_class | |
295 | Component class to check. | |
296 | ||
297 | @returns | |
298 | #BT_TRUE if \bt_p{component_class} is a sink component class. | |
299 | ||
300 | @bt_pre_not_null{component_class} | |
301 | ||
302 | @sa bt_component_class_get_type() — | |
303 | Returns the type enumerator of a component class. | |
304 | */ | |
305 | static inline | |
306 | bt_bool bt_component_class_is_sink( | |
307 | const bt_component_class *component_class) | |
308 | { | |
309 | return bt_component_class_get_type(component_class) == | |
310 | BT_COMPONENT_CLASS_TYPE_SINK; | |
311 | } | |
312 | ||
313 | /*! @} */ | |
314 | ||
315 | /*! | |
316 | @name Properties | |
317 | @{ | |
318 | */ | |
319 | ||
320 | /*! | |
321 | @brief | |
322 | Returns the name of the component class \bt_p{component_class}. | |
323 | ||
324 | See the \ref api-comp-cls-prop-name "name" property. | |
325 | ||
326 | @param[in] component_class | |
327 | Component class of which to get the name. | |
328 | ||
329 | @returns | |
330 | @parblock | |
331 | Name of \bt_p{component_class}. | |
332 | ||
333 | The returned pointer remains valid as long as \bt_p{component_class} | |
334 | exists. | |
335 | @endparblock | |
336 | ||
337 | @bt_pre_not_null{component_class} | |
338 | */ | |
339 | extern const char *bt_component_class_get_name( | |
340 | const bt_component_class *component_class); | |
341 | ||
342 | /*! | |
343 | @brief | |
344 | Returns the description of the component class | |
345 | \bt_p{component_class}. | |
346 | ||
347 | See the \ref api-comp-cls-prop-descr "description" property. | |
348 | ||
349 | @param[in] component_class | |
350 | Component class of which to get the description. | |
351 | ||
352 | @returns | |
353 | @parblock | |
354 | Description of \bt_p{component_class}, or \c NULL if none. | |
355 | ||
356 | The returned pointer remains valid as long as \bt_p{component_class} | |
357 | exists. | |
358 | @endparblock | |
359 | ||
360 | @bt_pre_not_null{component_class} | |
361 | */ | |
362 | extern const char *bt_component_class_get_description( | |
363 | const bt_component_class *component_class); | |
364 | ||
365 | /*! | |
366 | @brief | |
367 | Returns the help text of the component class \bt_p{component_class}. | |
368 | ||
369 | See the \ref api-comp-cls-prop-help "help text" property. | |
370 | ||
371 | @param[in] component_class | |
372 | Component class of which to get the help text. | |
373 | ||
374 | @returns | |
375 | @parblock | |
376 | Help text of \bt_p{component_class}, or \c NULL if none. | |
377 | ||
378 | The returned pointer remains valid as long as \bt_p{component_class} | |
379 | exists. | |
380 | @endparblock | |
381 | ||
382 | @bt_pre_not_null{component_class} | |
383 | */ | |
384 | extern const char *bt_component_class_get_help( | |
385 | const bt_component_class *component_class); | |
386 | ||
387 | /*! @} */ | |
388 | ||
389 | /*! | |
390 | @name Common reference count | |
391 | @{ | |
392 | */ | |
393 | ||
394 | /*! | |
395 | @brief | |
396 | Increments the \ref api-fund-shared-object "reference count" of | |
397 | the component class \bt_p{component_class}. | |
398 | ||
399 | @param[in] component_class | |
400 | @parblock | |
401 | Component class of which to increment the reference count. | |
402 | ||
403 | Can be \c NULL. | |
404 | @endparblock | |
405 | ||
406 | @sa bt_component_put_ref() — | |
407 | Decrements the reference count of a component class. | |
408 | */ | |
409 | extern void bt_component_class_get_ref( | |
410 | const bt_component_class *component_class); | |
411 | ||
412 | /*! | |
413 | @brief | |
414 | Decrements the \ref api-fund-shared-object "reference count" of | |
415 | the component class \bt_p{component_class}. | |
416 | ||
417 | @param[in] component_class | |
418 | @parblock | |
419 | Component class of which to decrement the reference count. | |
420 | ||
421 | Can be \c NULL. | |
422 | @endparblock | |
423 | ||
424 | @sa bt_component_get_ref() — | |
425 | Increments the reference count of a component class. | |
426 | */ | |
427 | extern void bt_component_class_put_ref( | |
428 | const bt_component_class *component_class); | |
429 | ||
430 | /*! | |
431 | @brief | |
432 | Decrements the reference count of the component class | |
433 | \bt_p{_component_class}, and then sets \bt_p{_component_class} | |
434 | to \c NULL. | |
435 | ||
436 | @param _component_class | |
437 | @parblock | |
438 | Component class of which to decrement the reference count. | |
439 | ||
440 | Can contain \c NULL. | |
441 | @endparblock | |
442 | ||
443 | @bt_pre_assign_expr{_component_class} | |
444 | */ | |
445 | #define BT_COMPONENT_CLASS_PUT_REF_AND_RESET(_component_class) \ | |
446 | do { \ | |
447 | bt_component_class_put_ref(_component_class); \ | |
448 | (_component_class) = NULL; \ | |
449 | } while (0) | |
450 | ||
451 | /*! | |
452 | @brief | |
453 | Decrements the reference count of the component class \bt_p{_dst}, | |
454 | sets \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} | |
455 | to \c NULL. | |
456 | ||
457 | This macro effectively moves a component class reference from the | |
458 | expression | |
459 | \bt_p{_src} to the expression \bt_p{_dst}, putting the existing | |
460 | \bt_p{_dst} reference. | |
461 | ||
462 | @param _dst | |
463 | @parblock | |
464 | Destination expression. | |
465 | ||
466 | Can contain \c NULL. | |
467 | @endparblock | |
468 | @param _src | |
469 | @parblock | |
470 | Source expression. | |
471 | ||
472 | Can contain \c NULL. | |
473 | @endparblock | |
474 | ||
475 | @bt_pre_assign_expr{_dst} | |
476 | @bt_pre_assign_expr{_src} | |
477 | */ | |
478 | #define BT_COMPONENT_CLASS_MOVE_REF(_dst, _src) \ | |
479 | do { \ | |
480 | bt_component_class_put_ref(_dst); \ | |
481 | (_dst) = (_src); \ | |
482 | (_src) = NULL; \ | |
483 | } while (0) | |
484 | ||
485 | /*! @} */ | |
486 | ||
487 | /*! | |
488 | @name Source component class upcast | |
489 | @{ | |
490 | */ | |
491 | ||
492 | /*! | |
493 | @brief | |
494 | \ref api-fund-c-typing "Upcasts" the \bt_src_comp_cls | |
495 | \bt_p{component_class} to the common #bt_component_class type. | |
496 | ||
497 | @param[in] component_class | |
498 | @parblock | |
499 | Source component class to upcast. | |
500 | ||
501 | Can be \c NULL. | |
502 | @endparblock | |
503 | ||
504 | @returns | |
505 | \bt_p{component_class} as a common component class. | |
506 | */ | |
507 | static inline | |
508 | const bt_component_class * | |
509 | bt_component_class_source_as_component_class_const( | |
510 | const bt_component_class_source *component_class) | |
511 | { | |
512 | return __BT_UPCAST_CONST(bt_component_class, component_class); | |
513 | } | |
514 | ||
515 | /*! @} */ | |
516 | ||
517 | /*! | |
518 | @name Source component class reference count | |
519 | @{ | |
520 | */ | |
521 | ||
522 | /*! | |
523 | @brief | |
524 | Increments the \ref api-fund-shared-object "reference count" of | |
525 | the \bt_src_comp_cls \bt_p{component_class}. | |
526 | ||
527 | @param[in] component_class | |
528 | @parblock | |
529 | Source component class of which to increment the reference count. | |
530 | ||
531 | Can be \c NULL. | |
532 | @endparblock | |
533 | ||
534 | @sa bt_component_class_source_put_ref() — | |
535 | Decrements the reference count of a source component class. | |
536 | */ | |
537 | extern void bt_component_class_source_get_ref( | |
538 | const bt_component_class_source *component_class); | |
539 | ||
540 | /*! | |
541 | @brief | |
542 | Decrements the \ref api-fund-shared-object "reference count" of | |
543 | the \bt_src_comp_cls \bt_p{component_class}. | |
544 | ||
545 | @param[in] component_class | |
546 | @parblock | |
547 | Source component class of which to decrement the reference count. | |
548 | ||
549 | Can be \c NULL. | |
550 | @endparblock | |
551 | ||
552 | @sa bt_component_class_source_get_ref() — | |
553 | Increments the reference count of a source component class. | |
554 | */ | |
555 | extern void bt_component_class_source_put_ref( | |
556 | const bt_component_class_source *component_class); | |
557 | ||
558 | /*! | |
559 | @brief | |
560 | Decrements the reference count of the \bt_src_comp_cls | |
561 | \bt_p{_component_class}, and then sets \bt_p{_component_class} to | |
562 | \c NULL. | |
563 | ||
564 | @param _component_class | |
565 | @parblock | |
566 | Source component class of which to decrement the reference count. | |
567 | ||
568 | Can contain \c NULL. | |
569 | @endparblock | |
570 | ||
571 | @bt_pre_assign_expr{_component_class} | |
572 | */ | |
573 | #define BT_COMPONENT_CLASS_SOURCE_PUT_REF_AND_RESET(_component_class) \ | |
574 | do { \ | |
575 | bt_component_class_source_put_ref(_component_class); \ | |
576 | (_component_class) = NULL; \ | |
577 | } while (0) | |
578 | ||
579 | /*! | |
580 | @brief | |
581 | Decrements the reference count of the \bt_src_comp_cls \bt_p{_dst}, | |
582 | sets \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to | |
583 | \c NULL. | |
584 | ||
585 | This macro effectively moves a source component class reference from the | |
586 | expression \bt_p{_src} to the expression \bt_p{_dst}, putting the | |
587 | existing \bt_p{_dst} reference. | |
588 | ||
589 | @param _dst | |
590 | @parblock | |
591 | Destination expression. | |
592 | ||
593 | Can contain \c NULL. | |
594 | @endparblock | |
595 | @param _src | |
596 | @parblock | |
597 | Source expression. | |
598 | ||
599 | Can contain \c NULL. | |
600 | @endparblock | |
601 | ||
602 | @bt_pre_assign_expr{_dst} | |
603 | @bt_pre_assign_expr{_src} | |
604 | */ | |
605 | #define BT_COMPONENT_CLASS_SOURCE_MOVE_REF(_dst, _src) \ | |
606 | do { \ | |
607 | bt_component_class_source_put_ref(_dst); \ | |
608 | (_dst) = (_src); \ | |
609 | (_src) = NULL; \ | |
610 | } while (0) | |
611 | ||
612 | /*! @} */ | |
613 | ||
614 | /*! | |
615 | @name Filter component class upcast | |
616 | @{ | |
617 | */ | |
618 | ||
619 | /*! | |
620 | @brief | |
621 | \ref api-fund-c-typing "Upcasts" the \bt_flt_comp_cls | |
622 | \bt_p{component_class} to the common #bt_component_class type. | |
623 | ||
624 | @param[in] component_class | |
625 | @parblock | |
626 | Filter component class to upcast. | |
627 | ||
628 | Can be \c NULL. | |
629 | @endparblock | |
630 | ||
631 | @returns | |
632 | \bt_p{component_class} as a common component class. | |
633 | */ | |
634 | static inline | |
635 | const bt_component_class * | |
636 | bt_component_class_filter_as_component_class_const( | |
637 | const bt_component_class_filter *component_class) | |
638 | { | |
639 | return __BT_UPCAST_CONST(bt_component_class, component_class); | |
640 | } | |
641 | ||
642 | /*! @} */ | |
643 | ||
644 | /*! | |
645 | @name Filter component class reference count | |
646 | @{ | |
647 | */ | |
648 | ||
649 | /*! | |
650 | @brief | |
651 | Increments the \ref api-fund-shared-object "reference count" of | |
652 | the \bt_flt_comp_cls \bt_p{component_class}. | |
653 | ||
654 | @param[in] component_class | |
655 | @parblock | |
656 | Filter component class of which to increment the reference count. | |
657 | ||
658 | Can be \c NULL. | |
659 | @endparblock | |
660 | ||
661 | @sa bt_component_class_filter_put_ref() — | |
662 | Decrements the reference count of a filter component class. | |
663 | */ | |
664 | extern void bt_component_class_filter_get_ref( | |
665 | const bt_component_class_filter *component_class); | |
666 | ||
667 | /*! | |
668 | @brief | |
669 | Decrements the \ref api-fund-shared-object "reference count" of | |
670 | the \bt_flt_comp_cls \bt_p{component_class}. | |
671 | ||
672 | @param[in] component_class | |
673 | @parblock | |
674 | Filter component class of which to decrement the reference count. | |
675 | ||
676 | Can be \c NULL. | |
677 | @endparblock | |
678 | ||
679 | @sa bt_component_class_filter_get_ref() — | |
680 | Increments the reference count of a filter component class. | |
681 | */ | |
682 | extern void bt_component_class_filter_put_ref( | |
683 | const bt_component_class_filter *component_class); | |
684 | ||
685 | /*! | |
686 | @brief | |
687 | Decrements the reference count of the \bt_flt_comp_cls | |
688 | \bt_p{_component_class}, and then sets \bt_p{_component_class} to | |
689 | \c NULL. | |
690 | ||
691 | @param _component_class | |
692 | @parblock | |
693 | Filter component class of which to decrement the reference count. | |
694 | ||
695 | Can contain \c NULL. | |
696 | @endparblock | |
697 | ||
698 | @bt_pre_assign_expr{_component_class} | |
699 | */ | |
700 | #define BT_COMPONENT_CLASS_FILTER_PUT_REF_AND_RESET(_component_class) \ | |
701 | do { \ | |
702 | bt_component_class_filter_put_ref(_component_class); \ | |
703 | (_component_class) = NULL; \ | |
704 | } while (0) | |
705 | ||
706 | /*! | |
707 | @brief | |
708 | Decrements the reference count of the \bt_flt_comp_cls \bt_p{_dst}, | |
709 | setsc \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to | |
710 | \c NULL. | |
711 | ||
712 | This macro effectively moves a filter component class reference from the | |
713 | expression \bt_p{_src} to the expression \bt_p{_dst}, putting the | |
714 | existing \bt_p{_dst} reference. | |
715 | ||
716 | @param _dst | |
717 | @parblock | |
718 | Destination expression. | |
719 | ||
720 | Can contain \c NULL. | |
721 | @endparblock | |
722 | @param _src | |
723 | @parblock | |
724 | Source expression. | |
725 | ||
726 | Can contain \c NULL. | |
727 | @endparblock | |
728 | ||
729 | @bt_pre_assign_expr{_dst} | |
730 | @bt_pre_assign_expr{_src} | |
731 | */ | |
732 | #define BT_COMPONENT_CLASS_FILTER_MOVE_REF(_dst, _src) \ | |
733 | do { \ | |
734 | bt_component_class_filter_put_ref(_dst); \ | |
735 | (_dst) = (_src); \ | |
736 | (_src) = NULL; \ | |
737 | } while (0) | |
738 | ||
739 | /*! @} */ | |
740 | ||
741 | /*! | |
742 | @name Sink component class upcast | |
743 | @{ | |
744 | */ | |
745 | ||
746 | /*! | |
747 | @brief | |
748 | \ref api-fund-c-typing "Upcasts" the \bt_sink_comp_cls | |
749 | \bt_p{component_class} to the common #bt_component_class type. | |
750 | ||
751 | @param[in] component_class | |
752 | @parblock | |
753 | Sink component class to upcast. | |
754 | ||
755 | Can be \c NULL. | |
756 | @endparblock | |
757 | ||
758 | @returns | |
759 | \bt_p{component_class} as a common component class. | |
760 | */ | |
761 | static inline | |
762 | const bt_component_class * | |
763 | bt_component_class_sink_as_component_class_const( | |
764 | const bt_component_class_sink *component_class) | |
765 | { | |
766 | return __BT_UPCAST_CONST(bt_component_class, component_class); | |
767 | } | |
768 | ||
769 | /*! @} */ | |
770 | ||
771 | /*! | |
772 | @name Sink component class reference count | |
773 | @{ | |
774 | */ | |
775 | ||
776 | /*! | |
777 | @brief | |
778 | Increments the \ref api-fund-shared-object "reference count" of | |
779 | the \bt_sink_comp_cls \bt_p{component_class}. | |
780 | ||
781 | @param[in] component_class | |
782 | @parblock | |
783 | Sink component class of which to increment the reference count. | |
784 | ||
785 | Can be \c NULL. | |
786 | @endparblock | |
787 | ||
788 | @sa bt_component_class_sink_put_ref() — | |
789 | Decrements the reference count of a sink component class. | |
790 | */ | |
791 | extern void bt_component_class_sink_get_ref( | |
792 | const bt_component_class_sink *component_class); | |
793 | ||
794 | /*! | |
795 | @brief | |
796 | Decrements the \ref api-fund-shared-object "reference count" of | |
797 | the \bt_sink_comp_cls \bt_p{component_class}. | |
798 | ||
799 | @param[in] component_class | |
800 | @parblock | |
801 | Sink component class of which to decrement the reference count. | |
802 | ||
803 | Can be \c NULL. | |
804 | @endparblock | |
805 | ||
806 | @sa bt_component_class_sink_get_ref() — | |
807 | Increments the reference count of a sink component class. | |
808 | */ | |
809 | extern void bt_component_class_sink_put_ref( | |
810 | const bt_component_class_sink *component_class); | |
811 | ||
812 | /*! | |
813 | @brief | |
814 | Decrements the reference count of the \bt_sink_comp_cls | |
815 | \bt_p{_component_class}, and then sets \bt_p{_component_class} to | |
816 | \c NULL. | |
817 | ||
818 | @param _component_class | |
819 | @parblock | |
820 | Sink component class of which to decrement the reference count. | |
821 | ||
822 | Can contain \c NULL. | |
823 | @endparblock | |
824 | ||
825 | @bt_pre_assign_expr{_component_class} | |
826 | */ | |
827 | #define BT_COMPONENT_CLASS_SINK_PUT_REF_AND_RESET(_component_class) \ | |
828 | do { \ | |
829 | bt_component_class_sink_put_ref(_component_class); \ | |
830 | (_component_class) = NULL; \ | |
831 | } while (0) | |
832 | ||
833 | /*! | |
834 | @brief | |
835 | Decrements the reference count of the \bt_sink_comp_cls \bt_p{_dst}, | |
836 | sets \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to | |
837 | \c NULL. | |
838 | ||
839 | This macro effectively moves a sink component class reference from the | |
840 | expression \bt_p{_src} to the expression \bt_p{_dst}, putting the | |
841 | existing \bt_p{_dst} reference. | |
842 | ||
843 | @param _dst | |
844 | @parblock | |
845 | Destination expression. | |
846 | ||
847 | Can contain \c NULL. | |
848 | @endparblock | |
849 | @param _src | |
850 | @parblock | |
851 | Source expression. | |
852 | ||
853 | Can contain \c NULL. | |
854 | @endparblock | |
855 | ||
856 | @bt_pre_assign_expr{_dst} | |
857 | @bt_pre_assign_expr{_src} | |
858 | */ | |
859 | #define BT_COMPONENT_CLASS_SINK_MOVE_REF(_dst, _src) \ | |
860 | do { \ | |
861 | bt_component_class_sink_put_ref(_dst); \ | |
862 | (_dst) = (_src); \ | |
863 | (_src) = NULL; \ | |
864 | } while (0) | |
865 | ||
866 | /*! @} */ | |
867 | ||
868 | /*! @} */ | |
2154eb7d | 869 | |
d3e4dcd8 PP |
870 | #ifdef __cplusplus |
871 | } | |
872 | #endif | |
873 | ||
924dc299 | 874 | #endif /* BABELTRACE2_GRAPH_COMPONENT_CLASS_H */ |