#define BABELTRACE2_GRAPH_COMPONENT_CLASS_H
/*
- * Copyright 2017-2018 Philippe Proulx <pproulx@efficios.com>
- * Copyright 2016 Jérémie Galarneau <jeremie.galarneau@efficios.com>
+ * 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
# error "Please include <babeltrace2/babeltrace.h> instead."
#endif
-/* For bt_component_class */
#include <babeltrace2/types.h>
#ifdef __cplusplus
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_INVALID_PARAMS = __BT_FUNC_STATUS_INVALID_PARAMS,
-} 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 <strong><em>component class</em></strong> 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
+<code>bt_graph_add_*_component*()</code> 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:
+
+<dl>
+ <dt>\anchor api-comp-cls-src Source component class</dt>
+ <dd>
+ 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().
+ </dd>
+
+ <dt>\anchor api-comp-cls-flt Filter component class</dt>
+ <dd>
+ 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().
+ </dd>
+
+ <dt>\anchor api-comp-cls-sink Sink component class</dt>
+ <dd>
+ 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().
+ </dd>
+</dl>
+
+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.
+
+<h1>Properties</h1>
+
+A component class has the following common properties:
+
+<dl>
+ <dt>
+ \anchor api-comp-cls-prop-name
+ Name
+ </dt>
+ <dd>
+ 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().
+ </dd>
+
+ <dt>
+ \anchor api-comp-cls-prop-descr
+ \bt_dt_opt Description
+ </dt>
+ <dd>
+ Textual description of the component class.
+
+ Get a component class's description with
+ bt_component_class_get_description().
+ </dd>
+
+ <dt>
+ \anchor api-comp-cls-prop-help
+ \bt_dt_opt Help text
+ </dt>
+ <dd>
+ Help text of the component class.
+
+ Get a component class's help text with
+ bt_component_class_get_help().
+ </dd>
+</dl>
+*/
+
+/*! @{ */
+
+/*!
+@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
}