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