Commit | Line | Data |
---|---|---|
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 | |
34 | extern "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 | ||
45 | A <strong><em>component descriptor set</em></strong> | |
46 | is an \em unordered set of component descriptors. | |
47 | ||
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: | |
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 | ||
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. | |
72 | ||
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(). | |
77 | ||
78 | Create an empty component descriptor set with | |
79 | bt_component_descriptor_set_create(). | |
80 | ||
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(). | |
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 |
113 | extern 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 | 121 | typedef 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 |
148 | extern bt_component_descriptor_set_add_descriptor_status |
149 | bt_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 | 194 | extern bt_component_descriptor_set_add_descriptor_status |
4175c1d5 | 195 | bt_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() — | |
220 | Decrements the reference count of a component descriptor set. | |
221 | */ | |
222 | extern 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() — | |
238 | Increments the reference count of a component descriptor set. | |
239 | */ | |
240 | extern 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 | ||
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. | |
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 */ |