Component descriptor set

Detailed Description

Set of descriptors of prospective components to use with bt_get_greatest_operative_mip_version().

A component descriptor set is an unordered set of component descriptors.

A component descriptor describes a prospective component, that is, everything that is needed to instantiate a component class within a trace processing graph without actually doing it:

• The component class to instantiate, which you would pass as the component_class parameter of one of the bt_graph_add_*_component*() functions.
• The initialization parameters, which you would pass as the params parameter of one of the bt_graph_add_*_component*() functions.
• The initialization method data, which you would pass as the initialize_method_data parameter of one of the bt_graph_add_*_component_with_initialize_method_data() functions.

As of Babeltrace 2.0, the only use case of a component descriptor set is bt_get_greatest_operative_mip_version(). This function computes the greatest Message Interchange Protocol version which you can use to create a trace processing graph to which you intend to add components described by a set of component descriptors.

A component descriptor set is a 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().

Creation
enum	bt_component_descriptor_set_add_descriptor_status {   BT_COMPONENT_DESCRIPTOR_SET_ADD_DESCRIPTOR_STATUS_OK ,   BT_COMPONENT_DESCRIPTOR_SET_ADD_DESCRIPTOR_STATUS_MEMORY_ERROR }
	Status codes for bt_component_descriptor_set_add_descriptor() and bt_component_descriptor_set_add_descriptor_with_initialize_method_data(). More...
typedef enum bt_component_descriptor_set_add_descriptor_status	bt_component_descriptor_set_add_descriptor_status
	Status codes for bt_component_descriptor_set_add_descriptor() and bt_component_descriptor_set_add_descriptor_with_initialize_method_data().
bt_component_descriptor_set *	bt_component_descriptor_set_create (void)
	Creates an empty component descriptor set.

Type
typedef struct bt_component_descriptor_set	bt_component_descriptor_set
	Component descriptor set.

Component descriptor adding
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)
	Alias of bt_component_descriptor_set_add_descriptor_with_initialize_method_data() with the initialize_method_data parameter set to NULL.
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)
	Adds a descriptor of a component which would be an instance of the component class component_class, would receive the parameters params and the method data initialize_method_data at initialization time, to the component descriptor set component_descriptor_set.

Reference count
void	bt_component_descriptor_set_get_ref (const bt_component_descriptor_set *component_descriptor_set)
	Increments the reference count of the component descriptor set component_descriptor_set.
void	bt_component_descriptor_set_put_ref (const bt_component_descriptor_set *component_descriptor_set)
	Decrements the reference count of the component descriptor set component_descriptor_set.
#define	BT_COMPONENT_DESCRIPTOR_SET_PUT_REF_AND_RESET(_component_descriptor_set)
	Decrements the reference count of the component descriptor set _component_descriptor_set, and then sets _component_descriptor_set to NULL.
#define	BT_COMPONENT_DESCRIPTOR_SET_MOVE_REF(_dst, _src)
	Decrements the reference count of the component descriptor set _dst, sets _dst to _src, and then sets _src to NULL.

Enumeration Type Documentation

bt_component_descriptor_set_add_descriptor_status

enum bt_component_descriptor_set_add_descriptor_status

Status codes for bt_component_descriptor_set_add_descriptor() and bt_component_descriptor_set_add_descriptor_with_initialize_method_data().

Enumerator
BT_COMPONENT_DESCRIPTOR_SET_ADD_DESCRIPTOR_STATUS_OK	Success.
BT_COMPONENT_DESCRIPTOR_SET_ADD_DESCRIPTOR_STATUS_MEMORY_ERROR	Out of memory.

Macro Definition Documentation

BT_COMPONENT_DESCRIPTOR_SET_PUT_REF_AND_RESET

#define BT_COMPONENT_DESCRIPTOR_SET_PUT_REF_AND_RESET

(

_component_descriptor_set

)

Decrements the reference count of the component descriptor set _component_descriptor_set, and then sets _component_descriptor_set to NULL.

Parameters

_component_descriptor_set

Component descriptor set of which to decrement the reference count. Can contain NULL.

Precondition

_component_descriptor_set is an assignable expression.

BT_COMPONENT_DESCRIPTOR_SET_MOVE_REF

#define BT_COMPONENT_DESCRIPTOR_SET_MOVE_REF	(		_dst,
			_src )

Decrements the reference count of the component descriptor set _dst, sets _dst to _src, and then sets _src to NULL.

This macro effectively moves a component descriptor set reference from the expression _src to the expression _dst, putting the existing _dst reference.

Parameters

_dst	Destination expression. Can contain NULL.
_src	Source expression. Can contain NULL.

Precondition

_dst is an assignable expression.

_src is an assignable expression.

Function Documentation

bt_component_descriptor_set_create()

bt_component_descriptor_set * bt_component_descriptor_set_create ( void )

extern

Creates an empty component descriptor set.

Returns

New component descriptor set reference, or NULL on memory error.

bt_component_descriptor_set_add_descriptor_with_initialize_method_data()

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 )

extern

Adds a descriptor of a component which would be an instance of the component class component_class, would receive the parameters params and the method data initialize_method_data at initialization time, to the component descriptor set component_descriptor_set.

Parameters

[in]	component_descriptor_set	Component descriptor set to which to add a component descriptor.
[in]	component_class	Component class which would be instantiated to create the described component.
[in]	params	Parameters which would be passed to the initialization method of the described component as the params parameter. Can be NULL, in which case it is equivalent to passing an empty map value.
[in]	initialize_method_data	User data which would be passed to the initialization method of the described component as the initialize_method_data parameter.

Return values

BT_COMPONENT_DESCRIPTOR_SET_ADD_DESCRIPTOR_STATUS_OK	Success.
BT_COMPONENT_DESCRIPTOR_SET_ADD_DESCRIPTOR_STATUS_MEMORY_ERROR	Out of memory.

Precondition

component_descriptor_set is not NULL.

component_class is not NULL.

params is a map value (bt_value_is_map() returns BT_TRUE) or is NULL.

Postcondition

On success, component_class is frozen.

On success, params is frozen.

bt_component_descriptor_set_get_ref()

void bt_component_descriptor_set_get_ref ( const bt_component_descriptor_set * component_descriptor_set )

extern

Increments the reference count of the component descriptor set component_descriptor_set.

Parameters

[in]

component_descriptor_set

Component descriptor set of which to increment the reference count. Can be NULL.

See also

bt_component_descriptor_set_put_ref() — Decrements the reference count of a component descriptor set.

bt_component_descriptor_set_put_ref()

void bt_component_descriptor_set_put_ref ( const bt_component_descriptor_set * component_descriptor_set )

extern

Decrements the reference count of the component descriptor set component_descriptor_set.

Parameters

[in]

component_descriptor_set

Component descriptor set of which to decrement the reference count. Can be NULL.

See also

bt_component_descriptor_set_get_ref() — Increments the reference count of a component descriptor set.