+/*!
+@defgroup api-self-comp Self components
+@ingroup api-comp-cls-dev
+
+@brief
+ Private views of \bt_p_comp for instance methods.
+
+The #bt_self_component, #bt_self_component_source,
+#bt_self_component_filter, #bt_self_component_sink types are
+private views of a \bt_comp from within a component class
+\ref api-comp-cls-dev-instance-meth "instance method".
+
+Add a \bt_port to a component with
+bt_self_component_source_add_output_port(),
+bt_self_component_filter_add_input_port(),
+bt_self_component_filter_add_output_port(), and
+bt_self_component_sink_add_input_port().
+
+When you add a port to a component, you can attach custom user data
+to it (\bt_voidp). You can retrieve this user data
+afterwards with bt_self_component_port_get_data().
+
+Borrow a \bt_self_comp_port from a component by index with
+bt_self_component_source_borrow_output_port_by_index(),
+bt_self_component_filter_borrow_input_port_by_index(),
+bt_self_component_filter_borrow_output_port_by_index(), and
+bt_self_component_sink_borrow_input_port_by_index().
+
+Borrow a \bt_self_comp_port from a component by name with
+bt_self_component_source_borrow_output_port_by_name(),
+bt_self_component_filter_borrow_input_port_by_name(),
+bt_self_component_filter_borrow_output_port_by_name(), and
+bt_self_component_sink_borrow_input_port_by_name().
+
+Set and get user data attached to a component with
+bt_self_component_set_data() and bt_self_component_get_data().
+
+Get a component's owning trace processing \bt_graph's effective
+\bt_mip version with bt_self_component_get_graph_mip_version().
+
+Check whether or not a \bt_sink_comp is interrupted with
+bt_self_component_sink_is_interrupted().
+
+\ref api-fund-c-typing "Upcast" the "self" (private) types to the
+public and common self component types with the
+<code>bt_self_component*_as_component*()</code> and
+<code>bt_self_component_*_as_self_component()</code> functions.
+*/
+
+/*! @{ */
+
+/*!
+@name Types
+@{
+
+@typedef struct bt_self_component bt_self_component;
+
+@brief
+ Self \bt_comp.
+
+@typedef struct bt_self_component_source bt_self_component_source;
+
+@brief
+ Self \bt_src_comp.
+
+@typedef struct bt_self_component_filter bt_self_component_filter;
+
+@brief
+ Self \bt_flt_comp.
+
+@typedef struct bt_self_component_sink bt_self_component_sink;
+
+@brief
+ Self \bt_sink_comp.
+
+@typedef struct bt_self_component_source_configuration bt_self_component_source_configuration;
+
+@brief
+ Self \bt_src_comp configuration.
+
+@typedef struct bt_self_component_filter_configuration bt_self_component_filter_configuration;
+
+@brief
+ Self \bt_flt_comp configuration.
+
+@typedef struct bt_self_component_sink_configuration bt_self_component_sink_configuration;
+
+@brief
+ Self \bt_sink_comp configuration.
+
+@}
+*/
+
+/*!
+@name Port adding
+@{
+*/
+
+/*!
+@brief
+ Status codes for bt_self_component_source_add_output_port(),
+ bt_self_component_filter_add_input_port(),
+ bt_self_component_filter_add_output_port(), and
+ bt_self_component_sink_add_input_port().
+*/
+typedef enum bt_self_component_add_port_status {
+ /*!
+ @brief
+ Success.
+ */
+ BT_SELF_COMPONENT_ADD_PORT_STATUS_OK = __BT_FUNC_STATUS_OK,
+
+ /*!
+ @brief
+ Out of memory.
+ */
+ BT_SELF_COMPONENT_ADD_PORT_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
+
+ /*!
+ @brief
+ Other error.
+ */
+ BT_SELF_COMPONENT_ADD_PORT_STATUS_ERROR = __BT_FUNC_STATUS_ERROR,
+} bt_self_component_add_port_status;
+
+/*!
+@brief
+ Adds an \bt_oport named \bt_p{name} and having the user data
+ \bt_p{user_data} to the \bt_src_comp \bt_p{self_component},
+ and sets \bt_p{*self_component_port} to the resulting port.
+
+@attention
+ You can only call this function from within the
+ \ref api-comp-cls-dev-meth-init "initialization",
+ \link api-comp-cls-dev-meth-iport-connected "input port connected"\endlink,
+ and
+ \link api-comp-cls-dev-meth-oport-connected "output port connected"\endlink
+ methods.
+
+@param[in] self_component
+ Source component instance.
+@param[in] name
+ Name of the output port to add to \bt_p{self_component} (copied).
+@param[in] user_data
+ User data of the output port to add to \bt_p{self_component}.
+@param[out] self_component_port
+ <strong>On success, if not \c NULL</strong>,
+ \bt_p{*self_component_port} is a \em borrowed reference of the
+ created port.
+
+@retval #BT_SELF_COMPONENT_ADD_PORT_STATUS_OK
+ Success.
+@retval #BT_SELF_COMPONENT_ADD_PORT_STATUS_MEMORY_ERROR
+ Out of memory.
+@retval #BT_SELF_COMPONENT_ADD_PORT_STATUS_ERROR
+ Other error.
+
+@bt_pre_not_null{self_component}
+@bt_pre_not_null{name}
+@pre
+ No other output port within \bt_p{self_component} has the name
+ \bt_p{name}.
+*/
+extern bt_self_component_add_port_status
+bt_self_component_source_add_output_port(
+ bt_self_component_source *self_component,
+ const char *name, void *user_data,
+ bt_self_component_port_output **self_component_port);
+
+/*!
+@brief
+ Adds an \bt_iport named \bt_p{name} and having the user data
+ \bt_p{user_data} to the \bt_flt_comp \bt_p{self_component},
+ and sets \bt_p{*self_component_port} to the resulting port.
+
+@attention
+ You can only call this function from within the
+ \ref api-comp-cls-dev-meth-init "initialization",
+ \link api-comp-cls-dev-meth-iport-connected "input port connected"\endlink,
+ and
+ \link api-comp-cls-dev-meth-oport-connected "output port connected"\endlink
+ methods.
+
+@param[in] self_component
+ Filter component instance.
+@param[in] name
+ Name of the input port to add to \bt_p{self_component} (copied).
+@param[in] user_data
+ User data of the input port to add to \bt_p{self_component}.
+@param[out] self_component_port
+ <strong>On success, if not \c NULL</strong>,
+ \bt_p{*self_component_port} is a \em borrowed reference of the
+ created port.
+
+@retval #BT_SELF_COMPONENT_ADD_PORT_STATUS_OK
+ Success.
+@retval #BT_SELF_COMPONENT_ADD_PORT_STATUS_MEMORY_ERROR
+ Out of memory.
+@retval #BT_SELF_COMPONENT_ADD_PORT_STATUS_ERROR
+ Other error.
+
+@bt_pre_not_null{self_component}
+@bt_pre_not_null{name}
+@pre
+ No other input port within \bt_p{self_component} has the name
+ \bt_p{name}.
+*/
+extern bt_self_component_add_port_status
+bt_self_component_filter_add_input_port(
+ bt_self_component_filter *self_component,
+ const char *name, void *user_data,
+ bt_self_component_port_input **self_component_port);
+
+/*!
+@brief
+ Adds an \bt_oport named \bt_p{name} and having the user data
+ \bt_p{user_data} to the \bt_flt_comp \bt_p{self_component},
+ and sets \bt_p{*self_component_port} to the resulting port.
+
+@attention
+ You can only call this function from within the
+ \ref api-comp-cls-dev-meth-init "initialization",
+ \link api-comp-cls-dev-meth-iport-connected "input port connected"\endlink,
+ and
+ \link api-comp-cls-dev-meth-oport-connected "output port connected"\endlink
+ methods.
+
+@param[in] self_component
+ Filter component instance.
+@param[in] name
+ Name of the output port to add to \bt_p{self_component} (copied).
+@param[in] user_data
+ User data of the output port to add to \bt_p{self_component}.
+@param[out] self_component_port
+ <strong>On success, if not \c NULL</strong>,
+ \bt_p{*self_component_port} is a \em borrowed reference of the
+ created port.
+
+@retval #BT_SELF_COMPONENT_ADD_PORT_STATUS_OK
+ Success.
+@retval #BT_SELF_COMPONENT_ADD_PORT_STATUS_MEMORY_ERROR
+ Out of memory.
+@retval #BT_SELF_COMPONENT_ADD_PORT_STATUS_ERROR
+ Other error.
+
+@bt_pre_not_null{self_component}
+@bt_pre_not_null{name}
+@pre
+ No other output port within \bt_p{self_component} has the name
+ \bt_p{name}.
+*/
+extern bt_self_component_add_port_status
+bt_self_component_filter_add_output_port(
+ bt_self_component_filter *self_component,
+ const char *name, void *user_data,
+ bt_self_component_port_output **self_component_port);
+
+/*!
+@brief
+ Adds an \bt_iport named \bt_p{name} and having the user data
+ \bt_p{user_data} to the \bt_sink_comp \bt_p{self_component},
+ and sets \bt_p{*self_component_port} to the resulting port.
+
+@attention
+ You can only call this function from within the
+ \ref api-comp-cls-dev-meth-init "initialization",
+ \link api-comp-cls-dev-meth-iport-connected "input port connected"\endlink,
+ and
+ \link api-comp-cls-dev-meth-oport-connected "output port connected"\endlink
+ methods.
+
+@param[in] self_component
+ Sink component instance.
+@param[in] name
+ Name of the input port to add to \bt_p{self_component} (copied).
+@param[in] user_data
+ User data of the input port to add to \bt_p{self_component}.
+@param[out] self_component_port
+ <strong>On success, if not \c NULL</strong>,
+ \bt_p{*self_component_port} is a \em borrowed reference of the
+ created port.
+
+@retval #BT_SELF_COMPONENT_ADD_PORT_STATUS_OK
+ Success.
+@retval #BT_SELF_COMPONENT_ADD_PORT_STATUS_MEMORY_ERROR
+ Out of memory.
+@retval #BT_SELF_COMPONENT_ADD_PORT_STATUS_ERROR
+ Other error.
+
+@bt_pre_not_null{self_component}
+@bt_pre_not_null{name}
+@pre
+ No other input port within \bt_p{self_component} has the name
+ \bt_p{name}.
+*/
+
+extern bt_self_component_add_port_status
+bt_self_component_sink_add_input_port(
+ bt_self_component_sink *self_component,
+ const char *name, void *user_data,
+ bt_self_component_port_input **self_component_port);
+
+/*! @} */
+
+/*!
+@name Port access
+@{
+*/
+
+/*!
+@brief
+ Borrows the \bt_self_comp_oport at index \bt_p{index} from the
+ \bt_src_comp \bt_p{self_component}.
+
+@param[in] self_component
+ Source component instance.
+@param[in] index
+ Index of the output port to borrow from \bt_p{self_component}.
+
+@returns
+ @parblock
+ \em Borrowed reference of the output port of
+ \bt_p{self_component} at index \bt_p{index}.
+
+ The returned pointer remains valid as long as \bt_p{self_component}
+ exists.
+ @endparblock
+
+@bt_pre_not_null{self_component}
+@pre
+ \bt_p{index} is less than the number of output ports
+ \bt_p{self_component} has (as returned by
+ bt_component_source_get_output_port_count()).
+
+@sa bt_component_source_get_output_port_count() —
+ Returns the number of output ports that a source component has.
+*/
+extern bt_self_component_port_output *
+bt_self_component_source_borrow_output_port_by_index(
+ bt_self_component_source *self_component,
+ uint64_t index);
+
+/*!
+@brief
+ Borrows the \bt_self_comp_iport at index \bt_p{index} from the
+ \bt_flt_comp \bt_p{self_component}.
+
+@param[in] self_component
+ Filter component instance.
+@param[in] index
+ Index of the input port to borrow from \bt_p{self_component}.
+
+@returns
+ @parblock
+ \em Borrowed reference of the input port of
+ \bt_p{self_component} at index \bt_p{index}.
+
+ The returned pointer remains valid as long as \bt_p{self_component}
+ exists.
+ @endparblock
+
+@bt_pre_not_null{self_component}
+@pre
+ \bt_p{index} is less than the number of input ports
+ \bt_p{self_component} has (as returned by
+ bt_component_filter_get_input_port_count()).
+
+@sa bt_component_filter_get_input_port_count() —
+ Returns the number of input ports that a filter component has.
+*/
+extern bt_self_component_port_input *
+bt_self_component_filter_borrow_input_port_by_index(
+ bt_self_component_filter *self_component,
+ uint64_t index);
+
+/*!
+@brief
+ Borrows the \bt_self_comp_oport at index \bt_p{index} from the
+ \bt_flt_comp \bt_p{self_component}.
+
+@param[in] self_component
+ Filter component instance.
+@param[in] index
+ Index of the output port to borrow from \bt_p{self_component}.
+
+@returns
+ @parblock
+ \em Borrowed reference of the output port of
+ \bt_p{self_component} at index \bt_p{index}.
+
+ The returned pointer remains valid as long as \bt_p{self_component}
+ exists.
+ @endparblock
+
+@bt_pre_not_null{self_component}
+@pre
+ \bt_p{index} is less than the number of output ports
+ \bt_p{self_component} has (as returned by
+ bt_component_filter_get_output_port_count()).
+
+@sa bt_component_filter_get_output_port_count() —
+ Returns the number of output ports that a filter component has.
+*/
+extern bt_self_component_port_output *
+bt_self_component_filter_borrow_output_port_by_index(
+ bt_self_component_filter *self_component,
+ uint64_t index);
+
+/*!
+@brief
+ Borrows the \bt_self_comp_iport at index \bt_p{index} from the
+ \bt_sink_comp \bt_p{self_component}.
+
+@param[in] self_component
+ Sink component instance.
+@param[in] index
+ Index of the input port to borrow from \bt_p{self_component}.
+
+@returns
+ @parblock
+ \em Borrowed reference of the input port of
+ \bt_p{self_component} at index \bt_p{index}.
+
+ The returned pointer remains valid as long as \bt_p{self_component}
+ exists.
+ @endparblock
+
+@bt_pre_not_null{self_component}
+@pre
+ \bt_p{index} is less than the number of input ports
+ \bt_p{self_component} has (as returned by
+ bt_component_sink_get_input_port_count()).
+
+@sa bt_component_sink_get_input_port_count() —
+ Returns the number of input ports that a sink component has.
+*/
+extern bt_self_component_port_input *
+bt_self_component_sink_borrow_input_port_by_index(
+ bt_self_component_sink *self_component, uint64_t index);
+
+/*!
+@brief
+ Borrows the \bt_self_comp_oport named \bt_p{name} from the
+ \bt_src_comp \bt_p{self_component}.
+
+If \bt_p{self_component} has no output port named \bt_p{name}, this
+function returns \c NULL.
+
+@param[in] self_component
+ Source component instance.
+@param[in] name
+ Name of the output port to borrow from \bt_p{self_component}.
+
+@returns
+ @parblock
+ \em Borrowed reference of the output port of
+ \bt_p{self_component} named \bt_p{name}, or \c NULL if none.
+
+ The returned pointer remains valid as long as \bt_p{self_component}
+ exists.
+ @endparblock
+
+@bt_pre_not_null{self_component}
+@bt_pre_not_null{name}
+*/
+extern bt_self_component_port_output *
+bt_self_component_source_borrow_output_port_by_name(
+ bt_self_component_source *self_component,
+ const char *name);
+
+/*!
+@brief
+ Borrows the \bt_self_comp_iport named \bt_p{name} from the
+ \bt_flt_comp \bt_p{self_component}.
+
+If \bt_p{self_component} has no input port named \bt_p{name}, this
+function returns \c NULL.
+
+@param[in] self_component
+ Filter component instance.
+@param[in] name
+ Name of the input port to borrow from \bt_p{self_component}.
+
+@returns
+ @parblock
+ \em Borrowed reference of the input port of
+ \bt_p{self_component} named \bt_p{name}, or \c NULL if none.
+
+ The returned pointer remains valid as long as \bt_p{self_component}
+ exists.
+ @endparblock
+
+@bt_pre_not_null{self_component}
+@bt_pre_not_null{name}
+*/
+extern bt_self_component_port_input *
+bt_self_component_filter_borrow_input_port_by_name(
+ bt_self_component_filter *self_component,
+ const char *name);