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 #ifndef __BT_IN_BABELTRACE_H
11 # error "Please include <babeltrace2/babeltrace.h> instead."
14 #include <babeltrace2/types.h>
21 @defgroup api-comp-cls Component classes
25 Source, filter, and sink component classes (non-development).
27 A <strong><em>component class</em></strong> is the class of a \bt_comp:
29 @image html component.png
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.
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).
40 There are two ways to obtain a component class:
42 - Create one programatically: see \ref api-comp-cls-dev.
44 - Borrow one from a \bt_plugin.
46 Note that, as of \bt_name_version_min_maj, you cannot access a
47 component class's plugin, if any.
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().
53 The common C type of a component class is #bt_component_class.
55 There are three types of component classes:
58 <dt>\anchor api-comp-cls-src Source component class</dt>
60 A source component class instance (a \bt_src_comp) \bt_msg_iter
61 emits fresh \bt_p_msg.
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.
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().
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().
76 <dt>\anchor api-comp-cls-flt Filter component class</dt>
78 A filter component class instance (a \bt_flt_comp) message iterator
79 emits fresh and transformed messages. It can also discard
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.
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().
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().
95 <dt>\anchor api-comp-cls-sink Sink component class</dt>
97 A sink component class instance (a \bt_sink_comp) consumes messages
98 from a source or filter message iterator.
100 A filter component class's specific type is #bt_component_class_sink
101 and its type enumerator is #BT_COMPONENT_CLASS_TYPE_SINK.
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().
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().
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.
120 A component class has the following common properties:
124 \anchor api-comp-cls-prop-name
128 Name of the component class.
130 Within a \bt_plugin, for a given component class type, each
131 component class has a unique name.
133 Get a component class's name with bt_component_class_get_name().
137 \anchor api-comp-cls-prop-descr
138 \bt_dt_opt Description
141 Textual description of the component class.
143 Get a component class's description with
144 bt_component_class_get_description().
148 \anchor api-comp-cls-prop-help
152 Help text of the component class.
154 Get a component class's help text with
155 bt_component_class_get_help().
166 @typedef struct bt_component_class bt_component_class;
171 @typedef struct bt_component_class_source bt_component_class_source;
176 @typedef struct bt_component_class_filter bt_component_class_filter;
181 @typedef struct bt_component_class_sink bt_component_class_sink;
196 Component class type enumerators.
198 typedef enum bt_component_class_type
{
203 BT_COMPONENT_CLASS_TYPE_SOURCE
= 1 << 0,
209 BT_COMPONENT_CLASS_TYPE_FILTER
= 1 << 1,
215 BT_COMPONENT_CLASS_TYPE_SINK
= 1 << 2,
216 } bt_component_class_type
;
220 Returns the type enumerator of the component class
221 \bt_p{component_class}.
223 @param[in] component_class
224 Component class of which to get the type enumerator.
227 Type enumerator of \bt_p{component_class}.
229 @bt_pre_not_null{component_class}
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.
238 extern bt_component_class_type
bt_component_class_get_type(
239 const bt_component_class
*component_class
);
243 Returns whether or not the component class \bt_p{component_class}
244 is a \bt_src_comp_cls.
246 @param[in] component_class
247 Component class to check.
250 #BT_TRUE if \bt_p{component_class} is a source component class.
252 @bt_pre_not_null{component_class}
254 @sa bt_component_class_get_type() —
255 Returns the type enumerator of a component class.
258 bt_bool
bt_component_class_is_source(
259 const bt_component_class
*component_class
)
261 return bt_component_class_get_type(component_class
) ==
262 BT_COMPONENT_CLASS_TYPE_SOURCE
;
267 Returns whether or not the component class \bt_p{component_class}
268 is a \bt_flt_comp_cls.
270 @param[in] component_class
271 Component class to check.
274 #BT_TRUE if \bt_p{component_class} is a filter component class.
276 @bt_pre_not_null{component_class}
278 @sa bt_component_class_get_type() —
279 Returns the type enumerator of a component class.
282 bt_bool
bt_component_class_is_filter(
283 const bt_component_class
*component_class
)
285 return bt_component_class_get_type(component_class
) ==
286 BT_COMPONENT_CLASS_TYPE_FILTER
;
291 Returns whether or not the component class \bt_p{component_class}
292 is a \bt_sink_comp_cls.
294 @param[in] component_class
295 Component class to check.
298 #BT_TRUE if \bt_p{component_class} is a sink component class.
300 @bt_pre_not_null{component_class}
302 @sa bt_component_class_get_type() —
303 Returns the type enumerator of a component class.
306 bt_bool
bt_component_class_is_sink(
307 const bt_component_class
*component_class
)
309 return bt_component_class_get_type(component_class
) ==
310 BT_COMPONENT_CLASS_TYPE_SINK
;
322 Returns the name of the component class \bt_p{component_class}.
324 See the \ref api-comp-cls-prop-name "name" property.
326 @param[in] component_class
327 Component class of which to get the name.
331 Name of \bt_p{component_class}.
333 The returned pointer remains valid as long as \bt_p{component_class}
337 @bt_pre_not_null{component_class}
339 extern const char *bt_component_class_get_name(
340 const bt_component_class
*component_class
);
344 Returns the description of the component class
345 \bt_p{component_class}.
347 See the \ref api-comp-cls-prop-descr "description" property.
349 @param[in] component_class
350 Component class of which to get the description.
354 Description of \bt_p{component_class}, or \c NULL if none.
356 The returned pointer remains valid as long as \bt_p{component_class}
360 @bt_pre_not_null{component_class}
362 extern const char *bt_component_class_get_description(
363 const bt_component_class
*component_class
);
367 Returns the help text of the component class \bt_p{component_class}.
369 See the \ref api-comp-cls-prop-help "help text" property.
371 @param[in] component_class
372 Component class of which to get the help text.
376 Help text of \bt_p{component_class}, or \c NULL if none.
378 The returned pointer remains valid as long as \bt_p{component_class}
382 @bt_pre_not_null{component_class}
384 extern const char *bt_component_class_get_help(
385 const bt_component_class
*component_class
);
390 @name Common reference count
396 Increments the \ref api-fund-shared-object "reference count" of
397 the component class \bt_p{component_class}.
399 @param[in] component_class
401 Component class of which to increment the reference count.
406 @sa bt_component_put_ref() —
407 Decrements the reference count of a component class.
409 extern void bt_component_class_get_ref(
410 const bt_component_class
*component_class
);
414 Decrements the \ref api-fund-shared-object "reference count" of
415 the component class \bt_p{component_class}.
417 @param[in] component_class
419 Component class of which to decrement the reference count.
424 @sa bt_component_get_ref() —
425 Increments the reference count of a component class.
427 extern void bt_component_class_put_ref(
428 const bt_component_class
*component_class
);
432 Decrements the reference count of the component class
433 \bt_p{_component_class}, and then sets \bt_p{_component_class}
436 @param _component_class
438 Component class of which to decrement the reference count.
443 @bt_pre_assign_expr{_component_class}
445 #define BT_COMPONENT_CLASS_PUT_REF_AND_RESET(_component_class) \
447 bt_component_class_put_ref(_component_class); \
448 (_component_class) = NULL; \
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}
457 This macro effectively moves a component class reference from the
459 \bt_p{_src} to the expression \bt_p{_dst}, putting the existing
460 \bt_p{_dst} reference.
464 Destination expression.
475 @bt_pre_assign_expr{_dst}
476 @bt_pre_assign_expr{_src}
478 #define BT_COMPONENT_CLASS_MOVE_REF(_dst, _src) \
480 bt_component_class_put_ref(_dst); \
488 @name Source component class upcast
494 \ref api-fund-c-typing "Upcasts" the \bt_src_comp_cls
495 \bt_p{component_class} to the common #bt_component_class type.
497 @param[in] component_class
499 Source component class to upcast.
505 \bt_p{component_class} as a common component class.
508 const bt_component_class
*
509 bt_component_class_source_as_component_class_const(
510 const bt_component_class_source
*component_class
)
512 return __BT_UPCAST_CONST(bt_component_class
, component_class
);
518 @name Source component class reference count
524 Increments the \ref api-fund-shared-object "reference count" of
525 the \bt_src_comp_cls \bt_p{component_class}.
527 @param[in] component_class
529 Source component class of which to increment the reference count.
534 @sa bt_component_class_source_put_ref() —
535 Decrements the reference count of a source component class.
537 extern void bt_component_class_source_get_ref(
538 const bt_component_class_source
*component_class
);
542 Decrements the \ref api-fund-shared-object "reference count" of
543 the \bt_src_comp_cls \bt_p{component_class}.
545 @param[in] component_class
547 Source component class of which to decrement the reference count.
552 @sa bt_component_class_source_get_ref() —
553 Increments the reference count of a source component class.
555 extern void bt_component_class_source_put_ref(
556 const bt_component_class_source
*component_class
);
560 Decrements the reference count of the \bt_src_comp_cls
561 \bt_p{_component_class}, and then sets \bt_p{_component_class} to
564 @param _component_class
566 Source component class of which to decrement the reference count.
571 @bt_pre_assign_expr{_component_class}
573 #define BT_COMPONENT_CLASS_SOURCE_PUT_REF_AND_RESET(_component_class) \
575 bt_component_class_source_put_ref(_component_class); \
576 (_component_class) = NULL; \
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
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.
591 Destination expression.
602 @bt_pre_assign_expr{_dst}
603 @bt_pre_assign_expr{_src}
605 #define BT_COMPONENT_CLASS_SOURCE_MOVE_REF(_dst, _src) \
607 bt_component_class_source_put_ref(_dst); \
615 @name Filter component class upcast
621 \ref api-fund-c-typing "Upcasts" the \bt_flt_comp_cls
622 \bt_p{component_class} to the common #bt_component_class type.
624 @param[in] component_class
626 Filter component class to upcast.
632 \bt_p{component_class} as a common component class.
635 const bt_component_class
*
636 bt_component_class_filter_as_component_class_const(
637 const bt_component_class_filter
*component_class
)
639 return __BT_UPCAST_CONST(bt_component_class
, component_class
);
645 @name Filter component class reference count
651 Increments the \ref api-fund-shared-object "reference count" of
652 the \bt_flt_comp_cls \bt_p{component_class}.
654 @param[in] component_class
656 Filter component class of which to increment the reference count.
661 @sa bt_component_class_filter_put_ref() —
662 Decrements the reference count of a filter component class.
664 extern void bt_component_class_filter_get_ref(
665 const bt_component_class_filter
*component_class
);
669 Decrements the \ref api-fund-shared-object "reference count" of
670 the \bt_flt_comp_cls \bt_p{component_class}.
672 @param[in] component_class
674 Filter component class of which to decrement the reference count.
679 @sa bt_component_class_filter_get_ref() —
680 Increments the reference count of a filter component class.
682 extern void bt_component_class_filter_put_ref(
683 const bt_component_class_filter
*component_class
);
687 Decrements the reference count of the \bt_flt_comp_cls
688 \bt_p{_component_class}, and then sets \bt_p{_component_class} to
691 @param _component_class
693 Filter component class of which to decrement the reference count.
698 @bt_pre_assign_expr{_component_class}
700 #define BT_COMPONENT_CLASS_FILTER_PUT_REF_AND_RESET(_component_class) \
702 bt_component_class_filter_put_ref(_component_class); \
703 (_component_class) = NULL; \
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
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.
718 Destination expression.
729 @bt_pre_assign_expr{_dst}
730 @bt_pre_assign_expr{_src}
732 #define BT_COMPONENT_CLASS_FILTER_MOVE_REF(_dst, _src) \
734 bt_component_class_filter_put_ref(_dst); \
742 @name Sink component class upcast
748 \ref api-fund-c-typing "Upcasts" the \bt_sink_comp_cls
749 \bt_p{component_class} to the common #bt_component_class type.
751 @param[in] component_class
753 Sink component class to upcast.
759 \bt_p{component_class} as a common component class.
762 const bt_component_class
*
763 bt_component_class_sink_as_component_class_const(
764 const bt_component_class_sink
*component_class
)
766 return __BT_UPCAST_CONST(bt_component_class
, component_class
);
772 @name Sink component class reference count
778 Increments the \ref api-fund-shared-object "reference count" of
779 the \bt_sink_comp_cls \bt_p{component_class}.
781 @param[in] component_class
783 Sink component class of which to increment the reference count.
788 @sa bt_component_class_sink_put_ref() —
789 Decrements the reference count of a sink component class.
791 extern void bt_component_class_sink_get_ref(
792 const bt_component_class_sink
*component_class
);
796 Decrements the \ref api-fund-shared-object "reference count" of
797 the \bt_sink_comp_cls \bt_p{component_class}.
799 @param[in] component_class
801 Sink component class of which to decrement the reference count.
806 @sa bt_component_class_sink_get_ref() —
807 Increments the reference count of a sink component class.
809 extern void bt_component_class_sink_put_ref(
810 const bt_component_class_sink
*component_class
);
814 Decrements the reference count of the \bt_sink_comp_cls
815 \bt_p{_component_class}, and then sets \bt_p{_component_class} to
818 @param _component_class
820 Sink component class of which to decrement the reference count.
825 @bt_pre_assign_expr{_component_class}
827 #define BT_COMPONENT_CLASS_SINK_PUT_REF_AND_RESET(_component_class) \
829 bt_component_class_sink_put_ref(_component_class); \
830 (_component_class) = NULL; \
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
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.
845 Destination expression.
856 @bt_pre_assign_expr{_dst}
857 @bt_pre_assign_expr{_src}
859 #define BT_COMPONENT_CLASS_SINK_MOVE_REF(_dst, _src) \
861 bt_component_class_sink_put_ref(_dst); \
874 #endif /* BABELTRACE2_GRAPH_COMPONENT_CLASS_H */