X-Git-Url: http://git.efficios.com/?p=babeltrace.git;a=blobdiff_plain;f=include%2Fbabeltrace2%2Fgraph%2Fcomponent-class.h;h=66036c22a0629aad34c4347035623ca8ee87a7fb;hp=8a35146c612e6c056a83afad1a44d6c8698834bc;hb=0235b0db7de5bcacdb3650c92461f2ce5eb2143d;hpb=a635e50750a3c1e8907b38c8311dc0b8bb0f09c3 diff --git a/include/babeltrace2/graph/component-class.h b/include/babeltrace2/graph/component-class.h index 8a35146c..66036c22 100644 --- a/include/babeltrace2/graph/component-class.h +++ b/include/babeltrace2/graph/component-class.h @@ -1,28 +1,12 @@ -#ifndef BABELTRACE2_GRAPH_COMPONENT_CLASS_H -#define BABELTRACE2_GRAPH_COMPONENT_CLASS_H - /* - * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation - * - * Permission is hereby granted, free of charge, to any person obtaining a copy - * of this software and associated documentation files (the "Software"), to deal - * in the Software without restriction, including without limitation the rights - * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell - * copies of the Software, and to permit persons to whom the Software is - * furnished to do so, subject to the following conditions: + * SPDX-License-Identifier: MIT * - * The above copyright notice and this permission notice shall be included in - * all copies or substantial portions of the Software. - * - * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR - * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, - * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE - * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER - * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, - * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE - * SOFTWARE. + * Copyright (C) 2010-2019 EfficiOS Inc. and Linux Foundation */ +#ifndef BABELTRACE2_GRAPH_COMPONENT_CLASS_H +#define BABELTRACE2_GRAPH_COMPONENT_CLASS_H + #ifndef __BT_IN_BABELTRACE_H # error "Please include instead." #endif @@ -33,75 +17,855 @@ extern "C" { #endif -typedef enum bt_component_class_init_method_status { - BT_COMPONENT_CLASS_INIT_METHOD_STATUS_OK = __BT_FUNC_STATUS_OK, - BT_COMPONENT_CLASS_INIT_METHOD_STATUS_ERROR = __BT_FUNC_STATUS_ERROR, - BT_COMPONENT_CLASS_INIT_METHOD_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR, -} bt_component_class_init_method_status; - -typedef enum bt_component_class_port_connected_method_status { - BT_COMPONENT_CLASS_PORT_CONNECTED_METHOD_STATUS_OK = __BT_FUNC_STATUS_OK, - BT_COMPONENT_CLASS_PORT_CONNECTED_METHOD_STATUS_ERROR = __BT_FUNC_STATUS_ERROR, - BT_COMPONENT_CLASS_PORT_CONNECTED_METHOD_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR, -} bt_component_class_port_connected_method_status; - -typedef enum bt_component_class_query_method_status { - BT_COMPONENT_CLASS_QUERY_METHOD_STATUS_OK = __BT_FUNC_STATUS_OK, - BT_COMPONENT_CLASS_QUERY_METHOD_STATUS_AGAIN = __BT_FUNC_STATUS_AGAIN, - BT_COMPONENT_CLASS_QUERY_METHOD_STATUS_ERROR = __BT_FUNC_STATUS_ERROR, - BT_COMPONENT_CLASS_QUERY_METHOD_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR, - BT_COMPONENT_CLASS_QUERY_METHOD_STATUS_INVALID_OBJECT = __BT_FUNC_STATUS_INVALID_OBJECT, -} bt_component_class_query_method_status; - -typedef enum bt_component_class_message_iterator_init_method_status { - BT_COMPONENT_CLASS_MESSAGE_ITERATOR_INIT_METHOD_STATUS_OK = __BT_FUNC_STATUS_OK, - BT_COMPONENT_CLASS_MESSAGE_ITERATOR_INIT_METHOD_STATUS_ERROR = __BT_FUNC_STATUS_ERROR, - BT_COMPONENT_CLASS_MESSAGE_ITERATOR_INIT_METHOD_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR, -} bt_component_class_message_iterator_init_method_status; - -typedef enum bt_component_class_message_iterator_next_method_status { - BT_COMPONENT_CLASS_MESSAGE_ITERATOR_NEXT_METHOD_STATUS_OK = __BT_FUNC_STATUS_OK, - BT_COMPONENT_CLASS_MESSAGE_ITERATOR_NEXT_METHOD_STATUS_AGAIN = __BT_FUNC_STATUS_AGAIN, - BT_COMPONENT_CLASS_MESSAGE_ITERATOR_NEXT_METHOD_STATUS_ERROR = __BT_FUNC_STATUS_ERROR, - BT_COMPONENT_CLASS_MESSAGE_ITERATOR_NEXT_METHOD_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR, - BT_COMPONENT_CLASS_MESSAGE_ITERATOR_NEXT_METHOD_STATUS_END = __BT_FUNC_STATUS_END, -} bt_component_class_message_iterator_next_method_status; - -typedef enum bt_component_class_message_iterator_seek_beginning_method_status { - BT_COMPONENT_CLASS_MESSAGE_ITERATOR_SEEK_BEGINNING_METHOD_STATUS_OK = __BT_FUNC_STATUS_OK, - BT_COMPONENT_CLASS_MESSAGE_ITERATOR_SEEK_BEGINNING_METHOD_STATUS_AGAIN = __BT_FUNC_STATUS_AGAIN, - BT_COMPONENT_CLASS_MESSAGE_ITERATOR_SEEK_BEGINNING_METHOD_STATUS_ERROR = __BT_FUNC_STATUS_ERROR, - BT_COMPONENT_CLASS_MESSAGE_ITERATOR_SEEK_BEGINNING_METHOD_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR, -} bt_component_class_message_iterator_seek_beginning_method_status; - -typedef enum bt_component_class_message_iterator_seek_ns_from_origin_method_status { - BT_COMPONENT_CLASS_MESSAGE_ITERATOR_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_OK = __BT_FUNC_STATUS_OK, - BT_COMPONENT_CLASS_MESSAGE_ITERATOR_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_AGAIN = __BT_FUNC_STATUS_AGAIN, - BT_COMPONENT_CLASS_MESSAGE_ITERATOR_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_ERROR = __BT_FUNC_STATUS_ERROR, - BT_COMPONENT_CLASS_MESSAGE_ITERATOR_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR, -} bt_component_class_message_iterator_seek_ns_from_origin_method_status; - -typedef enum bt_component_class_set_method_status { - BT_COMPONENT_CLASS_SET_METHOD_STATUS_OK = __BT_FUNC_STATUS_OK, -} bt_component_class_set_method_status; - -typedef enum bt_component_class_set_description_status { - BT_COMPONENT_CLASS_SET_DESCRIPTION_STATUS_OK = __BT_FUNC_STATUS_OK, - BT_COMPONENT_CLASS_SET_DESCRIPTION_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR, -} bt_component_class_set_description_status; - -extern bt_component_class_set_description_status -bt_component_class_set_description(bt_component_class *component_class, - const char *description); - -typedef enum bt_component_class_set_help_status { - BT_COMPONENT_CLASS_SET_HELP_STATUS_OK = __BT_FUNC_STATUS_OK, - BT_COMPONENT_CLASS_SET_HELP_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR, -} bt_component_class_set_help_status; - -extern bt_component_class_set_help_status bt_component_class_set_help( - bt_component_class *component_class, - const char *help); +/*! +@defgroup api-comp-cls Component classes +@ingroup api-graph + +@brief + Source, filter, and sink component classes (non-development). + +A component class is the class of a \bt_comp: + +@image html component.png + +@attention + This module (component class API) offers basic, read-only functions + to get component class properties. To \em create a component class, + see \ref api-comp-cls-dev or \ref api-plugin-dev. + +You can instantiate a given component class many times, with different +initialization parameters, to create many components with the +bt_graph_add_*_component*() functions (see \ref api-graph). + +There are two ways to obtain a component class: + +- Create one programatically: see \ref api-comp-cls-dev. + +- Borrow one from a \bt_plugin. + + Note that, as of \bt_name_version_min_maj, you cannot access a + component class's plugin, if any. + +A component class is a \ref api-fund-shared-object "shared object": get +a new reference with bt_component_class_get_ref() and put an existing +reference with bt_component_class_put_ref(). + +The common C type of a component class is #bt_component_class. + +There are three types of component classes: + +
+
\anchor api-comp-cls-src Source component class
+
+ A source component class instance (a \bt_src_comp) \bt_msg_iter + emits fresh \bt_p_msg. + + A source component class's specific type is + #bt_component_class_source and its type enumerator is + #BT_COMPONENT_CLASS_TYPE_SOURCE. + + \ref api-fund-c-typing "Upcast" the #bt_component_class_source type + to the #bt_component_class type with + bt_component_class_source_as_component_class_const(). + + Get a new source component class reference with Use + bt_component_class_source_get_ref() and put an existing one with + bt_component_class_source_put_ref(). +
+ +
\anchor api-comp-cls-flt Filter component class
+
+ A filter component class instance (a \bt_flt_comp) message iterator + emits fresh and transformed messages. It can also discard + existing messages. + + A filter component class's specific type is + #bt_component_class_filter and its type enumerator is + #BT_COMPONENT_CLASS_TYPE_FILTER. + + \ref api-fund-c-typing "Upcast" the #bt_component_class_filter type + to the #bt_component_class type with + bt_component_class_filter_as_component_class_const(). + + Get a new filter component class reference with + bt_component_class_filter_get_ref() and put an existing one with + bt_component_class_filter_put_ref(). +
+ +
\anchor api-comp-cls-sink Sink component class
+
+ A sink component class instance (a \bt_sink_comp) consumes messages + from a source or filter message iterator. + + A filter component class's specific type is #bt_component_class_sink + and its type enumerator is #BT_COMPONENT_CLASS_TYPE_SINK. + + \ref api-fund-c-typing "Upcast" the #bt_component_class_sink type to + the #bt_component_class type with + bt_component_class_sink_as_component_class_const(). + + Get a new sink component class reference with + bt_component_class_sink_get_ref() and put an existing one with + bt_component_class_sink_put_ref(). +
+
+ +Get a component's class type enumerator with +bt_component_class_get_type(). You can also use the +bt_component_class_is_source(), bt_component_class_is_filter(), and +bt_component_class_is_sink() helper functions. + +

Properties

+ +A component class has the following common properties: + +
+
+ \anchor api-comp-cls-prop-name + Name +
+
+ Name of the component class. + + Within a \bt_plugin, for a given component class type, each + component class has a unique name. + + Get a component class's name with bt_component_class_get_name(). +
+ +
+ \anchor api-comp-cls-prop-descr + \bt_dt_opt Description +
+
+ Textual description of the component class. + + Get a component class's description with + bt_component_class_get_description(). +
+ +
+ \anchor api-comp-cls-prop-help + \bt_dt_opt Help text +
+
+ Help text of the component class. + + Get a component class's help text with + bt_component_class_get_help(). +
+
+*/ + +/*! @{ */ + +/*! +@name Types +@{ + +@typedef struct bt_component_class bt_component_class; + +@brief + Component class. + +@typedef struct bt_component_class_source bt_component_class_source; + +@brief + \bt_c_src_comp_cls. + +@typedef struct bt_component_class_filter bt_component_class_filter; + +@brief + \bt_c_flt_comp_cls. + +@typedef struct bt_component_class_sink bt_component_class_sink; + +@brief + \bt_c_sink_comp_cls. + +@} +*/ + +/*! +@name Type query +@{ +*/ + +/*! +@brief + Component class type enumerators. +*/ +typedef enum bt_component_class_type { + /*! + @brief + \bt_c_src_comp_cls. + */ + BT_COMPONENT_CLASS_TYPE_SOURCE = 1 << 0, + + /*! + @brief + \bt_c_flt_comp_cls. + */ + BT_COMPONENT_CLASS_TYPE_FILTER = 1 << 1, + + /*! + @brief + \bt_c_sink_comp_cls. + */ + BT_COMPONENT_CLASS_TYPE_SINK = 1 << 2, +} bt_component_class_type; + +/*! +@brief + Returns the type enumerator of the component class + \bt_p{component_class}. + +@param[in] component_class + Component class of which to get the type enumerator. + +@returns + Type enumerator of \bt_p{component_class}. + +@bt_pre_not_null{component_class} + +@sa bt_component_class_is_source() — + Returns whether or not a component class is a \bt_src_comp_cls. +@sa bt_component_class_is_filter() — + Returns whether or not a component class is a \bt_flt_comp_cls. +@sa bt_component_class_is_sink() — + Returns whether or not a component class is a \bt_sink_comp_cls. +*/ +extern bt_component_class_type bt_component_class_get_type( + const bt_component_class *component_class); + +/*! +@brief + Returns whether or not the component class \bt_p{component_class} + is a \bt_src_comp_cls. + +@param[in] component_class + Component class to check. + +@returns + #BT_TRUE if \bt_p{component_class} is a source component class. + +@bt_pre_not_null{component_class} + +@sa bt_component_class_get_type() — + Returns the type enumerator of a component class. +*/ +static inline +bt_bool bt_component_class_is_source( + const bt_component_class *component_class) +{ + return bt_component_class_get_type(component_class) == + BT_COMPONENT_CLASS_TYPE_SOURCE; +} + +/*! +@brief + Returns whether or not the component class \bt_p{component_class} + is a \bt_flt_comp_cls. + +@param[in] component_class + Component class to check. + +@returns + #BT_TRUE if \bt_p{component_class} is a filter component class. + +@bt_pre_not_null{component_class} + +@sa bt_component_class_get_type() — + Returns the type enumerator of a component class. +*/ +static inline +bt_bool bt_component_class_is_filter( + const bt_component_class *component_class) +{ + return bt_component_class_get_type(component_class) == + BT_COMPONENT_CLASS_TYPE_FILTER; +} + +/*! +@brief + Returns whether or not the component class \bt_p{component_class} + is a \bt_sink_comp_cls. + +@param[in] component_class + Component class to check. + +@returns + #BT_TRUE if \bt_p{component_class} is a sink component class. + +@bt_pre_not_null{component_class} + +@sa bt_component_class_get_type() — + Returns the type enumerator of a component class. +*/ +static inline +bt_bool bt_component_class_is_sink( + const bt_component_class *component_class) +{ + return bt_component_class_get_type(component_class) == + BT_COMPONENT_CLASS_TYPE_SINK; +} + +/*! @} */ + +/*! +@name Properties +@{ +*/ + +/*! +@brief + Returns the name of the component class \bt_p{component_class}. + +See the \ref api-comp-cls-prop-name "name" property. + +@param[in] component_class + Component class of which to get the name. + +@returns + @parblock + Name of \bt_p{component_class}. + + The returned pointer remains valid as long as \bt_p{component_class} + exists. + @endparblock + +@bt_pre_not_null{component_class} +*/ +extern const char *bt_component_class_get_name( + const bt_component_class *component_class); + +/*! +@brief + Returns the description of the component class + \bt_p{component_class}. + +See the \ref api-comp-cls-prop-descr "description" property. + +@param[in] component_class + Component class of which to get the description. + +@returns + @parblock + Description of \bt_p{component_class}, or \c NULL if none. + + The returned pointer remains valid as long as \bt_p{component_class} + exists. + @endparblock + +@bt_pre_not_null{component_class} +*/ +extern const char *bt_component_class_get_description( + const bt_component_class *component_class); + +/*! +@brief + Returns the help text of the component class \bt_p{component_class}. + +See the \ref api-comp-cls-prop-help "help text" property. + +@param[in] component_class + Component class of which to get the help text. + +@returns + @parblock + Help text of \bt_p{component_class}, or \c NULL if none. + + The returned pointer remains valid as long as \bt_p{component_class} + exists. + @endparblock + +@bt_pre_not_null{component_class} +*/ +extern const char *bt_component_class_get_help( + const bt_component_class *component_class); + +/*! @} */ + +/*! +@name Common reference count +@{ +*/ + +/*! +@brief + Increments the \ref api-fund-shared-object "reference count" of + the component class \bt_p{component_class}. + +@param[in] component_class + @parblock + Component class of which to increment the reference count. + + Can be \c NULL. + @endparblock + +@sa bt_component_put_ref() — + Decrements the reference count of a component class. +*/ +extern void bt_component_class_get_ref( + const bt_component_class *component_class); + +/*! +@brief + Decrements the \ref api-fund-shared-object "reference count" of + the component class \bt_p{component_class}. + +@param[in] component_class + @parblock + Component class of which to decrement the reference count. + + Can be \c NULL. + @endparblock + +@sa bt_component_get_ref() — + Increments the reference count of a component class. +*/ +extern void bt_component_class_put_ref( + const bt_component_class *component_class); + +/*! +@brief + Decrements the reference count of the component class + \bt_p{_component_class}, and then sets \bt_p{_component_class} + to \c NULL. + +@param _component_class + @parblock + Component class of which to decrement the reference count. + + Can contain \c NULL. + @endparblock + +@bt_pre_assign_expr{_component_class} +*/ +#define BT_COMPONENT_CLASS_PUT_REF_AND_RESET(_component_class) \ + do { \ + bt_component_class_put_ref(_component_class); \ + (_component_class) = NULL; \ + } while (0) + +/*! +@brief + Decrements the reference count of the component class \bt_p{_dst}, + sets \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} + to \c NULL. + +This macro effectively moves a component class reference from the +expression +\bt_p{_src} to the expression \bt_p{_dst}, putting the existing +\bt_p{_dst} reference. + +@param _dst + @parblock + Destination expression. + + Can contain \c NULL. + @endparblock +@param _src + @parblock + Source expression. + + Can contain \c NULL. + @endparblock + +@bt_pre_assign_expr{_dst} +@bt_pre_assign_expr{_src} +*/ +#define BT_COMPONENT_CLASS_MOVE_REF(_dst, _src) \ + do { \ + bt_component_class_put_ref(_dst); \ + (_dst) = (_src); \ + (_src) = NULL; \ + } while (0) + +/*! @} */ + +/*! +@name Source component class upcast +@{ +*/ + +/*! +@brief + \ref api-fund-c-typing "Upcasts" the \bt_src_comp_cls + \bt_p{component_class} to the common #bt_component_class type. + +@param[in] component_class + @parblock + Source component class to upcast. + + Can be \c NULL. + @endparblock + +@returns + \bt_p{component_class} as a common component class. +*/ +static inline +const bt_component_class * +bt_component_class_source_as_component_class_const( + const bt_component_class_source *component_class) +{ + return __BT_UPCAST_CONST(bt_component_class, component_class); +} + +/*! @} */ + +/*! +@name Source component class reference count +@{ +*/ + +/*! +@brief + Increments the \ref api-fund-shared-object "reference count" of + the \bt_src_comp_cls \bt_p{component_class}. + +@param[in] component_class + @parblock + Source component class of which to increment the reference count. + + Can be \c NULL. + @endparblock + +@sa bt_component_class_source_put_ref() — + Decrements the reference count of a source component class. +*/ +extern void bt_component_class_source_get_ref( + const bt_component_class_source *component_class); + +/*! +@brief + Decrements the \ref api-fund-shared-object "reference count" of + the \bt_src_comp_cls \bt_p{component_class}. + +@param[in] component_class + @parblock + Source component class of which to decrement the reference count. + + Can be \c NULL. + @endparblock + +@sa bt_component_class_source_get_ref() — + Increments the reference count of a source component class. +*/ +extern void bt_component_class_source_put_ref( + const bt_component_class_source *component_class); + +/*! +@brief + Decrements the reference count of the \bt_src_comp_cls + \bt_p{_component_class}, and then sets \bt_p{_component_class} to + \c NULL. + +@param _component_class + @parblock + Source component class of which to decrement the reference count. + + Can contain \c NULL. + @endparblock + +@bt_pre_assign_expr{_component_class} +*/ +#define BT_COMPONENT_CLASS_SOURCE_PUT_REF_AND_RESET(_component_class) \ + do { \ + bt_component_class_source_put_ref(_component_class); \ + (_component_class) = NULL; \ + } while (0) + +/*! +@brief + Decrements the reference count of the \bt_src_comp_cls \bt_p{_dst}, + sets \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to + \c NULL. + +This macro effectively moves a source component class reference from the +expression \bt_p{_src} to the expression \bt_p{_dst}, putting the +existing \bt_p{_dst} reference. + +@param _dst + @parblock + Destination expression. + + Can contain \c NULL. + @endparblock +@param _src + @parblock + Source expression. + + Can contain \c NULL. + @endparblock + +@bt_pre_assign_expr{_dst} +@bt_pre_assign_expr{_src} +*/ +#define BT_COMPONENT_CLASS_SOURCE_MOVE_REF(_dst, _src) \ + do { \ + bt_component_class_source_put_ref(_dst); \ + (_dst) = (_src); \ + (_src) = NULL; \ + } while (0) + +/*! @} */ + +/*! +@name Filter component class upcast +@{ +*/ + +/*! +@brief + \ref api-fund-c-typing "Upcasts" the \bt_flt_comp_cls + \bt_p{component_class} to the common #bt_component_class type. + +@param[in] component_class + @parblock + Filter component class to upcast. + + Can be \c NULL. + @endparblock + +@returns + \bt_p{component_class} as a common component class. +*/ +static inline +const bt_component_class * +bt_component_class_filter_as_component_class_const( + const bt_component_class_filter *component_class) +{ + return __BT_UPCAST_CONST(bt_component_class, component_class); +} + +/*! @} */ + +/*! +@name Filter component class reference count +@{ +*/ + +/*! +@brief + Increments the \ref api-fund-shared-object "reference count" of + the \bt_flt_comp_cls \bt_p{component_class}. + +@param[in] component_class + @parblock + Filter component class of which to increment the reference count. + + Can be \c NULL. + @endparblock + +@sa bt_component_class_filter_put_ref() — + Decrements the reference count of a filter component class. +*/ +extern void bt_component_class_filter_get_ref( + const bt_component_class_filter *component_class); + +/*! +@brief + Decrements the \ref api-fund-shared-object "reference count" of + the \bt_flt_comp_cls \bt_p{component_class}. + +@param[in] component_class + @parblock + Filter component class of which to decrement the reference count. + + Can be \c NULL. + @endparblock + +@sa bt_component_class_filter_get_ref() — + Increments the reference count of a filter component class. +*/ +extern void bt_component_class_filter_put_ref( + const bt_component_class_filter *component_class); + +/*! +@brief + Decrements the reference count of the \bt_flt_comp_cls + \bt_p{_component_class}, and then sets \bt_p{_component_class} to + \c NULL. + +@param _component_class + @parblock + Filter component class of which to decrement the reference count. + + Can contain \c NULL. + @endparblock + +@bt_pre_assign_expr{_component_class} +*/ +#define BT_COMPONENT_CLASS_FILTER_PUT_REF_AND_RESET(_component_class) \ + do { \ + bt_component_class_filter_put_ref(_component_class); \ + (_component_class) = NULL; \ + } while (0) + +/*! +@brief + Decrements the reference count of the \bt_flt_comp_cls \bt_p{_dst}, + setsc \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to + \c NULL. + +This macro effectively moves a filter component class reference from the +expression \bt_p{_src} to the expression \bt_p{_dst}, putting the +existing \bt_p{_dst} reference. + +@param _dst + @parblock + Destination expression. + + Can contain \c NULL. + @endparblock +@param _src + @parblock + Source expression. + + Can contain \c NULL. + @endparblock + +@bt_pre_assign_expr{_dst} +@bt_pre_assign_expr{_src} +*/ +#define BT_COMPONENT_CLASS_FILTER_MOVE_REF(_dst, _src) \ + do { \ + bt_component_class_filter_put_ref(_dst); \ + (_dst) = (_src); \ + (_src) = NULL; \ + } while (0) + +/*! @} */ + +/*! +@name Sink component class upcast +@{ +*/ + +/*! +@brief + \ref api-fund-c-typing "Upcasts" the \bt_sink_comp_cls + \bt_p{component_class} to the common #bt_component_class type. + +@param[in] component_class + @parblock + Sink component class to upcast. + + Can be \c NULL. + @endparblock + +@returns + \bt_p{component_class} as a common component class. +*/ +static inline +const bt_component_class * +bt_component_class_sink_as_component_class_const( + const bt_component_class_sink *component_class) +{ + return __BT_UPCAST_CONST(bt_component_class, component_class); +} + +/*! @} */ + +/*! +@name Sink component class reference count +@{ +*/ + +/*! +@brief + Increments the \ref api-fund-shared-object "reference count" of + the \bt_sink_comp_cls \bt_p{component_class}. + +@param[in] component_class + @parblock + Sink component class of which to increment the reference count. + + Can be \c NULL. + @endparblock + +@sa bt_component_class_sink_put_ref() — + Decrements the reference count of a sink component class. +*/ +extern void bt_component_class_sink_get_ref( + const bt_component_class_sink *component_class); + +/*! +@brief + Decrements the \ref api-fund-shared-object "reference count" of + the \bt_sink_comp_cls \bt_p{component_class}. + +@param[in] component_class + @parblock + Sink component class of which to decrement the reference count. + + Can be \c NULL. + @endparblock + +@sa bt_component_class_sink_get_ref() — + Increments the reference count of a sink component class. +*/ +extern void bt_component_class_sink_put_ref( + const bt_component_class_sink *component_class); + +/*! +@brief + Decrements the reference count of the \bt_sink_comp_cls + \bt_p{_component_class}, and then sets \bt_p{_component_class} to + \c NULL. + +@param _component_class + @parblock + Sink component class of which to decrement the reference count. + + Can contain \c NULL. + @endparblock + +@bt_pre_assign_expr{_component_class} +*/ +#define BT_COMPONENT_CLASS_SINK_PUT_REF_AND_RESET(_component_class) \ + do { \ + bt_component_class_sink_put_ref(_component_class); \ + (_component_class) = NULL; \ + } while (0) + +/*! +@brief + Decrements the reference count of the \bt_sink_comp_cls \bt_p{_dst}, + sets \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to + \c NULL. + +This macro effectively moves a sink component class reference from the +expression \bt_p{_src} to the expression \bt_p{_dst}, putting the +existing \bt_p{_dst} reference. + +@param _dst + @parblock + Destination expression. + + Can contain \c NULL. + @endparblock +@param _src + @parblock + Source expression. + + Can contain \c NULL. + @endparblock + +@bt_pre_assign_expr{_dst} +@bt_pre_assign_expr{_src} +*/ +#define BT_COMPONENT_CLASS_SINK_MOVE_REF(_dst, _src) \ + do { \ + bt_component_class_sink_put_ref(_dst); \ + (_dst) = (_src); \ + (_src) = NULL; \ + } while (0) + +/*! @} */ + +/*! @} */ #ifdef __cplusplus }