2 * SPDX-License-Identifier: MIT
4 * Copyright (C) 2010-2019 EfficiOS Inc. and Linux Foundation
7 #ifndef BABELTRACE2_GRAPH_COMPONENT_DESCRIPTOR_SET_H
8 #define BABELTRACE2_GRAPH_COMPONENT_DESCRIPTOR_SET_H
10 #ifndef __BT_IN_BABELTRACE_H
11 # error "Please include <babeltrace2/babeltrace.h> instead."
14 #include <babeltrace2/types.h>
15 #include <babeltrace2/logging.h>
22 @defgroup api-comp-descr-set Component descriptor set
26 Set of descriptors of prospective \bt_p_comp to use with
27 bt_get_greatest_operative_mip_version().
29 A <strong><em>component descriptor set</em></strong>
30 is an \em unordered set of component descriptors.
32 A <strong><em>component descriptor</em></strong> describes a
33 prospective \bt_comp, that is, everything that is needed to
34 \ref api-graph-lc-add "instantiate a component class" within a
35 trace processing \bt_graph without actually doing it:
37 - The <strong>component class</strong> to instantiate, which you would
38 pass as the \bt_p{component_class} parameter of one of the
39 <code>bt_graph_add_*_component*()</code> functions.
41 - The <strong>initialization parameters</strong>, which you
42 would pass as the \bt_p{params} parameter of one of the
43 <code>bt_graph_add_*_component*()</code> functions.
45 - The <strong>initialization method data</strong>, which you would pass
46 as the \bt_p{initialize_method_data} parameter of one of the
47 <code>bt_graph_add_*_component_with_initialize_method_data()</code>
50 As of \bt_name_version_min_maj, the only use case of a component
51 descriptor set is bt_get_greatest_operative_mip_version(). This
52 function computes the greatest \bt_mip version which
53 you can use to create a trace processing graph to which you intend
54 to \ref api-graph-lc-add "add components" described by a set of
55 component descriptors.
57 A component descriptor set is a
58 \ref api-fund-shared-object "shared object": get a new reference with
59 bt_component_descriptor_set_get_ref() and put an existing reference with
60 bt_component_descriptor_set_put_ref().
62 Create an empty component descriptor set with
63 bt_component_descriptor_set_create().
65 Add a component descriptor to a component descriptor set with
66 bt_component_descriptor_set_add_descriptor() and
67 bt_component_descriptor_set_add_descriptor_with_initialize_method_data().
76 @typedef struct bt_component_descriptor_set bt_component_descriptor_set;
79 Component descriptor set.
91 Creates an empty component descriptor set.
94 New component descriptor set reference, or \c NULL on memory error.
96 extern bt_component_descriptor_set
*bt_component_descriptor_set_create(void);
100 Status codes for bt_component_descriptor_set_add_descriptor()
102 bt_component_descriptor_set_add_descriptor_with_initialize_method_data().
104 typedef enum bt_component_descriptor_set_add_descriptor_status
{
109 BT_COMPONENT_DESCRIPTOR_SET_ADD_DESCRIPTOR_STATUS_OK
= __BT_FUNC_STATUS_OK
,
115 BT_COMPONENT_DESCRIPTOR_SET_ADD_DESCRIPTOR_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
116 } bt_component_descriptor_set_add_descriptor_status
;
121 @name Component descriptor adding
128 bt_component_descriptor_set_add_descriptor_with_initialize_method_data()
129 with the \bt_p{initialize_method_data} parameter set to \c NULL.
131 extern bt_component_descriptor_set_add_descriptor_status
132 bt_component_descriptor_set_add_descriptor(
133 bt_component_descriptor_set
*component_descriptor_set
,
134 const bt_component_class
*component_class
,
135 const bt_value
*params
);
139 Adds a descriptor of a \bt_comp which would be an instance of the
140 \bt_comp_cls \bt_p{component_class}, would receive the parameters
141 \bt_p{params} and the method data \bt_p{initialize_method_data} at
142 initialization time, to the component descriptor set
143 \bt_p{component_descriptor_set}.
145 @param[in] component_descriptor_set
146 Component descriptor set to which to add a component descriptor.
147 @param[in] component_class
148 \bt_c_comp_cls which would be instantiated to create the
152 Parameters which would be passed to the initialization method of
153 the described component as the \bt_p{params} parameter.
155 Can be \c NULL, in which case it is equivalent to passing an empty
158 @param[in] initialize_method_data
159 User data which would be passed to the initialization method of
160 the described component as the \bt_p{initialize_method_data}
163 @retval #BT_COMPONENT_DESCRIPTOR_SET_ADD_DESCRIPTOR_STATUS_OK
165 @retval #BT_COMPONENT_DESCRIPTOR_SET_ADD_DESCRIPTOR_STATUS_MEMORY_ERROR
168 @bt_pre_not_null{component_descriptor_set}
169 @bt_pre_not_null{component_class}
171 \bt_p{params} is a \bt_map_val (bt_value_is_map() returns #BT_TRUE)
174 @bt_post_success_frozen{component_class}
175 @bt_post_success_frozen{params}
177 extern bt_component_descriptor_set_add_descriptor_status
178 bt_component_descriptor_set_add_descriptor_with_initialize_method_data(
179 bt_component_descriptor_set
*component_descriptor_set
,
180 const bt_component_class
*component_class
,
181 const bt_value
*params
, void *initialize_method_data
);
186 @name Reference count
192 Increments the \ref api-fund-shared-object "reference count" of
193 the component descriptor set \bt_p{component_descriptor_set}.
195 @param[in] component_descriptor_set
197 Component descriptor set of which to increment the reference count.
202 @sa bt_component_descriptor_set_put_ref() —
203 Decrements the reference count of a component descriptor set.
205 extern void bt_component_descriptor_set_get_ref(
206 const bt_component_descriptor_set
*component_descriptor_set
);
210 Decrements the \ref api-fund-shared-object "reference count" of
211 the component descriptor set \bt_p{component_descriptor_set}.
213 @param[in] component_descriptor_set
215 Component descriptor set of which to decrement the reference count.
220 @sa bt_component_descriptor_set_get_ref() —
221 Increments the reference count of a component descriptor set.
223 extern void bt_component_descriptor_set_put_ref(
224 const bt_component_descriptor_set
*component_descriptor_set
);
228 Decrements the reference count of the component descriptor set
229 \bt_p{_component_descriptor_set}, and then sets
230 \bt_p{_component_descriptor_set} to \c NULL.
232 @param _component_descriptor_set
234 Component descriptor set of which to decrement the reference count.
239 @bt_pre_assign_expr{_component_descriptor_set}
241 #define BT_COMPONENT_DESCRIPTOR_SET_PUT_REF_AND_RESET(_component_descriptor_set) \
243 bt_component_descriptor_set_put_ref(_component_descriptor_set); \
244 (_component_descriptor_set) = NULL; \
249 Decrements the reference count of the component descriptor set
250 \bt_p{_dst}, sets \bt_p{_dst} to \bt_p{_src}, and then sets
251 \bt_p{_src} to \c NULL.
253 This macro effectively moves a component descriptor set reference from
254 the expression \bt_p{_src} to the expression \bt_p{_dst}, putting the
255 existing \bt_p{_dst} reference.
259 Destination expression.
270 @bt_pre_assign_expr{_dst}
271 @bt_pre_assign_expr{_src}
273 #define BT_COMPONENT_DESCRIPTOR_SET_MOVE_REF(_dst, _src) \
275 bt_component_descriptor_set_put_ref(_dst); \
288 #endif /* BABELTRACE2_GRAPH_COMPONENT_DESCRIPTOR_SET_H */