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