1 #ifndef BABELTRACE_COMPONENT_COMPONENT_H
2 #define BABELTRACE_COMPONENT_COMPONENT_H
5 * BabelTrace - Babeltrace Component Interface
7 * Copyright 2015 Jérémie Galarneau <jeremie.galarneau@efficios.com>
9 * Author: Jérémie Galarneau <jeremie.galarneau@efficios.com>
11 * Permission is hereby granted, free of charge, to any person obtaining a copy
12 * of this software and associated documentation files (the "Software"), to deal
13 * in the Software without restriction, including without limitation the rights
14 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
15 * copies of the Software, and to permit persons to whom the Software is
16 * furnished to do so, subject to the following conditions:
18 * The above copyright notice and this permission notice shall be included in
19 * all copies or substantial portions of the Software.
21 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
22 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
23 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
24 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
25 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
26 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
30 #include <babeltrace/component/notification/iterator.h>
31 #include <babeltrace/values.h>
41 enum bt_component_type
{
42 BT_COMPONENT_TYPE_UNKNOWN
= -1,
44 /** A source component is a notification generator. */
45 BT_COMPONENT_TYPE_SOURCE
= 0,
47 /** A sink component handles incoming notifications. */
48 BT_COMPONENT_TYPE_SINK
= 1,
50 /** A filter component implements both Source and Sink interfaces. */
51 BT_COMPONENT_TYPE_FILTER
= 2,
55 * Status code. Errors are always negative.
57 enum bt_component_status
{
58 /** No error, okay. */
59 BT_COMPONENT_STATUS_OK
= 0,
60 /** No more work to be done by this component. **/
61 BT_COMPONENT_STATUS_END
= 1,
63 * Component can't process a notification at this time
64 * (e.g. would block), try again later.
66 BT_COMPONENT_STATUS_AGAIN
= 2,
68 BT_COMPONENT_STATUS_ERROR
= -1,
69 /** Unsupported component feature. */
70 BT_COMPONENT_STATUS_UNSUPPORTED
= -2,
71 /** Invalid arguments. */
72 BT_COMPONENT_STATUS_INVALID
= -3,
73 /** Memory allocation failure. */
74 BT_COMPONENT_STATUS_NOMEM
= -4,
77 struct bt_component_class
;
82 * Component private data deallocation function type.
84 * @param component Component instance
86 typedef void (*bt_component_destroy_cb
)(struct bt_component
*component
);
89 * Component initialization function type.
91 * A component's private data and required callbacks must be set by this
94 * @param component Component instance
95 * @param params A dictionary of component parameters
96 * @returns One of #bt_component_status values
98 typedef enum bt_component_status (*bt_component_init_cb
)(
99 struct bt_component
*component
, struct bt_value
*params
);
103 * Get a component's private data.
105 * @param component Component of which to get the private data
106 * @returns Component's private data
108 extern void *bt_component_get_private_data(struct bt_component
*component
);
111 * Set a component's private data.
113 * @param component Component of which to set the private data
114 * @param data Component private data
115 * @returns One of #bt_component_status values
117 extern enum bt_component_status
bt_component_set_private_data(
118 struct bt_component
*component
, void *data
);
121 * Set a component's private data cleanup function.
123 * @param component Component of which to set the private data destruction
125 * @param data Component private data clean-up function
126 * @returns One of #bt_component_status values
128 extern enum bt_component_status
bt_component_set_destroy_cb(
129 struct bt_component
*component
,
130 bt_component_destroy_cb destroy
);
132 /** bt_component_souce */
134 * Iterator initialization function type.
136 * A notification iterator's private data, deinitialization, next, and get
137 * callbacks must be set by this function.
139 * @param source Source component instance
140 * @param iterator Notification iterator instance
142 typedef enum bt_component_status (*bt_component_source_init_iterator_cb
)(
143 struct bt_component
*, struct bt_notification_iterator
*);
146 * Set a source component's iterator initialization function.
148 * @param source Source component instance
149 * @param init_iterator Notification iterator initialization callback
151 extern enum bt_component_status
152 bt_component_source_set_iterator_init_cb(struct bt_component
*source
,
153 bt_component_source_init_iterator_cb init_iterator
);
155 /** bt_component_sink */
157 * Notification consumption function type.
159 * @param sink Sink component instance
160 * @returns One of #bt_component_status values
162 typedef enum bt_component_status (*bt_component_sink_consume_cb
)(
163 struct bt_component
*);
166 * Iterator addition function type.
168 * A sink component may choose to refuse the addition of an iterator
169 * by not returning BT_COMPONENT_STATUS_OK.
171 * @param sink Sink component instance
172 * @returns One of #bt_component_status values
174 typedef enum bt_component_status (*bt_component_sink_add_iterator_cb
)(
175 struct bt_component
*, struct bt_notification_iterator
*);
178 * Set a sink component's consumption callback.
180 * @param sink Sink component instance
181 * @param consume Consumption callback
182 * @returns One of #bt_component_status values
184 extern enum bt_component_status
185 bt_component_sink_set_consume_cb(struct bt_component
*sink
,
186 bt_component_sink_consume_cb consume
);
189 * Set a sink component's iterator addition callback.
191 * @param sink Sink component instance
192 * @param add_iterator Iterator addition callback
193 * @returns One of #bt_component_status values
195 extern enum bt_component_status
196 bt_component_sink_set_add_iterator_cb(struct bt_component
*sink
,
197 bt_component_sink_add_iterator_cb add_iterator
);
200 extern enum bt_component_status
201 bt_component_sink_set_minimum_input_count(struct bt_component
*sink
,
202 unsigned int minimum
);
205 extern enum bt_component_status
206 bt_component_sink_set_maximum_input_count(struct bt_component
*sink
,
207 unsigned int maximum
);
209 extern enum bt_component_status
210 bt_component_sink_get_input_count(struct bt_component
*sink
,
211 unsigned int *count
);
213 /* May return NULL after an interator has reached its end. */
214 extern enum bt_component_status
215 bt_component_sink_get_input_iterator(struct bt_component
*sink
,
216 unsigned int input
, struct bt_notification_iterator
**iterator
);
218 /** bt_component_filter */
220 * Iterator initialization function type.
222 * A notification iterator's private data, deinitialization, next, and get
223 * callbacks must be set by this function.
225 * @param filter Filter component instance
226 * @param iterator Notification iterator instance
228 typedef enum bt_component_status (*bt_component_filter_init_iterator_cb
)(
229 struct bt_component
*, struct bt_notification_iterator
*);
232 * Iterator addition function type.
234 * A filter component may choose to refuse the addition of an iterator
235 * by not returning BT_COMPONENT_STATUS_OK.
237 * @param filter Filter component instance
238 * @returns One of #bt_component_status values
240 typedef enum bt_component_status (*bt_component_filter_add_iterator_cb
)(
241 struct bt_component
*, struct bt_notification_iterator
*);
244 * Set a filter component's iterator initialization function.
246 * @param filter Filter component instance
247 * @param init_iterator Notification iterator initialization callback
249 extern enum bt_component_status
250 bt_component_filter_set_iterator_init_cb(struct bt_component
*filter
,
251 bt_component_filter_init_iterator_cb init_iterator
);
254 * Set a filter component's iterator addition callback.
256 * @param filter Filter component instance
257 * @param add_iterator Iterator addition callback
258 * @returns One of #bt_component_status values
260 extern enum bt_component_status
261 bt_component_filter_set_add_iterator_cb(struct bt_component
*filter
,
262 bt_component_filter_add_iterator_cb add_iterator
);
265 extern enum bt_component_status
266 bt_component_filter_set_minimum_input_count(struct bt_component
*filter
,
267 unsigned int minimum
);
270 extern enum bt_component_status
271 bt_component_filter_set_maximum_input_count(struct bt_component
*filter
,
272 unsigned int maximum
);
274 extern enum bt_component_status
275 bt_component_filter_get_input_count(struct bt_component
*filter
,
276 unsigned int *count
);
278 /* May return NULL after an interator has reached its end. */
279 extern enum bt_component_status
280 bt_component_filter_get_input_iterator(struct bt_component
*filter
,
281 unsigned int input
, struct bt_notification_iterator
**iterator
);
284 * Create an instance of a component from a component class.
286 * @param component_class Component class of which to create an instance
287 * @param name Name of the new component instance, optional
288 * @param params A dictionary of component parameters
289 * @returns Returns a pointer to a new component instance
291 extern struct bt_component
*bt_component_create(
292 struct bt_component_class
*component_class
, const char *name
,
293 struct bt_value
*params
);
296 * Get component's name.
298 * @param component Component instance of which to get the name
299 * @returns Returns a pointer to the component's name
301 extern const char *bt_component_get_name(struct bt_component
*component
);
304 * Set component's name.
306 * @param component Component instance of which to set the name
307 * @param name New component name (will be copied)
308 * @returns One of #bt_component_status values
310 extern enum bt_component_status
bt_component_set_name(
311 struct bt_component
*component
, const char *name
);
314 * Get component's class.
316 * @param component Component instance of which to get the class
317 * @returns The component's class
319 extern struct bt_component_class
*bt_component_get_class(
320 struct bt_component
*component
);
326 #endif /* BABELTRACE_COMPONENT_COMPONENT_H */