X-Git-Url: http://git.efficios.com/?p=babeltrace.git;a=blobdiff_plain;f=include%2Fbabeltrace2%2Fgraph%2Fcomponent-descriptor-set.h;h=b90572099f20eea7ff85c10f23dda809d9c80636;hp=e551a70b7ae01d1844829fcf69f546495ffd805f;hb=43c59509042845f8d42c3e99ec74d45fa2dc0908;hpb=1cda4ff4025e4b3f7bd2a861baa51d2113c4cbf9 diff --git a/include/babeltrace2/graph/component-descriptor-set.h b/include/babeltrace2/graph/component-descriptor-set.h index e551a70b..b9057209 100644 --- a/include/babeltrace2/graph/component-descriptor-set.h +++ b/include/babeltrace2/graph/component-descriptor-set.h @@ -34,24 +34,269 @@ 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 component descriptor set +is an \em unordered set of component descriptors. + +A component descriptor 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 component class to instantiate, which you would + pass as the \bt_p{component_class} parameter of one of the + bt_graph_add_*_component*() functions. + +- The initialization parameters, which you + would pass as the \bt_p{params} parameter of one of the + bt_graph_add_*_component*() functions. + +- The initialization method data, which you would pass + as the \bt_p{initialize_method_data} parameter of one of the + bt_graph_add_*_component_with_initialize_method_data() + 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 *comp_descriptor_set, + 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 *comp_descriptor_set, + bt_component_descriptor_set *component_descriptor_set, const bt_component_class *component_class, - const bt_value *params, void *init_method_data); + 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() — + 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() — + 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 }