2 * SPDX-License-Identifier: MIT
4 * Copyright (C) 2010-2019 EfficiOS Inc. and Linux Foundation
7 #ifndef BABELTRACE2_GRAPH_COMPONENT_CLASS_H
8 #define BABELTRACE2_GRAPH_COMPONENT_CLASS_H
10 /* IWYU pragma: private, include <babeltrace2/babeltrace.h> */
12 #ifndef __BT_IN_BABELTRACE_H
13 # error "Please include <babeltrace2/babeltrace.h> instead."
16 #include <babeltrace2/types.h>
23 @defgroup api-comp-cls Component classes
27 Source, filter, and sink component classes (non-development).
29 A <strong><em>component class</em></strong> is the class of a \bt_comp:
31 @image html component.png
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.
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).
42 There are two ways to obtain a component class:
44 - Create one programmatically: see \ref api-comp-cls-dev.
46 - Borrow one from a \bt_plugin.
48 Note that, as of \bt_name_version_min_maj, you cannot access a
49 component class's plugin, if any.
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().
55 The common C type of a component class is #bt_component_class.
57 There are three types of component classes:
60 <dt>\anchor api-comp-cls-src Source component class</dt>
62 A source component class instance (a \bt_src_comp) \bt_msg_iter
63 emits fresh \bt_p_msg.
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.
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().
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().
78 <dt>\anchor api-comp-cls-flt Filter component class</dt>
80 A filter component class instance (a \bt_flt_comp) message iterator
81 emits fresh and transformed messages. It can also discard
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.
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().
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().
97 <dt>\anchor api-comp-cls-sink Sink component class</dt>
99 A sink component class instance (a \bt_sink_comp) consumes messages
100 from a source or filter message iterator.
102 A filter component class's specific type is #bt_component_class_sink
103 and its type enumerator is #BT_COMPONENT_CLASS_TYPE_SINK.
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().
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().
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.
122 A component class has the following common properties:
126 \anchor api-comp-cls-prop-name
130 Name of the component class.
132 Within a \bt_plugin, for a given component class type, each
133 component class has a unique name.
135 Get a component class's name with bt_component_class_get_name().
139 \anchor api-comp-cls-prop-descr
140 \bt_dt_opt Description
143 Textual description of the component class.
145 Get a component class's description with
146 bt_component_class_get_description().
150 \anchor api-comp-cls-prop-help
154 Help text of the component class.
156 Get a component class's help text with
157 bt_component_class_get_help().
168 @typedef struct bt_component_class bt_component_class;
173 @typedef struct bt_component_class_source bt_component_class_source;
178 @typedef struct bt_component_class_filter bt_component_class_filter;
183 @typedef struct bt_component_class_sink bt_component_class_sink;
198 Component class type enumerators.
200 typedef enum bt_component_class_type
{
205 BT_COMPONENT_CLASS_TYPE_SOURCE
= 1 << 0,
211 BT_COMPONENT_CLASS_TYPE_FILTER
= 1 << 1,
217 BT_COMPONENT_CLASS_TYPE_SINK
= 1 << 2,
218 } bt_component_class_type
;
222 Returns the type enumerator of the component class
223 \bt_p{component_class}.
225 @param[in] component_class
226 Component class of which to get the type enumerator.
229 Type enumerator of \bt_p{component_class}.
231 @bt_pre_not_null{component_class}
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.
240 extern bt_component_class_type
bt_component_class_get_type(
241 const bt_component_class
*component_class
) __BT_NOEXCEPT
;
245 Returns whether or not the component class \bt_p{component_class}
246 is a \bt_src_comp_cls.
248 @param[in] component_class
249 Component class to check.
252 #BT_TRUE if \bt_p{component_class} is a source component class.
254 @bt_pre_not_null{component_class}
256 @sa bt_component_class_get_type() —
257 Returns the type enumerator of a component class.
260 bt_bool
bt_component_class_is_source(
261 const bt_component_class
*component_class
) __BT_NOEXCEPT
263 return bt_component_class_get_type(component_class
) ==
264 BT_COMPONENT_CLASS_TYPE_SOURCE
;
269 Returns whether or not the component class \bt_p{component_class}
270 is a \bt_flt_comp_cls.
272 @param[in] component_class
273 Component class to check.
276 #BT_TRUE if \bt_p{component_class} is a filter component class.
278 @bt_pre_not_null{component_class}
280 @sa bt_component_class_get_type() —
281 Returns the type enumerator of a component class.
284 bt_bool
bt_component_class_is_filter(
285 const bt_component_class
*component_class
) __BT_NOEXCEPT
287 return bt_component_class_get_type(component_class
) ==
288 BT_COMPONENT_CLASS_TYPE_FILTER
;
293 Returns whether or not the component class \bt_p{component_class}
294 is a \bt_sink_comp_cls.
296 @param[in] component_class
297 Component class to check.
300 #BT_TRUE if \bt_p{component_class} is a sink component class.
302 @bt_pre_not_null{component_class}
304 @sa bt_component_class_get_type() —
305 Returns the type enumerator of a component class.
308 bt_bool
bt_component_class_is_sink(
309 const bt_component_class
*component_class
) __BT_NOEXCEPT
311 return bt_component_class_get_type(component_class
) ==
312 BT_COMPONENT_CLASS_TYPE_SINK
;
324 Returns the name of the component class \bt_p{component_class}.
326 See the \ref api-comp-cls-prop-name "name" property.
328 @param[in] component_class
329 Component class of which to get the name.
333 Name of \bt_p{component_class}.
335 The returned pointer remains valid as long as \bt_p{component_class}
339 @bt_pre_not_null{component_class}
341 extern const char *bt_component_class_get_name(
342 const bt_component_class
*component_class
) __BT_NOEXCEPT
;
346 Returns the description of the component class
347 \bt_p{component_class}.
349 See the \ref api-comp-cls-prop-descr "description" property.
351 @param[in] component_class
352 Component class of which to get the description.
356 Description of \bt_p{component_class}, or \c NULL if none.
358 The returned pointer remains valid as long as \bt_p{component_class}
362 @bt_pre_not_null{component_class}
364 extern const char *bt_component_class_get_description(
365 const bt_component_class
*component_class
) __BT_NOEXCEPT
;
369 Returns the help text of the component class \bt_p{component_class}.
371 See the \ref api-comp-cls-prop-help "help text" property.
373 @param[in] component_class
374 Component class of which to get the help text.
378 Help text of \bt_p{component_class}, or \c NULL if none.
380 The returned pointer remains valid as long as \bt_p{component_class}
384 @bt_pre_not_null{component_class}
386 extern const char *bt_component_class_get_help(
387 const bt_component_class
*component_class
) __BT_NOEXCEPT
;
392 @name Common reference count
398 Increments the \ref api-fund-shared-object "reference count" of
399 the component class \bt_p{component_class}.
401 @param[in] component_class
403 Component class of which to increment the reference count.
408 @sa bt_component_put_ref() —
409 Decrements the reference count of a component class.
411 extern void bt_component_class_get_ref(
412 const bt_component_class
*component_class
) __BT_NOEXCEPT
;
416 Decrements the \ref api-fund-shared-object "reference count" of
417 the component class \bt_p{component_class}.
419 @param[in] component_class
421 Component class of which to decrement the reference count.
426 @sa bt_component_get_ref() —
427 Increments the reference count of a component class.
429 extern void bt_component_class_put_ref(
430 const bt_component_class
*component_class
) __BT_NOEXCEPT
;
434 Decrements the reference count of the component class
435 \bt_p{_component_class}, and then sets \bt_p{_component_class}
438 @param _component_class
440 Component class of which to decrement the reference count.
445 @bt_pre_assign_expr{_component_class}
447 #define BT_COMPONENT_CLASS_PUT_REF_AND_RESET(_component_class) \
449 bt_component_class_put_ref(_component_class); \
450 (_component_class) = NULL; \
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}
459 This macro effectively moves a component class reference from the
461 \bt_p{_src} to the expression \bt_p{_dst}, putting the existing
462 \bt_p{_dst} reference.
466 Destination expression.
477 @bt_pre_assign_expr{_dst}
478 @bt_pre_assign_expr{_src}
480 #define BT_COMPONENT_CLASS_MOVE_REF(_dst, _src) \
482 bt_component_class_put_ref(_dst); \
490 @name Source component class upcast
496 \ref api-fund-c-typing "Upcasts" the \bt_src_comp_cls
497 \bt_p{component_class} to the common #bt_component_class type.
499 @param[in] component_class
501 Source component class to upcast.
507 \bt_p{component_class} as a common component class.
510 const bt_component_class
*
511 bt_component_class_source_as_component_class_const(
512 const bt_component_class_source
*component_class
) __BT_NOEXCEPT
514 return __BT_UPCAST_CONST(bt_component_class
, component_class
);
520 @name Source component class reference count
526 Increments the \ref api-fund-shared-object "reference count" of
527 the \bt_src_comp_cls \bt_p{component_class}.
529 @param[in] component_class
531 Source component class of which to increment the reference count.
536 @sa bt_component_class_source_put_ref() —
537 Decrements the reference count of a source component class.
539 extern void bt_component_class_source_get_ref(
540 const bt_component_class_source
*component_class
) __BT_NOEXCEPT
;
544 Decrements the \ref api-fund-shared-object "reference count" of
545 the \bt_src_comp_cls \bt_p{component_class}.
547 @param[in] component_class
549 Source component class of which to decrement the reference count.
554 @sa bt_component_class_source_get_ref() —
555 Increments the reference count of a source component class.
557 extern void bt_component_class_source_put_ref(
558 const bt_component_class_source
*component_class
) __BT_NOEXCEPT
;
562 Decrements the reference count of the \bt_src_comp_cls
563 \bt_p{_component_class}, and then sets \bt_p{_component_class} to
566 @param _component_class
568 Source component class of which to decrement the reference count.
573 @bt_pre_assign_expr{_component_class}
575 #define BT_COMPONENT_CLASS_SOURCE_PUT_REF_AND_RESET(_component_class) \
577 bt_component_class_source_put_ref(_component_class); \
578 (_component_class) = NULL; \
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
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.
593 Destination expression.
604 @bt_pre_assign_expr{_dst}
605 @bt_pre_assign_expr{_src}
607 #define BT_COMPONENT_CLASS_SOURCE_MOVE_REF(_dst, _src) \
609 bt_component_class_source_put_ref(_dst); \
617 @name Filter component class upcast
623 \ref api-fund-c-typing "Upcasts" the \bt_flt_comp_cls
624 \bt_p{component_class} to the common #bt_component_class type.
626 @param[in] component_class
628 Filter component class to upcast.
634 \bt_p{component_class} as a common component class.
637 const bt_component_class
*
638 bt_component_class_filter_as_component_class_const(
639 const bt_component_class_filter
*component_class
) __BT_NOEXCEPT
641 return __BT_UPCAST_CONST(bt_component_class
, component_class
);
647 @name Filter component class reference count
653 Increments the \ref api-fund-shared-object "reference count" of
654 the \bt_flt_comp_cls \bt_p{component_class}.
656 @param[in] component_class
658 Filter component class of which to increment the reference count.
663 @sa bt_component_class_filter_put_ref() —
664 Decrements the reference count of a filter component class.
666 extern void bt_component_class_filter_get_ref(
667 const bt_component_class_filter
*component_class
) __BT_NOEXCEPT
;
671 Decrements the \ref api-fund-shared-object "reference count" of
672 the \bt_flt_comp_cls \bt_p{component_class}.
674 @param[in] component_class
676 Filter component class of which to decrement the reference count.
681 @sa bt_component_class_filter_get_ref() —
682 Increments the reference count of a filter component class.
684 extern void bt_component_class_filter_put_ref(
685 const bt_component_class_filter
*component_class
) __BT_NOEXCEPT
;
689 Decrements the reference count of the \bt_flt_comp_cls
690 \bt_p{_component_class}, and then sets \bt_p{_component_class} to
693 @param _component_class
695 Filter component class of which to decrement the reference count.
700 @bt_pre_assign_expr{_component_class}
702 #define BT_COMPONENT_CLASS_FILTER_PUT_REF_AND_RESET(_component_class) \
704 bt_component_class_filter_put_ref(_component_class); \
705 (_component_class) = NULL; \
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
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.
720 Destination expression.
731 @bt_pre_assign_expr{_dst}
732 @bt_pre_assign_expr{_src}
734 #define BT_COMPONENT_CLASS_FILTER_MOVE_REF(_dst, _src) \
736 bt_component_class_filter_put_ref(_dst); \
744 @name Sink component class upcast
750 \ref api-fund-c-typing "Upcasts" the \bt_sink_comp_cls
751 \bt_p{component_class} to the common #bt_component_class type.
753 @param[in] component_class
755 Sink component class to upcast.
761 \bt_p{component_class} as a common component class.
764 const bt_component_class
*
765 bt_component_class_sink_as_component_class_const(
766 const bt_component_class_sink
*component_class
) __BT_NOEXCEPT
768 return __BT_UPCAST_CONST(bt_component_class
, component_class
);
774 @name Sink component class reference count
780 Increments the \ref api-fund-shared-object "reference count" of
781 the \bt_sink_comp_cls \bt_p{component_class}.
783 @param[in] component_class
785 Sink component class of which to increment the reference count.
790 @sa bt_component_class_sink_put_ref() —
791 Decrements the reference count of a sink component class.
793 extern void bt_component_class_sink_get_ref(
794 const bt_component_class_sink
*component_class
) __BT_NOEXCEPT
;
798 Decrements the \ref api-fund-shared-object "reference count" of
799 the \bt_sink_comp_cls \bt_p{component_class}.
801 @param[in] component_class
803 Sink component class of which to decrement the reference count.
808 @sa bt_component_class_sink_get_ref() —
809 Increments the reference count of a sink component class.
811 extern void bt_component_class_sink_put_ref(
812 const bt_component_class_sink
*component_class
) __BT_NOEXCEPT
;
816 Decrements the reference count of the \bt_sink_comp_cls
817 \bt_p{_component_class}, and then sets \bt_p{_component_class} to
820 @param _component_class
822 Sink component class of which to decrement the reference count.
827 @bt_pre_assign_expr{_component_class}
829 #define BT_COMPONENT_CLASS_SINK_PUT_REF_AND_RESET(_component_class) \
831 bt_component_class_sink_put_ref(_component_class); \
832 (_component_class) = NULL; \
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
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.
847 Destination expression.
858 @bt_pre_assign_expr{_dst}
859 @bt_pre_assign_expr{_src}
861 #define BT_COMPONENT_CLASS_SINK_MOVE_REF(_dst, _src) \
863 bt_component_class_sink_put_ref(_dst); \
876 #endif /* BABELTRACE2_GRAPH_COMPONENT_CLASS_H */