include/babeltrace2: add `noexcept` specifier for C++ ≥ 11
[babeltrace.git] / include / babeltrace2 / graph / component-descriptor-set.h
CommitLineData
55f09f52 1/*
0235b0db 2 * SPDX-License-Identifier: MIT
55f09f52 3 *
0235b0db 4 * Copyright (C) 2010-2019 EfficiOS Inc. and Linux Foundation
55f09f52
PP
5 */
6
0235b0db
MJ
7#ifndef BABELTRACE2_GRAPH_COMPONENT_DESCRIPTOR_SET_H
8#define BABELTRACE2_GRAPH_COMPONENT_DESCRIPTOR_SET_H
9
f38da6ca
SM
10/* IWYU pragma: private, include <babeltrace2/babeltrace.h> */
11
55f09f52
PP
12#ifndef __BT_IN_BABELTRACE_H
13# error "Please include <babeltrace2/babeltrace.h> instead."
14#endif
15
16#include <babeltrace2/types.h>
17#include <babeltrace2/logging.h>
18
19#ifdef __cplusplus
20extern "C" {
21#endif
22
43c59509
PP
23/*!
24@defgroup api-comp-descr-set Component descriptor set
25@ingroup api-graph
26
27@brief
28 Set of descriptors of prospective \bt_p_comp to use with
29 bt_get_greatest_operative_mip_version().
30
31A <strong><em>component descriptor set</em></strong>
32is an \em unordered set of component descriptors.
33
34A <strong><em>component descriptor</em></strong> describes a
35prospective \bt_comp, that is, everything that is needed to
36\ref api-graph-lc-add "instantiate a component class" within a
37trace processing \bt_graph without actually doing it:
38
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.
42
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.
46
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>
50 functions.
51
52As of \bt_name_version_min_maj, the only use case of a component
53descriptor set is bt_get_greatest_operative_mip_version(). This
54function computes the greatest \bt_mip version which
55you can use to create a trace processing graph to which you intend
56to \ref api-graph-lc-add "add components" described by a set of
57component descriptors.
58
59A component descriptor set is a
60\ref api-fund-shared-object "shared object": get a new reference with
61bt_component_descriptor_set_get_ref() and put an existing reference with
62bt_component_descriptor_set_put_ref().
63
64Create an empty component descriptor set with
65bt_component_descriptor_set_create().
66
67Add a component descriptor to a component descriptor set with
68bt_component_descriptor_set_add_descriptor() and
69bt_component_descriptor_set_add_descriptor_with_initialize_method_data().
70*/
71
72/*! @{ */
73
74/*!
75@name Type
76@{
77
78@typedef struct bt_component_descriptor_set bt_component_descriptor_set;
79
80@brief
81 Component descriptor set.
82
83@}
84*/
85
86/*!
87@name Creation
88@{
89*/
90
43c59509
PP
91/*!
92@brief
93 Creates an empty component descriptor set.
94
95@returns
96 New component descriptor set reference, or \c NULL on memory error.
97*/
4c81a2b7
PP
98extern bt_component_descriptor_set *bt_component_descriptor_set_create(void)
99 __BT_NOEXCEPT;
55f09f52 100
43c59509
PP
101/*!
102@brief
103 Status codes for bt_component_descriptor_set_add_descriptor()
104 and
105 bt_component_descriptor_set_add_descriptor_with_initialize_method_data().
106*/
55f09f52 107typedef enum bt_component_descriptor_set_add_descriptor_status {
43c59509
PP
108 /*!
109 @brief
110 Success.
111 */
55f09f52 112 BT_COMPONENT_DESCRIPTOR_SET_ADD_DESCRIPTOR_STATUS_OK = __BT_FUNC_STATUS_OK,
43c59509
PP
113
114 /*!
115 @brief
116 Out of memory.
117 */
55f09f52
PP
118 BT_COMPONENT_DESCRIPTOR_SET_ADD_DESCRIPTOR_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
119} bt_component_descriptor_set_add_descriptor_status;
120
43c59509
PP
121/*! @} */
122
123/*!
124@name Component descriptor adding
125@{
126*/
127
128/*!
129@brief
130 Alias of
131 bt_component_descriptor_set_add_descriptor_with_initialize_method_data()
132 with the \bt_p{initialize_method_data} parameter set to \c NULL.
133*/
55f09f52
PP
134extern bt_component_descriptor_set_add_descriptor_status
135bt_component_descriptor_set_add_descriptor(
43c59509 136 bt_component_descriptor_set *component_descriptor_set,
55f09f52 137 const bt_component_class *component_class,
4c81a2b7 138 const bt_value *params) __BT_NOEXCEPT;
55f09f52 139
43c59509
PP
140/*!
141@brief
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}.
147
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
152 described component.
153@param[in] params
154 @parblock
155 Parameters which would be passed to the initialization method of
156 the described component as the \bt_p{params} parameter.
157
158 Can be \c NULL, in which case it is equivalent to passing an empty
159 \bt_map_val.
160 @endparblock
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}
164 parameter.
165
166@retval #BT_COMPONENT_DESCRIPTOR_SET_ADD_DESCRIPTOR_STATUS_OK
167 Success.
168@retval #BT_COMPONENT_DESCRIPTOR_SET_ADD_DESCRIPTOR_STATUS_MEMORY_ERROR
169 Out of memory.
170
171@bt_pre_not_null{component_descriptor_set}
172@bt_pre_not_null{component_class}
173@pre
174 \bt_p{params} is a \bt_map_val (bt_value_is_map() returns #BT_TRUE)
175 or is \c NULL.
176
177@bt_post_success_frozen{component_class}
178@bt_post_success_frozen{params}
179*/
55f09f52 180extern bt_component_descriptor_set_add_descriptor_status
21a9f056 181bt_component_descriptor_set_add_descriptor_with_initialize_method_data(
43c59509 182 bt_component_descriptor_set *component_descriptor_set,
55f09f52 183 const bt_component_class *component_class,
4c81a2b7
PP
184 const bt_value *params,
185 void *initialize_method_data) __BT_NOEXCEPT;
43c59509
PP
186
187/*! @} */
188
189/*!
190@name Reference count
191@{
192*/
193
194/*!
195@brief
196 Increments the \ref api-fund-shared-object "reference count" of
197 the component descriptor set \bt_p{component_descriptor_set}.
198
199@param[in] component_descriptor_set
200 @parblock
201 Component descriptor set of which to increment the reference count.
202
203 Can be \c NULL.
204 @endparblock
205
206@sa bt_component_descriptor_set_put_ref() &mdash;
207 Decrements the reference count of a component descriptor set.
208*/
209extern void bt_component_descriptor_set_get_ref(
4c81a2b7
PP
210 const bt_component_descriptor_set *component_descriptor_set)
211 __BT_NOEXCEPT;
43c59509
PP
212
213/*!
214@brief
215 Decrements the \ref api-fund-shared-object "reference count" of
216 the component descriptor set \bt_p{component_descriptor_set}.
217
218@param[in] component_descriptor_set
219 @parblock
220 Component descriptor set of which to decrement the reference count.
221
222 Can be \c NULL.
223 @endparblock
224
225@sa bt_component_descriptor_set_get_ref() &mdash;
226 Increments the reference count of a component descriptor set.
227*/
228extern void bt_component_descriptor_set_put_ref(
4c81a2b7
PP
229 const bt_component_descriptor_set *component_descriptor_set)
230 __BT_NOEXCEPT;
43c59509
PP
231
232/*!
233@brief
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.
237
238@param _component_descriptor_set
239 @parblock
240 Component descriptor set of which to decrement the reference count.
241
242 Can contain \c NULL.
243 @endparblock
244
245@bt_pre_assign_expr{_component_descriptor_set}
246*/
247#define BT_COMPONENT_DESCRIPTOR_SET_PUT_REF_AND_RESET(_component_descriptor_set) \
248 do { \
249 bt_component_descriptor_set_put_ref(_component_descriptor_set); \
250 (_component_descriptor_set) = NULL; \
251 } while (0)
252
253/*!
254@brief
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.
258
259This macro effectively moves a component descriptor set reference from
260the expression \bt_p{_src} to the expression \bt_p{_dst}, putting the
261existing \bt_p{_dst} reference.
262
263@param _dst
264 @parblock
265 Destination expression.
266
267 Can contain \c NULL.
268 @endparblock
269@param _src
270 @parblock
271 Source expression.
272
273 Can contain \c NULL.
274 @endparblock
275
276@bt_pre_assign_expr{_dst}
277@bt_pre_assign_expr{_src}
278*/
279#define BT_COMPONENT_DESCRIPTOR_SET_MOVE_REF(_dst, _src) \
280 do { \
281 bt_component_descriptor_set_put_ref(_dst); \
282 (_dst) = (_src); \
283 (_src) = NULL; \
284 } while (0)
285
286/*! @} */
287
288/*! @} */
55f09f52
PP
289
290#ifdef __cplusplus
291}
292#endif
293
294#endif /* BABELTRACE2_GRAPH_COMPONENT_DESCRIPTOR_SET_H */
This page took 0.061787 seconds and 4 git commands to generate.