Document libbabeltrace2's C API
[babeltrace.git] / include / babeltrace2 / graph / component-descriptor-set.h
CommitLineData
36e611bb
PP
1#ifndef BABELTRACE2_GRAPH_COMPONENT_DESCRIPTOR_SET_H
2#define BABELTRACE2_GRAPH_COMPONENT_DESCRIPTOR_SET_H
3
4/*
5 * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
6 *
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:
13 *
14 * The above copyright notice and this permission notice shall be included in
15 * all copies or substantial portions of the Software.
16 *
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
23 * SOFTWARE.
24 */
25
26#ifndef __BT_IN_BABELTRACE_H
27# error "Please include <babeltrace2/babeltrace.h> instead."
28#endif
29
30#include <babeltrace2/types.h>
31#include <babeltrace2/logging.h>
32
33#ifdef __cplusplus
34extern "C" {
35#endif
36
7704a0af
PP
37/*!
38@defgroup api-comp-descr-set Component descriptor set
39@ingroup api-graph
40
41@brief
42 Set of descriptors of prospective \bt_p_comp to use with
43 bt_get_greatest_operative_mip_version().
44
45A <strong><em>component descriptor set</em></strong>
46is an \em unordered set of component descriptors.
47
48A <strong><em>component descriptor</em></strong> describes a
49prospective \bt_comp, that is, everything that is needed to
50\ref api-graph-lc-add "instantiate a component class" within a
51trace processing \bt_graph without actually doing it:
52
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.
56
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.
60
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>
64 functions.
65
66As of \bt_name_version_min_maj, the only use case of a component
67descriptor set is bt_get_greatest_operative_mip_version(). This
68function computes the greatest \bt_mip version which
69you can use to create a trace processing graph to which you intend
70to \ref api-graph-lc-add "add components" described by a set of
71component descriptors.
72
73A component descriptor set is a
74\ref api-fund-shared-object "shared object": get a new reference with
75bt_component_descriptor_set_get_ref() and put an existing reference with
76bt_component_descriptor_set_put_ref().
77
78Create an empty component descriptor set with
79bt_component_descriptor_set_create().
80
81Add a component descriptor to a component descriptor set with
82bt_component_descriptor_set_add_descriptor() and
83bt_component_descriptor_set_add_descriptor_with_initialize_method_data().
84*/
85
86/*! @{ */
87
88/*!
89@name Type
90@{
91
92@typedef struct bt_component_descriptor_set bt_component_descriptor_set;
93
94@brief
95 Component descriptor set.
96
97@}
98*/
99
100/*!
101@name Creation
102@{
103*/
104
105
106/*!
107@brief
108 Creates an empty component descriptor set.
109
110@returns
111 New component descriptor set reference, or \c NULL on memory error.
112*/
36e611bb
PP
113extern bt_component_descriptor_set *bt_component_descriptor_set_create(void);
114
7704a0af
PP
115/*!
116@brief
117 Status codes for bt_component_descriptor_set_add_descriptor()
118 and
119 bt_component_descriptor_set_add_descriptor_with_initialize_method_data().
120*/
36e611bb 121typedef enum bt_component_descriptor_set_add_descriptor_status {
7704a0af
PP
122 /*!
123 @brief
124 Success.
125 */
36e611bb 126 BT_COMPONENT_DESCRIPTOR_SET_ADD_DESCRIPTOR_STATUS_OK = __BT_FUNC_STATUS_OK,
7704a0af
PP
127
128 /*!
129 @brief
130 Out of memory.
131 */
36e611bb
PP
132 BT_COMPONENT_DESCRIPTOR_SET_ADD_DESCRIPTOR_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
133} bt_component_descriptor_set_add_descriptor_status;
134
7704a0af
PP
135/*! @} */
136
137/*!
138@name Component descriptor adding
139@{
140*/
141
142/*!
143@brief
144 Alias of
145 bt_component_descriptor_set_add_descriptor_with_initialize_method_data()
146 with the \bt_p{initialize_method_data} parameter set to \c NULL.
147*/
36e611bb
PP
148extern bt_component_descriptor_set_add_descriptor_status
149bt_component_descriptor_set_add_descriptor(
7704a0af 150 bt_component_descriptor_set *component_descriptor_set,
36e611bb
PP
151 const bt_component_class *component_class,
152 const bt_value *params);
153
7704a0af
PP
154/*!
155@brief
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}.
161
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
166 described component.
167@param[in] params
168 @parblock
169 Parameters which would be passed to the initialization method of
170 the described component as the \bt_p{params} parameter.
171
172 Can be \c NULL, in which case it is equivalent to passing an empty
173 \bt_map_val.
174 @endparblock
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}
178 parameter.
179
180@retval #BT_COMPONENT_DESCRIPTOR_SET_ADD_DESCRIPTOR_STATUS_OK
181 Success.
182@retval #BT_COMPONENT_DESCRIPTOR_SET_ADD_DESCRIPTOR_STATUS_MEMORY_ERROR
183 Out of memory.
184
185@bt_pre_not_null{component_descriptor_set}
186@bt_pre_not_null{component_class}
187@pre
188 \bt_p{params} is a \bt_map_val (bt_value_is_map() returns #BT_TRUE)
189 or is \c NULL.
190
191@bt_post_success_frozen{component_class}
192@bt_post_success_frozen{params}
193*/
36e611bb 194extern bt_component_descriptor_set_add_descriptor_status
4175c1d5 195bt_component_descriptor_set_add_descriptor_with_initialize_method_data(
7704a0af 196 bt_component_descriptor_set *component_descriptor_set,
36e611bb 197 const bt_component_class *component_class,
7704a0af
PP
198 const bt_value *params, void *initialize_method_data);
199
200/*! @} */
201
202/*!
203@name Reference count
204@{
205*/
206
207/*!
208@brief
209 Increments the \ref api-fund-shared-object "reference count" of
210 the component descriptor set \bt_p{component_descriptor_set}.
211
212@param[in] component_descriptor_set
213 @parblock
214 Component descriptor set of which to increment the reference count.
215
216 Can be \c NULL.
217 @endparblock
218
219@sa bt_component_descriptor_set_put_ref() &mdash;
220 Decrements the reference count of a component descriptor set.
221*/
222extern void bt_component_descriptor_set_get_ref(
223 const bt_component_descriptor_set *component_descriptor_set);
224
225/*!
226@brief
227 Decrements the \ref api-fund-shared-object "reference count" of
228 the component descriptor set \bt_p{component_descriptor_set}.
229
230@param[in] component_descriptor_set
231 @parblock
232 Component descriptor set of which to decrement the reference count.
233
234 Can be \c NULL.
235 @endparblock
236
237@sa bt_component_descriptor_set_get_ref() &mdash;
238 Increments the reference count of a component descriptor set.
239*/
240extern void bt_component_descriptor_set_put_ref(
241 const bt_component_descriptor_set *component_descriptor_set);
242
243/*!
244@brief
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.
248
249@param _component_descriptor_set
250 @parblock
251 Component descriptor set of which to decrement the reference count.
252
253 Can contain \c NULL.
254 @endparblock
255
256@bt_pre_assign_expr{_component_descriptor_set}
257*/
258#define BT_COMPONENT_DESCRIPTOR_SET_PUT_REF_AND_RESET(_component_descriptor_set) \
259 do { \
260 bt_component_descriptor_set_put_ref(_component_descriptor_set); \
261 (_component_descriptor_set) = NULL; \
262 } while (0)
263
264/*!
265@brief
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.
269
270This macro effectively moves a component descriptor set reference from
271the expression \bt_p{_src} to the expression \bt_p{_dst}, putting the
272existing \bt_p{_dst} reference.
273
274@param _dst
275 @parblock
276 Destination expression.
277
278 Can contain \c NULL.
279 @endparblock
280@param _src
281 @parblock
282 Source expression.
283
284 Can contain \c NULL.
285 @endparblock
286
287@bt_pre_assign_expr{_dst}
288@bt_pre_assign_expr{_src}
289*/
290#define BT_COMPONENT_DESCRIPTOR_SET_MOVE_REF(_dst, _src) \
291 do { \
292 bt_component_descriptor_set_put_ref(_dst); \
293 (_dst) = (_src); \
294 (_src) = NULL; \
295 } while (0)
296
297/*! @} */
298
299/*! @} */
36e611bb
PP
300
301#ifdef __cplusplus
302}
303#endif
304
305#endif /* BABELTRACE2_GRAPH_COMPONENT_DESCRIPTOR_SET_H */
This page took 0.044785 seconds and 4 git commands to generate.