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 /* IWYU pragma: private, include <babeltrace2/babeltrace.h> */
12 #ifndef __BT_IN_BABELTRACE_H
13 # error "Please include <babeltrace2/babeltrace.h> instead."
16 #include <babeltrace2/types.h>
17 #include <babeltrace2/logging.h>
24 @defgroup api-comp-descr-set Component descriptor set
28 Set of descriptors of prospective \bt_p_comp to use with
29 bt_get_greatest_operative_mip_version().
31 A <strong><em>component descriptor set</em></strong>
32 is an \em unordered set of component descriptors.
34 A <strong><em>component descriptor</em></strong> describes a
35 prospective \bt_comp, that is, everything that is needed to
36 \ref api-graph-lc-add "instantiate a component class" within a
37 trace processing \bt_graph without actually doing it:
39 - The <strong>component class</strong> to instantiate, which you would
40 pass as the \bt_p{component_class} parameter of one of the
41 <code>bt_graph_add_*_component*()</code> functions.
43 - The <strong>initialization parameters</strong>, which you
44 would pass as the \bt_p{params} parameter of one of the
45 <code>bt_graph_add_*_component*()</code> functions.
47 - The <strong>initialization method data</strong>, which you would pass
48 as the \bt_p{initialize_method_data} parameter of one of the
49 <code>bt_graph_add_*_component_with_initialize_method_data()</code>
52 As of \bt_name_version_min_maj, the only use case of a component
53 descriptor set is bt_get_greatest_operative_mip_version(). This
54 function computes the greatest \bt_mip version which
55 you can use to create a trace processing graph to which you intend
56 to \ref api-graph-lc-add "add components" described by a set of
57 component descriptors.
59 A component descriptor set is a
60 \ref api-fund-shared-object "shared object": get a new reference with
61 bt_component_descriptor_set_get_ref() and put an existing reference with
62 bt_component_descriptor_set_put_ref().
64 Create an empty component descriptor set with
65 bt_component_descriptor_set_create().
67 Add a component descriptor to a component descriptor set with
68 bt_component_descriptor_set_add_descriptor() and
69 bt_component_descriptor_set_add_descriptor_with_initialize_method_data().
78 @typedef struct bt_component_descriptor_set bt_component_descriptor_set;
81 Component descriptor set.
93 Creates an empty component descriptor set.
96 New component descriptor set reference, or \c NULL on memory error.
98 extern bt_component_descriptor_set
*bt_component_descriptor_set_create(void)
103 Status codes for bt_component_descriptor_set_add_descriptor()
105 bt_component_descriptor_set_add_descriptor_with_initialize_method_data().
107 typedef enum bt_component_descriptor_set_add_descriptor_status
{
112 BT_COMPONENT_DESCRIPTOR_SET_ADD_DESCRIPTOR_STATUS_OK
= __BT_FUNC_STATUS_OK
,
118 BT_COMPONENT_DESCRIPTOR_SET_ADD_DESCRIPTOR_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
119 } bt_component_descriptor_set_add_descriptor_status
;
124 @name Component descriptor adding
131 bt_component_descriptor_set_add_descriptor_with_initialize_method_data()
132 with the \bt_p{initialize_method_data} parameter set to \c NULL.
134 extern bt_component_descriptor_set_add_descriptor_status
135 bt_component_descriptor_set_add_descriptor(
136 bt_component_descriptor_set
*component_descriptor_set
,
137 const bt_component_class
*component_class
,
138 const bt_value
*params
) __BT_NOEXCEPT
;
142 Adds a descriptor of a \bt_comp which would be an instance of the
143 \bt_comp_cls \bt_p{component_class}, would receive the parameters
144 \bt_p{params} and the method data \bt_p{initialize_method_data} at
145 initialization time, to the component descriptor set
146 \bt_p{component_descriptor_set}.
148 @param[in] component_descriptor_set
149 Component descriptor set to which to add a component descriptor.
150 @param[in] component_class
151 \bt_c_comp_cls which would be instantiated to create the
155 Parameters which would be passed to the initialization method of
156 the described component as the \bt_p{params} parameter.
158 Can be \c NULL, in which case it is equivalent to passing an empty
161 @param[in] initialize_method_data
162 User data which would be passed to the initialization method of
163 the described component as the \bt_p{initialize_method_data}
166 @retval #BT_COMPONENT_DESCRIPTOR_SET_ADD_DESCRIPTOR_STATUS_OK
168 @retval #BT_COMPONENT_DESCRIPTOR_SET_ADD_DESCRIPTOR_STATUS_MEMORY_ERROR
171 @bt_pre_not_null{component_descriptor_set}
172 @bt_pre_not_null{component_class}
174 \bt_p{params} is a \bt_map_val (bt_value_is_map() returns #BT_TRUE)
177 @bt_post_success_frozen{component_class}
178 @bt_post_success_frozen{params}
180 extern bt_component_descriptor_set_add_descriptor_status
181 bt_component_descriptor_set_add_descriptor_with_initialize_method_data(
182 bt_component_descriptor_set
*component_descriptor_set
,
183 const bt_component_class
*component_class
,
184 const bt_value
*params
,
185 void *initialize_method_data
) __BT_NOEXCEPT
;
190 @name Reference count
196 Increments the \ref api-fund-shared-object "reference count" of
197 the component descriptor set \bt_p{component_descriptor_set}.
199 @param[in] component_descriptor_set
201 Component descriptor set of which to increment the reference count.
206 @sa bt_component_descriptor_set_put_ref() —
207 Decrements the reference count of a component descriptor set.
209 extern void bt_component_descriptor_set_get_ref(
210 const bt_component_descriptor_set
*component_descriptor_set
)
215 Decrements the \ref api-fund-shared-object "reference count" of
216 the component descriptor set \bt_p{component_descriptor_set}.
218 @param[in] component_descriptor_set
220 Component descriptor set of which to decrement the reference count.
225 @sa bt_component_descriptor_set_get_ref() —
226 Increments the reference count of a component descriptor set.
228 extern void bt_component_descriptor_set_put_ref(
229 const bt_component_descriptor_set
*component_descriptor_set
)
234 Decrements the reference count of the component descriptor set
235 \bt_p{_component_descriptor_set}, and then sets
236 \bt_p{_component_descriptor_set} to \c NULL.
238 @param _component_descriptor_set
240 Component descriptor set of which to decrement the reference count.
245 @bt_pre_assign_expr{_component_descriptor_set}
247 #define BT_COMPONENT_DESCRIPTOR_SET_PUT_REF_AND_RESET(_component_descriptor_set) \
249 bt_component_descriptor_set_put_ref(_component_descriptor_set); \
250 (_component_descriptor_set) = NULL; \
255 Decrements the reference count of the component descriptor set
256 \bt_p{_dst}, sets \bt_p{_dst} to \bt_p{_src}, and then sets
257 \bt_p{_src} to \c NULL.
259 This macro effectively moves a component descriptor set reference from
260 the expression \bt_p{_src} to the expression \bt_p{_dst}, putting the
261 existing \bt_p{_dst} reference.
265 Destination expression.
276 @bt_pre_assign_expr{_dst}
277 @bt_pre_assign_expr{_src}
279 #define BT_COMPONENT_DESCRIPTOR_SET_MOVE_REF(_dst, _src) \
281 bt_component_descriptor_set_put_ref(_dst); \
294 #endif /* BABELTRACE2_GRAPH_COMPONENT_DESCRIPTOR_SET_H */