1 #ifndef BABELTRACE2_GRAPH_COMPONENT_DESCRIPTOR_SET_H
2 #define BABELTRACE2_GRAPH_COMPONENT_DESCRIPTOR_SET_H
5 * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
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:
14 * The above copyright notice and this permission notice shall be included in
15 * all copies or substantial portions of the Software.
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
26 #ifndef __BT_IN_BABELTRACE_H
27 # error "Please include <babeltrace2/babeltrace.h> instead."
30 #include <babeltrace2/types.h>
31 #include <babeltrace2/logging.h>
38 @defgroup api-comp-descr-set Component descriptor set
42 Set of descriptors of prospective \bt_p_comp to use with
43 bt_get_greatest_operative_mip_version().
45 A <strong><em>component descriptor set</em></strong>
46 is an \em unordered set of component descriptors.
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:
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.
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.
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>
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.
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().
78 Create an empty component descriptor set with
79 bt_component_descriptor_set_create().
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().
92 @typedef struct bt_component_descriptor_set bt_component_descriptor_set;
95 Component descriptor set.
108 Creates an empty component descriptor set.
111 New component descriptor set reference, or \c NULL on memory error.
113 extern bt_component_descriptor_set
*bt_component_descriptor_set_create(void);
117 Status codes for bt_component_descriptor_set_add_descriptor()
119 bt_component_descriptor_set_add_descriptor_with_initialize_method_data().
121 typedef enum bt_component_descriptor_set_add_descriptor_status
{
126 BT_COMPONENT_DESCRIPTOR_SET_ADD_DESCRIPTOR_STATUS_OK
= __BT_FUNC_STATUS_OK
,
132 BT_COMPONENT_DESCRIPTOR_SET_ADD_DESCRIPTOR_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
133 } bt_component_descriptor_set_add_descriptor_status
;
138 @name Component descriptor adding
145 bt_component_descriptor_set_add_descriptor_with_initialize_method_data()
146 with the \bt_p{initialize_method_data} parameter set to \c NULL.
148 extern bt_component_descriptor_set_add_descriptor_status
149 bt_component_descriptor_set_add_descriptor(
150 bt_component_descriptor_set
*component_descriptor_set
,
151 const bt_component_class
*component_class
,
152 const bt_value
*params
);
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}.
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
169 Parameters which would be passed to the initialization method of
170 the described component as the \bt_p{params} parameter.
172 Can be \c NULL, in which case it is equivalent to passing an empty
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}
180 @retval #BT_COMPONENT_DESCRIPTOR_SET_ADD_DESCRIPTOR_STATUS_OK
182 @retval #BT_COMPONENT_DESCRIPTOR_SET_ADD_DESCRIPTOR_STATUS_MEMORY_ERROR
185 @bt_pre_not_null{component_descriptor_set}
186 @bt_pre_not_null{component_class}
188 \bt_p{params} is a \bt_map_val (bt_value_is_map() returns #BT_TRUE)
191 @bt_post_success_frozen{component_class}
192 @bt_post_success_frozen{params}
194 extern bt_component_descriptor_set_add_descriptor_status
195 bt_component_descriptor_set_add_descriptor_with_initialize_method_data(
196 bt_component_descriptor_set
*component_descriptor_set
,
197 const bt_component_class
*component_class
,
198 const bt_value
*params
, void *initialize_method_data
);
203 @name Reference count
209 Increments the \ref api-fund-shared-object "reference count" of
210 the component descriptor set \bt_p{component_descriptor_set}.
212 @param[in] component_descriptor_set
214 Component descriptor set of which to increment the reference count.
219 @sa bt_component_descriptor_set_put_ref() —
220 Decrements the reference count of a component descriptor set.
222 extern void bt_component_descriptor_set_get_ref(
223 const bt_component_descriptor_set
*component_descriptor_set
);
227 Decrements the \ref api-fund-shared-object "reference count" of
228 the component descriptor set \bt_p{component_descriptor_set}.
230 @param[in] component_descriptor_set
232 Component descriptor set of which to decrement the reference count.
237 @sa bt_component_descriptor_set_get_ref() —
238 Increments the reference count of a component descriptor set.
240 extern void bt_component_descriptor_set_put_ref(
241 const bt_component_descriptor_set
*component_descriptor_set
);
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.
249 @param _component_descriptor_set
251 Component descriptor set of which to decrement the reference count.
256 @bt_pre_assign_expr{_component_descriptor_set}
258 #define BT_COMPONENT_DESCRIPTOR_SET_PUT_REF_AND_RESET(_component_descriptor_set) \
260 bt_component_descriptor_set_put_ref(_component_descriptor_set); \
261 (_component_descriptor_set) = NULL; \
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.
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.
276 Destination expression.
287 @bt_pre_assign_expr{_dst}
288 @bt_pre_assign_expr{_src}
290 #define BT_COMPONENT_DESCRIPTOR_SET_MOVE_REF(_dst, _src) \
292 bt_component_descriptor_set_put_ref(_dst); \
305 #endif /* BABELTRACE2_GRAPH_COMPONENT_DESCRIPTOR_SET_H */