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>
39 * Status code. Errors are always negative.
41 enum bt_component_status
{
42 /** No error, okay. */
43 BT_COMPONENT_STATUS_OK
= 0,
44 /** No more work to be done by this component. **/
45 BT_COMPONENT_STATUS_END
= 1,
47 * Component can't process a notification at this time
48 * (e.g. would block), try again later.
50 BT_COMPONENT_STATUS_AGAIN
= 2,
52 BT_COMPONENT_STATUS_ERROR
= -1,
53 /** Unsupported component feature. */
54 BT_COMPONENT_STATUS_UNSUPPORTED
= -2,
55 /** Invalid arguments. */
56 BT_COMPONENT_STATUS_INVALID
= -3,
57 /** Memory allocation failure. */
58 BT_COMPONENT_STATUS_NOMEM
= -4,
61 struct bt_component_class
;
66 * Component private data deallocation function type.
68 * @param component Component instance
70 typedef void (*bt_component_destroy_cb
)(struct bt_component
*component
);
73 * Component initialization function type.
75 * A component's private data and required callbacks must be set by this
78 * @param component Component instance
79 * @param params A dictionary of component parameters
80 * @returns One of #bt_component_status values
82 typedef enum bt_component_status (*bt_component_init_cb
)(
83 struct bt_component
*component
, struct bt_value
*params
);
87 * Get a component's private data.
89 * @param component Component of which to get the private data
90 * @returns Component's private data
92 extern void *bt_component_get_private_data(struct bt_component
*component
);
95 * Set a component's private data.
97 * @param component Component of which to set the private data
98 * @param data Component private data
99 * @returns One of #bt_component_status values
101 extern enum bt_component_status
bt_component_set_private_data(
102 struct bt_component
*component
, void *data
);
105 * Set a component's private data cleanup function.
107 * @param component Component of which to set the private data destruction
109 * @param data Component private data clean-up function
110 * @returns One of #bt_component_status values
112 extern enum bt_component_status
bt_component_set_destroy_cb(
113 struct bt_component
*component
,
114 bt_component_destroy_cb destroy
);
116 /** bt_component_souce */
118 * Iterator initialization function type.
120 * A notification iterator's private data, deinitialization, next, and get
121 * callbacks must be set by this function.
123 * @param source Source component instance
124 * @param iterator Notification iterator instance
126 typedef enum bt_component_status (*bt_component_source_init_iterator_cb
)(
127 struct bt_component
*, struct bt_notification_iterator
*);
130 * Set a source component's iterator initialization function.
132 * @param source Source component instance
133 * @param init_iterator Notification iterator initialization callback
135 extern enum bt_component_status
136 bt_component_source_set_iterator_init_cb(struct bt_component
*source
,
137 bt_component_source_init_iterator_cb init_iterator
);
139 /** bt_component_sink */
141 * Notification consumption function type.
143 * @param sink Sink component instance
144 * @returns One of #bt_component_status values
146 typedef enum bt_component_status (*bt_component_sink_consume_cb
)(
147 struct bt_component
*);
150 * Iterator addition function type.
152 * A sink component may choose to refuse the addition of an iterator
153 * by not returning BT_COMPONENT_STATUS_OK.
155 * @param sink Sink component instance
156 * @returns One of #bt_component_status values
158 typedef enum bt_component_status (*bt_component_sink_add_iterator_cb
)(
159 struct bt_component
*, struct bt_notification_iterator
*);
162 * Set a sink component's consumption callback.
164 * @param sink Sink component instance
165 * @param consume Consumption callback
166 * @returns One of #bt_component_status values
168 extern enum bt_component_status
169 bt_component_sink_set_consume_cb(struct bt_component
*sink
,
170 bt_component_sink_consume_cb consume
);
173 * Set a sink component's iterator addition callback.
175 * @param sink Sink component instance
176 * @param add_iterator Iterator addition callback
177 * @returns One of #bt_component_status values
179 extern enum bt_component_status
180 bt_component_sink_set_add_iterator_cb(struct bt_component
*sink
,
181 bt_component_sink_add_iterator_cb add_iterator
);
184 extern enum bt_component_status
185 bt_component_sink_set_minimum_input_count(struct bt_component
*sink
,
186 unsigned int minimum
);
189 extern enum bt_component_status
190 bt_component_sink_set_maximum_input_count(struct bt_component
*sink
,
191 unsigned int maximum
);
193 extern enum bt_component_status
194 bt_component_sink_get_input_count(struct bt_component
*sink
,
195 unsigned int *count
);
197 /* May return NULL after an interator has reached its end. */
198 extern enum bt_component_status
199 bt_component_sink_get_input_iterator(struct bt_component
*sink
,
200 unsigned int input
, struct bt_notification_iterator
**iterator
);
202 /** bt_component_filter */
204 * Iterator initialization function type.
206 * A notification iterator's private data, deinitialization, next, and get
207 * callbacks must be set by this function.
209 * @param filter Filter component instance
210 * @param iterator Notification iterator instance
212 typedef enum bt_component_status (*bt_component_filter_init_iterator_cb
)(
213 struct bt_component
*, struct bt_notification_iterator
*);
216 * Iterator addition function type.
218 * A filter component may choose to refuse the addition of an iterator
219 * by not returning BT_COMPONENT_STATUS_OK.
221 * @param filter Filter component instance
222 * @returns One of #bt_component_status values
224 typedef enum bt_component_status (*bt_component_filter_add_iterator_cb
)(
225 struct bt_component
*, struct bt_notification_iterator
*);
228 * Set a filter component's iterator initialization function.
230 * @param filter Filter component instance
231 * @param init_iterator Notification iterator initialization callback
233 extern enum bt_component_status
234 bt_component_filter_set_iterator_init_cb(struct bt_component
*filter
,
235 bt_component_filter_init_iterator_cb init_iterator
);
238 * Set a filter component's iterator addition callback.
240 * @param filter Filter component instance
241 * @param add_iterator Iterator addition callback
242 * @returns One of #bt_component_status values
244 extern enum bt_component_status
245 bt_component_filter_set_add_iterator_cb(struct bt_component
*filter
,
246 bt_component_filter_add_iterator_cb add_iterator
);
249 extern enum bt_component_status
250 bt_component_filter_set_minimum_input_count(struct bt_component
*filter
,
251 unsigned int minimum
);
254 extern enum bt_component_status
255 bt_component_filter_set_maximum_input_count(struct bt_component
*filter
,
256 unsigned int maximum
);
258 extern enum bt_component_status
259 bt_component_filter_get_input_count(struct bt_component
*filter
,
260 unsigned int *count
);
262 /* May return NULL after an interator has reached its end. */
263 extern enum bt_component_status
264 bt_component_filter_get_input_iterator(struct bt_component
*filter
,
265 unsigned int input
, struct bt_notification_iterator
**iterator
);
268 * Create an instance of a component from a component class.
270 * @param component_class Component class of which to create an instance
271 * @param name Name of the new component instance, optional
272 * @param params A dictionary of component parameters
273 * @returns Returns a pointer to a new component instance
275 extern struct bt_component
*bt_component_create(
276 struct bt_component_class
*component_class
, const char *name
,
277 struct bt_value
*params
);
280 * Get component's name.
282 * @param component Component instance of which to get the name
283 * @returns Returns a pointer to the component's name
285 extern const char *bt_component_get_name(struct bt_component
*component
);
288 * Set component's name.
290 * @param component Component instance of which to set the name
291 * @param name New component name (will be copied)
292 * @returns One of #bt_component_status values
294 extern enum bt_component_status
bt_component_set_name(
295 struct bt_component
*component
, const char *name
);
298 * Get component's class.
300 * @param component Component instance of which to get the class
301 * @returns The component's class
303 extern struct bt_component_class
*bt_component_get_class(
304 struct bt_component
*component
);
310 #endif /* BABELTRACE_COMPONENT_COMPONENT_H */