[babeltrace.git] / include / babeltrace2 / graph / component-descriptor-set.h

/*
 * SPDX-License-Identifier: MIT
 *
 * Copyright (C) 2010-2019 EfficiOS Inc. and Linux Foundation
 */

#ifndef BABELTRACE2_GRAPH_COMPONENT_DESCRIPTOR_SET_H
#define BABELTRACE2_GRAPH_COMPONENT_DESCRIPTOR_SET_H

/* IWYU pragma: private, include <babeltrace2/babeltrace.h> */

#ifndef __BT_IN_BABELTRACE_H
# error "Please include <babeltrace2/babeltrace.h> instead."
#endif

#include <babeltrace2/types.h>
#include <babeltrace2/logging.h>

#ifdef __cplusplus
extern "C" {
#endif

/*!
@defgroup api-comp-descr-set Component descriptor set
@ingroup api-graph

@brief
    Set of descriptors of prospective \bt_p_comp to use with
    bt_get_greatest_operative_mip_version().

A <strong><em>component descriptor set</em></strong>
is an \em unordered set of component descriptors.

A <strong><em>component descriptor</em></strong> describes a
prospective \bt_comp, that is, everything that is needed to
\ref api-graph-lc-add "instantiate a component class" within a
trace processing \bt_graph without actually doing it:

- The <strong>component class</strong> to instantiate, which you would
  pass as the \bt_p{component_class} parameter of one of the
  <code>bt_graph_add_*_component*()</code> functions.

- The <strong>initialization parameters</strong>, which you
  would pass as the \bt_p{params} parameter of one of the
  <code>bt_graph_add_*_component*()</code> functions.

- The <strong>initialization method data</strong>, which you would pass
  as the \bt_p{initialize_method_data} parameter of one of the
  <code>bt_graph_add_*_component_with_initialize_method_data()</code>
  functions.

As of \bt_name_version_min_maj, the only use case of a component
descriptor set is bt_get_greatest_operative_mip_version(). This
function computes the greatest \bt_mip version which
you can use to create a trace processing graph to which you intend
to \ref api-graph-lc-add "add components" described by a set of
component descriptors.

A component descriptor set is a
\ref api-fund-shared-object "shared object": get a new reference with
bt_component_descriptor_set_get_ref() and put an existing reference with
bt_component_descriptor_set_put_ref().

Create an empty component descriptor set with
bt_component_descriptor_set_create().

Add a component descriptor to a component descriptor set with
bt_component_descriptor_set_add_descriptor() and
bt_component_descriptor_set_add_descriptor_with_initialize_method_data().
*/

/*! @{ */

/*!
@name Type
@{

@typedef struct bt_component_descriptor_set bt_component_descriptor_set;

@brief
    Component descriptor set.

@}
*/

/*!
@name Creation
@{
*/

/*!
@brief
    Creates an empty component descriptor set.

@returns
    New component descriptor set reference, or \c NULL on memory error.
*/
extern bt_component_descriptor_set *bt_component_descriptor_set_create(void)
		__BT_NOEXCEPT;

/*!
@brief
    Status codes for bt_component_descriptor_set_add_descriptor()
    and
    bt_component_descriptor_set_add_descriptor_with_initialize_method_data().
*/
typedef enum bt_component_descriptor_set_add_descriptor_status {
	/*!
	@brief
	    Success.
	*/
	BT_COMPONENT_DESCRIPTOR_SET_ADD_DESCRIPTOR_STATUS_OK		= __BT_FUNC_STATUS_OK,

	/*!
	@brief
	    Out of memory.
	*/
	BT_COMPONENT_DESCRIPTOR_SET_ADD_DESCRIPTOR_STATUS_MEMORY_ERROR	= __BT_FUNC_STATUS_MEMORY_ERROR,
} bt_component_descriptor_set_add_descriptor_status;

/*! @} */

/*!
@name Component descriptor adding
@{
*/

/*!
@brief
    Alias of
    bt_component_descriptor_set_add_descriptor_with_initialize_method_data()
    with the \bt_p{initialize_method_data} parameter set to \c NULL.
*/
extern bt_component_descriptor_set_add_descriptor_status
bt_component_descriptor_set_add_descriptor(
		bt_component_descriptor_set *component_descriptor_set,
		const bt_component_class *component_class,
		const bt_value *params) __BT_NOEXCEPT;

/*!
@brief
    Adds a descriptor of a \bt_comp which would be an instance of the
    \bt_comp_cls \bt_p{component_class}, would receive the parameters
    \bt_p{params} and the method data \bt_p{initialize_method_data} at
    initialization time, to the component descriptor set
    \bt_p{component_descriptor_set}.

@param[in] component_descriptor_set
    Component descriptor set to which to add a component descriptor.
@param[in] component_class
    \bt_c_comp_cls which would be instantiated to create the
    described component.
@param[in] params
    @parblock
    Parameters which would be passed to the initialization method of
    the described component as the \bt_p{params} parameter.

    Can be \c NULL, in which case it is equivalent to passing an empty
    \bt_map_val.
    @endparblock
@param[in] initialize_method_data
    User data which would be passed to the initialization method of
    the described component as the \bt_p{initialize_method_data}
    parameter.

@retval #BT_COMPONENT_DESCRIPTOR_SET_ADD_DESCRIPTOR_STATUS_OK
    Success.
@retval #BT_COMPONENT_DESCRIPTOR_SET_ADD_DESCRIPTOR_STATUS_MEMORY_ERROR
    Out of memory.

@bt_pre_not_null{component_descriptor_set}
@bt_pre_not_null{component_class}
@pre
    \bt_p{params} is a \bt_map_val (bt_value_is_map() returns #BT_TRUE)
    or is \c NULL.

@bt_post_success_frozen{component_class}
@bt_post_success_frozen{params}
*/
extern bt_component_descriptor_set_add_descriptor_status
bt_component_descriptor_set_add_descriptor_with_initialize_method_data(
		bt_component_descriptor_set *component_descriptor_set,
		const bt_component_class *component_class,
		const bt_value *params,
		void *initialize_method_data) __BT_NOEXCEPT;

/*! @} */

/*!
@name Reference count
@{
*/

/*!
@brief
    Increments the \ref api-fund-shared-object "reference count" of
    the component descriptor set \bt_p{component_descriptor_set}.

@param[in] component_descriptor_set
    @parblock
    Component descriptor set of which to increment the reference count.

    Can be \c NULL.
    @endparblock

@sa bt_component_descriptor_set_put_ref() &mdash;
    Decrements the reference count of a component descriptor set.
*/
extern void bt_component_descriptor_set_get_ref(
		const bt_component_descriptor_set *component_descriptor_set)
		__BT_NOEXCEPT;

/*!
@brief
    Decrements the \ref api-fund-shared-object "reference count" of
    the component descriptor set \bt_p{component_descriptor_set}.

@param[in] component_descriptor_set
    @parblock
    Component descriptor set of which to decrement the reference count.

    Can be \c NULL.
    @endparblock

@sa bt_component_descriptor_set_get_ref() &mdash;
    Increments the reference count of a component descriptor set.
*/
extern void bt_component_descriptor_set_put_ref(
		const bt_component_descriptor_set *component_descriptor_set)
		__BT_NOEXCEPT;

/*!
@brief
    Decrements the reference count of the component descriptor set
    \bt_p{_component_descriptor_set}, and then sets
    \bt_p{_component_descriptor_set} to \c NULL.

@param _component_descriptor_set
    @parblock
    Component descriptor set of which to decrement the reference count.

    Can contain \c NULL.
    @endparblock

@bt_pre_assign_expr{_component_descriptor_set}
*/
#define BT_COMPONENT_DESCRIPTOR_SET_PUT_REF_AND_RESET(_component_descriptor_set) \
	do {								\
		bt_component_descriptor_set_put_ref(_component_descriptor_set); \
		(_component_descriptor_set) = NULL;			\
	} while (0)

/*!
@brief
    Decrements the reference count of the component descriptor set
    \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 descriptor set 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_DESCRIPTOR_SET_MOVE_REF(_dst, _src)	\
	do {							\
		bt_component_descriptor_set_put_ref(_dst);	\
		(_dst) = (_src);				\
		(_src) = NULL;					\
	} while (0)

/*! @} */

/*! @} */

#ifdef __cplusplus
}
#endif

#endif /* BABELTRACE2_GRAPH_COMPONENT_DESCRIPTOR_SET_H */
Commit	Line	Data
	1	/*
	2	* SPDX-License-Identifier: MIT
	3	*
	4	* Copyright (C) 2010-2019 EfficiOS Inc. and Linux Foundation
	5	*/
	6
	7	#ifndef BABELTRACE2_GRAPH_COMPONENT_DESCRIPTOR_SET_H
	8	#define BABELTRACE2_GRAPH_COMPONENT_DESCRIPTOR_SET_H
	9
	10	/* IWYU pragma: private, include <babeltrace2/babeltrace.h> */
	11
	12	#ifndef __BT_IN_BABELTRACE_H
	13	# error "Please include <babeltrace2/babeltrace.h> instead."
	14	#endif
	15
	16	#include <babeltrace2/types.h>
	17	#include <babeltrace2/logging.h>
	18
	19	#ifdef __cplusplus
	20	extern "C" {
	21	#endif
	22
	23	/*!
	24	@defgroup api-comp-descr-set Component descriptor set
	25	@ingroup api-graph
	26
	27	@brief
	28	Set of descriptors of prospective \bt_p_comp to use with
	29	bt_get_greatest_operative_mip_version().
	30
	31	A <strong><em>component descriptor set</em></strong>
	32	is an \em unordered set of component descriptors.
	33
	34	A <strong><em>component descriptor</em></strong> describes a
	35	prospective \bt_comp, that is, everything that is needed to
	36	\ref api-graph-lc-add "instantiate a component class" within a
	37	trace processing \bt_graph without actually doing it:
	38
	39	- The <strong>component class</strong> to instantiate, which you would
	40	pass as the \bt_p{component_class} parameter of one of the
	41	<code>bt_graph_add__component()</code> functions.
	42
	43	- The <strong>initialization parameters</strong>, which you
	44	would pass as the \bt_p{params} parameter of one of the
	45	<code>bt_graph_add__component()</code> functions.
	46
	47	- The <strong>initialization method data</strong>, which you would pass
	48	as the \bt_p{initialize_method_data} parameter of one of the
	49	<code>bt_graph_add_*_component_with_initialize_method_data()</code>
	50	functions.
	51
	52	As of \bt_name_version_min_maj, the only use case of a component
	53	descriptor set is bt_get_greatest_operative_mip_version(). This
	54	function computes the greatest \bt_mip version which
	55	you can use to create a trace processing graph to which you intend
	56	to \ref api-graph-lc-add "add components" described by a set of
	57	component descriptors.
	58
	59	A component descriptor set is a
	60	\ref api-fund-shared-object "shared object": get a new reference with
	61	bt_component_descriptor_set_get_ref() and put an existing reference with
	62	bt_component_descriptor_set_put_ref().
	63
	64	Create an empty component descriptor set with
	65	bt_component_descriptor_set_create().
	66
	67	Add a component descriptor to a component descriptor set with
	68	bt_component_descriptor_set_add_descriptor() and
	69	bt_component_descriptor_set_add_descriptor_with_initialize_method_data().
	70	*/
	71
	72	/! @{ /
	73
	74	/*!
	75	@name Type
	76	@{
	77
	78	@typedef struct bt_component_descriptor_set bt_component_descriptor_set;
	79
	80	@brief
	81	Component descriptor set.
	82
	83	@}
	84	*/
	85
	86	/*!
	87	@name Creation
	88	@{
	89	*/
	90
	91	/*!
	92	@brief
	93	Creates an empty component descriptor set.
	94
	95	@returns
	96	New component descriptor set reference, or \c NULL on memory error.
	97	*/
	98	extern bt_component_descriptor_set *bt_component_descriptor_set_create(void)
	99	__BT_NOEXCEPT;
	100
	101	/*!
	102	@brief
	103	Status codes for bt_component_descriptor_set_add_descriptor()
	104	and
	105	bt_component_descriptor_set_add_descriptor_with_initialize_method_data().
	106	*/
	107	typedef enum bt_component_descriptor_set_add_descriptor_status {
	108	/*!
	109	@brief
	110	Success.
	111	*/
	112	BT_COMPONENT_DESCRIPTOR_SET_ADD_DESCRIPTOR_STATUS_OK = __BT_FUNC_STATUS_OK,
	113
	114	/*!
	115	@brief
	116	Out of memory.
	117	*/
	118	BT_COMPONENT_DESCRIPTOR_SET_ADD_DESCRIPTOR_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
	119	} bt_component_descriptor_set_add_descriptor_status;
	120
	121	/! @} /
	122
	123	/*!
	124	@name Component descriptor adding
	125	@{
	126	*/
	127
	128	/*!
	129	@brief
	130	Alias of
	131	bt_component_descriptor_set_add_descriptor_with_initialize_method_data()
	132	with the \bt_p{initialize_method_data} parameter set to \c NULL.
	133	*/
	134	extern bt_component_descriptor_set_add_descriptor_status
	135	bt_component_descriptor_set_add_descriptor(
	136	bt_component_descriptor_set *component_descriptor_set,
	137	const bt_component_class *component_class,
	138	const bt_value *params) __BT_NOEXCEPT;
	139
	140	/*!
	141	@brief
	142	Adds a descriptor of a \bt_comp which would be an instance of the
	143	\bt_comp_cls \bt_p{component_class}, would receive the parameters
	144	\bt_p{params} and the method data \bt_p{initialize_method_data} at
	145	initialization time, to the component descriptor set
	146	\bt_p{component_descriptor_set}.
	147
	148	@param[in] component_descriptor_set
	149	Component descriptor set to which to add a component descriptor.
	150	@param[in] component_class
	151	\bt_c_comp_cls which would be instantiated to create the
	152	described component.
	153	@param[in] params
	154	@parblock
	155	Parameters which would be passed to the initialization method of
	156	the described component as the \bt_p{params} parameter.
	157
	158	Can be \c NULL, in which case it is equivalent to passing an empty
	159	\bt_map_val.
	160	@endparblock
	161	@param[in] initialize_method_data
	162	User data which would be passed to the initialization method of
	163	the described component as the \bt_p{initialize_method_data}
	164	parameter.
	165
	166	@retval #BT_COMPONENT_DESCRIPTOR_SET_ADD_DESCRIPTOR_STATUS_OK
	167	Success.
	168	@retval #BT_COMPONENT_DESCRIPTOR_SET_ADD_DESCRIPTOR_STATUS_MEMORY_ERROR
	169	Out of memory.
	170
	171	@bt_pre_not_null{component_descriptor_set}
	172	@bt_pre_not_null{component_class}
	173	@pre
	174	\bt_p{params} is a \bt_map_val (bt_value_is_map() returns #BT_TRUE)
	175	or is \c NULL.
	176
	177	@bt_post_success_frozen{component_class}
	178	@bt_post_success_frozen{params}
	179	*/
	180	extern bt_component_descriptor_set_add_descriptor_status
	181	bt_component_descriptor_set_add_descriptor_with_initialize_method_data(
	182	bt_component_descriptor_set *component_descriptor_set,
	183	const bt_component_class *component_class,
	184	const bt_value *params,
	185	void *initialize_method_data) __BT_NOEXCEPT;
	186
	187	/! @} /
	188
	189	/*!
	190	@name Reference count
	191	@{
	192	*/
	193
	194	/*!
	195	@brief
	196	Increments the \ref api-fund-shared-object "reference count" of
	197	the component descriptor set \bt_p{component_descriptor_set}.
	198
	199	@param[in] component_descriptor_set
	200	@parblock
	201	Component descriptor set of which to increment the reference count.
	202
	203	Can be \c NULL.
	204	@endparblock
	205
	206	@sa bt_component_descriptor_set_put_ref() —
	207	Decrements the reference count of a component descriptor set.
	208	*/
	209	extern void bt_component_descriptor_set_get_ref(
	210	const bt_component_descriptor_set *component_descriptor_set)
	211	__BT_NOEXCEPT;
	212
	213	/*!
	214	@brief
	215	Decrements the \ref api-fund-shared-object "reference count" of
	216	the component descriptor set \bt_p{component_descriptor_set}.
	217
	218	@param[in] component_descriptor_set
	219	@parblock
	220	Component descriptor set of which to decrement the reference count.
	221
	222	Can be \c NULL.
	223	@endparblock
	224
	225	@sa bt_component_descriptor_set_get_ref() —
	226	Increments the reference count of a component descriptor set.
	227	*/
	228	extern void bt_component_descriptor_set_put_ref(
	229	const bt_component_descriptor_set *component_descriptor_set)
	230	__BT_NOEXCEPT;
	231
	232	/*!
	233	@brief
	234	Decrements the reference count of the component descriptor set
	235	\bt_p{_component_descriptor_set}, and then sets
	236	\bt_p{_component_descriptor_set} to \c NULL.
	237
	238	@param _component_descriptor_set
	239	@parblock
	240	Component descriptor set of which to decrement the reference count.
	241
	242	Can contain \c NULL.
	243	@endparblock
	244
	245	@bt_pre_assign_expr{_component_descriptor_set}
	246	*/
	247	#define BT_COMPONENT_DESCRIPTOR_SET_PUT_REF_AND_RESET(_component_descriptor_set) \
	248	do { \
	249	bt_component_descriptor_set_put_ref(_component_descriptor_set); \
	250	(_component_descriptor_set) = NULL; \
	251	} while (0)
	252
	253	/*!
	254	@brief
	255	Decrements the reference count of the component descriptor set
	256	\bt_p{_dst}, sets \bt_p{_dst} to \bt_p{_src}, and then sets
	257	\bt_p{_src} to \c NULL.
	258
	259	This macro effectively moves a component descriptor set reference from
	260	the expression \bt_p{_src} to the expression \bt_p{_dst}, putting the
	261	existing \bt_p{_dst} reference.
	262
	263	@param _dst
	264	@parblock
	265	Destination expression.
	266
	267	Can contain \c NULL.
	268	@endparblock
	269	@param _src
	270	@parblock
	271	Source expression.
	272
	273	Can contain \c NULL.
	274	@endparblock
	275
	276	@bt_pre_assign_expr{_dst}
	277	@bt_pre_assign_expr{_src}
	278	*/
	279	#define BT_COMPONENT_DESCRIPTOR_SET_MOVE_REF(_dst, _src) \
	280	do { \
	281	bt_component_descriptor_set_put_ref(_dst); \
	282	(_dst) = (_src); \
	283	(_src) = NULL; \
	284	} while (0)
	285
	286	/! @} /
	287
	288	/! @} /
	289
	290	#ifdef __cplusplus
	291	}
	292	#endif
	293
	294	#endif /* BABELTRACE2_GRAPH_COMPONENT_DESCRIPTOR_SET_H */