1 #ifndef BABELTRACE2_GRAPH_COMPONENT_CLASS_H
2 #define BABELTRACE2_GRAPH_COMPONENT_CLASS_H
5 * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
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:
14 * The above copyright notice and this permission notice shall be included in
15 * all copies or substantial portions of the Software.
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
26 #ifndef __BT_IN_BABELTRACE_H
27 # error "Please include <babeltrace2/babeltrace.h> instead."
30 #include <babeltrace2/types.h>
37 @defgroup api-comp-cls Component classes
41 Source, filter, and sink component classes (non-development).
43 A <strong><em>component class</em></strong> is the class of a \bt_comp:
45 @image html component.png
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.
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).
56 There are two ways to obtain a component class:
58 - Create one programatically: see \ref api-comp-cls-dev.
60 - Borrow one from a \bt_plugin.
62 Note that, as of \bt_name_version_min_maj, you cannot access a
63 component class's plugin, if any.
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().
69 The common C type of a component class is #bt_component_class.
71 There are three types of component classes:
74 <dt>\anchor api-comp-cls-src Source component class</dt>
76 A source component class instance (a \bt_src_comp) \bt_msg_iter
77 emits fresh \bt_p_msg.
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.
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().
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().
92 <dt>\anchor api-comp-cls-flt Filter component class</dt>
94 A filter component class instance (a \bt_flt_comp) message iterator
95 emits fresh and transformed messages. It can also discard
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.
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().
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().
111 <dt>\anchor api-comp-cls-sink Sink component class</dt>
113 A sink component class instance (a \bt_sink_comp) consumes messages
114 from a source or filter message iterator.
116 A filter component class's specific type is #bt_component_class_sink
117 and its type enumerator is #BT_COMPONENT_CLASS_TYPE_SINK.
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().
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().
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.
136 A component class has the following common properties:
140 \anchor api-comp-cls-prop-name
144 Name of the component class.
146 Within a \bt_plugin, for a given component class type, each
147 component class has a unique name.
149 Get a component class's name with bt_component_class_get_name().
153 \anchor api-comp-cls-prop-descr
154 \bt_dt_opt Description
157 Textual description of the component class.
159 Get a component class's description with
160 bt_component_class_get_description().
164 \anchor api-comp-cls-prop-help
168 Help text of the component class.
170 Get a component class's help text with
171 bt_component_class_get_help().
182 @typedef struct bt_component_class bt_component_class;
187 @typedef struct bt_component_class_source bt_component_class_source;
192 @typedef struct bt_component_class_filter bt_component_class_filter;
197 @typedef struct bt_component_class_sink bt_component_class_sink;
212 Component class type enumerators.
214 typedef enum bt_component_class_type
{
219 BT_COMPONENT_CLASS_TYPE_SOURCE
= 1 << 0,
225 BT_COMPONENT_CLASS_TYPE_FILTER
= 1 << 1,
231 BT_COMPONENT_CLASS_TYPE_SINK
= 1 << 2,
232 } bt_component_class_type
;
236 Returns the type enumerator of the component class
237 \bt_p{component_class}.
239 @param[in] component_class
240 Component class of which to get the type enumerator.
243 Type enumerator of \bt_p{component_class}.
245 @bt_pre_not_null{component_class}
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.
254 extern bt_component_class_type
bt_component_class_get_type(
255 const bt_component_class
*component_class
);
259 Returns whether or not the component class \bt_p{component_class}
260 is a \bt_src_comp_cls.
262 @param[in] component_class
263 Component class to check.
266 #BT_TRUE if \bt_p{component_class} is a source component class.
268 @bt_pre_not_null{component_class}
270 @sa bt_component_class_get_type() —
271 Returns the type enumerator of a component class.
274 bt_bool
bt_component_class_is_source(
275 const bt_component_class
*component_class
)
277 return bt_component_class_get_type(component_class
) ==
278 BT_COMPONENT_CLASS_TYPE_SOURCE
;
283 Returns whether or not the component class \bt_p{component_class}
284 is a \bt_flt_comp_cls.
286 @param[in] component_class
287 Component class to check.
290 #BT_TRUE if \bt_p{component_class} is a filter component class.
292 @bt_pre_not_null{component_class}
294 @sa bt_component_class_get_type() —
295 Returns the type enumerator of a component class.
298 bt_bool
bt_component_class_is_filter(
299 const bt_component_class
*component_class
)
301 return bt_component_class_get_type(component_class
) ==
302 BT_COMPONENT_CLASS_TYPE_FILTER
;
307 Returns whether or not the component class \bt_p{component_class}
308 is a \bt_sink_comp_cls.
310 @param[in] component_class
311 Component class to check.
314 #BT_TRUE if \bt_p{component_class} is a sink component class.
316 @bt_pre_not_null{component_class}
318 @sa bt_component_class_get_type() —
319 Returns the type enumerator of a component class.
322 bt_bool
bt_component_class_is_sink(
323 const bt_component_class
*component_class
)
325 return bt_component_class_get_type(component_class
) ==
326 BT_COMPONENT_CLASS_TYPE_SINK
;
338 Returns the name of the component class \bt_p{component_class}.
340 See the \ref api-comp-cls-prop-name "name" property.
342 @param[in] component_class
343 Component class of which to get the name.
347 Name of \bt_p{component_class}.
349 The returned pointer remains valid as long as \bt_p{component_class}
353 @bt_pre_not_null{component_class}
355 extern const char *bt_component_class_get_name(
356 const bt_component_class
*component_class
);
360 Returns the description of the component class
361 \bt_p{component_class}.
363 See the \ref api-comp-cls-prop-descr "description" property.
365 @param[in] component_class
366 Component class of which to get the description.
370 Description of \bt_p{component_class}, or \c NULL if none.
372 The returned pointer remains valid as long as \bt_p{component_class}
376 @bt_pre_not_null{component_class}
378 extern const char *bt_component_class_get_description(
379 const bt_component_class
*component_class
);
383 Returns the help text of the component class \bt_p{component_class}.
385 See the \ref api-comp-cls-prop-help "help text" property.
387 @param[in] component_class
388 Component class of which to get the help text.
392 Help text of \bt_p{component_class}, or \c NULL if none.
394 The returned pointer remains valid as long as \bt_p{component_class}
398 @bt_pre_not_null{component_class}
400 extern const char *bt_component_class_get_help(
401 const bt_component_class
*component_class
);
406 @name Common reference count
412 Increments the \ref api-fund-shared-object "reference count" of
413 the component class \bt_p{component_class}.
415 @param[in] component_class
417 Component class of which to increment the reference count.
422 @sa bt_component_put_ref() —
423 Decrements the reference count of a component class.
425 extern void bt_component_class_get_ref(
426 const bt_component_class
*component_class
);
430 Decrements the \ref api-fund-shared-object "reference count" of
431 the component class \bt_p{component_class}.
433 @param[in] component_class
435 Component class of which to decrement the reference count.
440 @sa bt_component_get_ref() —
441 Increments the reference count of a component class.
443 extern void bt_component_class_put_ref(
444 const bt_component_class
*component_class
);
448 Decrements the reference count of the component class
449 \bt_p{_component_class}, and then sets \bt_p{_component_class}
452 @param _component_class
454 Component class of which to decrement the reference count.
459 @bt_pre_assign_expr{_component_class}
461 #define BT_COMPONENT_CLASS_PUT_REF_AND_RESET(_component_class) \
463 bt_component_class_put_ref(_component_class); \
464 (_component_class) = NULL; \
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}
473 This macro effectively moves a component class reference from the
475 \bt_p{_src} to the expression \bt_p{_dst}, putting the existing
476 \bt_p{_dst} reference.
480 Destination expression.
491 @bt_pre_assign_expr{_dst}
492 @bt_pre_assign_expr{_src}
494 #define BT_COMPONENT_CLASS_MOVE_REF(_dst, _src) \
496 bt_component_class_put_ref(_dst); \
504 @name Source component class upcast
510 \ref api-fund-c-typing "Upcasts" the \bt_src_comp_cls
511 \bt_p{component_class} to the common #bt_component_class type.
513 @param[in] component_class
515 Source component class to upcast.
521 \bt_p{component_class} as a common component class.
524 const bt_component_class
*
525 bt_component_class_source_as_component_class_const(
526 const bt_component_class_source
*component_class
)
528 return __BT_UPCAST_CONST(bt_component_class
, component_class
);
534 @name Source component class reference count
540 Increments the \ref api-fund-shared-object "reference count" of
541 the \bt_src_comp_cls \bt_p{component_class}.
543 @param[in] component_class
545 Source component class of which to increment the reference count.
550 @sa bt_component_class_source_put_ref() —
551 Decrements the reference count of a source component class.
553 extern void bt_component_class_source_get_ref(
554 const bt_component_class_source
*component_class
);
558 Decrements the \ref api-fund-shared-object "reference count" of
559 the \bt_src_comp_cls \bt_p{component_class}.
561 @param[in] component_class
563 Source component class of which to decrement the reference count.
568 @sa bt_component_class_source_get_ref() —
569 Increments the reference count of a source component class.
571 extern void bt_component_class_source_put_ref(
572 const bt_component_class_source
*component_class
);
576 Decrements the reference count of the \bt_src_comp_cls
577 \bt_p{_component_class}, and then sets \bt_p{_component_class} to
580 @param _component_class
582 Source component class of which to decrement the reference count.
587 @bt_pre_assign_expr{_component_class}
589 #define BT_COMPONENT_CLASS_SOURCE_PUT_REF_AND_RESET(_component_class) \
591 bt_component_class_source_put_ref(_component_class); \
592 (_component_class) = NULL; \
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
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.
607 Destination expression.
618 @bt_pre_assign_expr{_dst}
619 @bt_pre_assign_expr{_src}
621 #define BT_COMPONENT_CLASS_SOURCE_MOVE_REF(_dst, _src) \
623 bt_component_class_source_put_ref(_dst); \
631 @name Filter component class upcast
637 \ref api-fund-c-typing "Upcasts" the \bt_flt_comp_cls
638 \bt_p{component_class} to the common #bt_component_class type.
640 @param[in] component_class
642 Filter component class to upcast.
648 \bt_p{component_class} as a common component class.
651 const bt_component_class
*
652 bt_component_class_filter_as_component_class_const(
653 const bt_component_class_filter
*component_class
)
655 return __BT_UPCAST_CONST(bt_component_class
, component_class
);
661 @name Filter component class reference count
667 Increments the \ref api-fund-shared-object "reference count" of
668 the \bt_flt_comp_cls \bt_p{component_class}.
670 @param[in] component_class
672 Filter component class of which to increment the reference count.
677 @sa bt_component_class_filter_put_ref() —
678 Decrements the reference count of a filter component class.
680 extern void bt_component_class_filter_get_ref(
681 const bt_component_class_filter
*component_class
);
685 Decrements the \ref api-fund-shared-object "reference count" of
686 the \bt_flt_comp_cls \bt_p{component_class}.
688 @param[in] component_class
690 Filter component class of which to decrement the reference count.
695 @sa bt_component_class_filter_get_ref() —
696 Increments the reference count of a filter component class.
698 extern void bt_component_class_filter_put_ref(
699 const bt_component_class_filter
*component_class
);
703 Decrements the reference count of the \bt_flt_comp_cls
704 \bt_p{_component_class}, and then sets \bt_p{_component_class} to
707 @param _component_class
709 Filter component class of which to decrement the reference count.
714 @bt_pre_assign_expr{_component_class}
716 #define BT_COMPONENT_CLASS_FILTER_PUT_REF_AND_RESET(_component_class) \
718 bt_component_class_filter_put_ref(_component_class); \
719 (_component_class) = NULL; \
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
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.
734 Destination expression.
745 @bt_pre_assign_expr{_dst}
746 @bt_pre_assign_expr{_src}
748 #define BT_COMPONENT_CLASS_FILTER_MOVE_REF(_dst, _src) \
750 bt_component_class_filter_put_ref(_dst); \
758 @name Sink component class upcast
764 \ref api-fund-c-typing "Upcasts" the \bt_sink_comp_cls
765 \bt_p{component_class} to the common #bt_component_class type.
767 @param[in] component_class
769 Sink component class to upcast.
775 \bt_p{component_class} as a common component class.
778 const bt_component_class
*
779 bt_component_class_sink_as_component_class_const(
780 const bt_component_class_sink
*component_class
)
782 return __BT_UPCAST_CONST(bt_component_class
, component_class
);
788 @name Sink component class reference count
794 Increments the \ref api-fund-shared-object "reference count" of
795 the \bt_sink_comp_cls \bt_p{component_class}.
797 @param[in] component_class
799 Sink component class of which to increment the reference count.
804 @sa bt_component_class_sink_put_ref() —
805 Decrements the reference count of a sink component class.
807 extern void bt_component_class_sink_get_ref(
808 const bt_component_class_sink
*component_class
);
812 Decrements the \ref api-fund-shared-object "reference count" of
813 the \bt_sink_comp_cls \bt_p{component_class}.
815 @param[in] component_class
817 Sink component class of which to decrement the reference count.
822 @sa bt_component_class_sink_get_ref() —
823 Increments the reference count of a sink component class.
825 extern void bt_component_class_sink_put_ref(
826 const bt_component_class_sink
*component_class
);
830 Decrements the reference count of the \bt_sink_comp_cls
831 \bt_p{_component_class}, and then sets \bt_p{_component_class} to
834 @param _component_class
836 Sink component class of which to decrement the reference count.
841 @bt_pre_assign_expr{_component_class}
843 #define BT_COMPONENT_CLASS_SINK_PUT_REF_AND_RESET(_component_class) \
845 bt_component_class_sink_put_ref(_component_class); \
846 (_component_class) = NULL; \
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
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.
861 Destination expression.
872 @bt_pre_assign_expr{_dst}
873 @bt_pre_assign_expr{_src}
875 #define BT_COMPONENT_CLASS_SINK_MOVE_REF(_dst, _src) \
877 bt_component_class_sink_put_ref(_dst); \
890 #endif /* BABELTRACE2_GRAPH_COMPONENT_CLASS_H */