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

#ifndef BABELTRACE2_GRAPH_COMPONENT_DESCRIPTOR_SET_H
#define BABELTRACE2_GRAPH_COMPONENT_DESCRIPTOR_SET_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:
 *
 * 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.
 */

#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);

/*!
@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);

/*!
@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);

/*! @} */

/*!
@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);

/*!
@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);

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