include/babeltrace/component/component.h

   1 #ifndef BABELTRACE_COMPONENT_COMPONENT_H
   2 #define BABELTRACE_COMPONENT_COMPONENT_H
   3
   4 /*
   5  * BabelTrace - Babeltrace Component Interface
   6  *
   7  * Copyright 2015 Jérémie Galarneau <jeremie.galarneau@efficios.com>
   8  *
   9  * Author: Jérémie Galarneau <jeremie.galarneau@efficios.com>
  10  *
  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:
  17  *
  18  * The above copyright notice and this permission notice shall be included in
  19  * all copies or substantial portions of the Software.
  20  *
  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
  27  * SOFTWARE.
  28  */
  29
  30 #include <babeltrace/component/notification/iterator.h>
  31 #include <babeltrace/values.h>
  32 #include <stdio.h>
  33
  34 #ifdef __cplusplus
  35 extern "C" {
  36 #endif
  37
  38 /**
  39  * Status code. Errors are always negative.
  40  */
  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,
  46         /**
  47          * Component can't process a notification at this time
  48          * (e.g. would block), try again later.
  49          */
  50         BT_COMPONENT_STATUS_AGAIN =             2,
  51         /** General error. */
  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,
  59 };
  60
  61 struct bt_component_class;
  62 struct bt_component;
  63 struct bt_value;
  64
  65 /**
  66  * Component private data deallocation function type.
  67  *
  68  * @param component     Component instance
  69  */
  70 typedef void (*bt_component_destroy_cb)(struct bt_component *component);
  71
  72 /**
  73  * Component initialization function type.
  74  *
  75  * A component's private data and required callbacks must be set by this
  76  * function.
  77  *
  78  * @param component     Component instance
  79  * @param params        A dictionary of component parameters
  80  * @returns             One of #bt_component_status values
  81  */
  82 typedef enum bt_component_status (*bt_component_init_cb)(
  83                 struct bt_component *component, struct bt_value *params);
  84
  85
  86 /**
  87  * Get a component's private data.
  88  *
  89  * @param component     Component of which to get the private data
  90  * @returns             Component's private data
  91  */
  92 extern void *bt_component_get_private_data(struct bt_component *component);
  93
  94 /**
  95  * Set a component's private data.
  96  *
  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
 100  */
 101 extern enum bt_component_status bt_component_set_private_data(
 102                 struct bt_component *component, void *data);
 103
 104 /**
 105  * Set a component's private data cleanup function.
 106  *
 107  * @param component     Component of which to set the private data destruction
 108  *                      function
 109  * @param data          Component private data clean-up function
 110  * @returns             One of #bt_component_status values
 111  */
 112 extern enum bt_component_status bt_component_set_destroy_cb(
 113                 struct bt_component *component,
 114                 bt_component_destroy_cb destroy);
 115
 116 /** bt_component_souce */
 117 /**
 118  * Iterator initialization function type.
 119  *
 120  * A notification iterator's private data, deinitialization, next, and get
 121  * callbacks must be set by this function.
 122  *
 123  * @param source        Source component instance
 124  * @param iterator      Notification iterator instance
 125  */
 126 typedef enum bt_component_status (*bt_component_source_init_iterator_cb)(
 127                 struct bt_component *, struct bt_notification_iterator *);
 128
 129 /**
 130  * Set a source component's iterator initialization function.
 131  *
 132  * @param source        Source component instance
 133  * @param init_iterator Notification iterator initialization callback
 134  */
 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);
 138
 139 /** bt_component_sink */
 140 /**
 141  * Notification consumption function type.
 142  *
 143  * @param sink          Sink component instance
 144  * @returns             One of #bt_component_status values
 145  */
 146 typedef enum bt_component_status (*bt_component_sink_consume_cb)(
 147                 struct bt_component *);
 148
 149 /**
 150  * Iterator addition function type.
 151  *
 152  * A sink component may choose to refuse the addition of an iterator
 153  * by not returning BT_COMPONENT_STATUS_OK.
 154  *
 155  * @param sink          Sink component instance
 156  * @returns             One of #bt_component_status values
 157  */
 158 typedef enum bt_component_status (*bt_component_sink_add_iterator_cb)(
 159                 struct bt_component *, struct bt_notification_iterator *);
 160
 161 /**
 162  * Set a sink component's consumption callback.
 163  *
 164  * @param sink          Sink component instance
 165  * @param consume       Consumption callback
 166  * @returns             One of #bt_component_status values
 167  */
 168 extern enum bt_component_status
 169 bt_component_sink_set_consume_cb(struct bt_component *sink,
 170                 bt_component_sink_consume_cb consume);
 171
 172 /**
 173  * Set a sink component's iterator addition callback.
 174  *
 175  * @param sink          Sink component instance
 176  * @param add_iterator  Iterator addition callback
 177  * @returns             One of #bt_component_status values
 178  */
 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);
 182
 183 /* Defaults to 1. */
 184 extern enum bt_component_status
 185 bt_component_sink_set_minimum_input_count(struct bt_component *sink,
 186                 unsigned int minimum);
 187
 188 /* Defaults to 1. */
 189 extern enum bt_component_status
 190 bt_component_sink_set_maximum_input_count(struct bt_component *sink,
 191                 unsigned int maximum);
 192
 193 extern enum bt_component_status
 194 bt_component_sink_get_input_count(struct bt_component *sink,
 195                 unsigned int *count);
 196
 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);
 201
 202 /** bt_component_filter */
 203 /**
 204  * Iterator initialization function type.
 205  *
 206  * A notification iterator's private data, deinitialization, next, and get
 207  * callbacks must be set by this function.
 208  *
 209  * @param filter        Filter component instance
 210  * @param iterator      Notification iterator instance
 211  */
 212 typedef enum bt_component_status (*bt_component_filter_init_iterator_cb)(
 213                 struct bt_component *, struct bt_notification_iterator *);
 214
 215 /**
 216  * Iterator addition function type.
 217  *
 218  * A filter component may choose to refuse the addition of an iterator
 219  * by not returning BT_COMPONENT_STATUS_OK.
 220  *
 221  * @param filter        Filter component instance
 222  * @returns             One of #bt_component_status values
 223  */
 224 typedef enum bt_component_status (*bt_component_filter_add_iterator_cb)(
 225                 struct bt_component *, struct bt_notification_iterator *);
 226
 227 /**
 228  * Set a filter component's iterator initialization function.
 229  *
 230  * @param filter        Filter component instance
 231  * @param init_iterator Notification iterator initialization callback
 232  */
 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);
 236
 237 /**
 238  * Set a filter component's iterator addition callback.
 239  *
 240  * @param filter        Filter component instance
 241  * @param add_iterator  Iterator addition callback
 242  * @returns             One of #bt_component_status values
 243  */
 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);
 247
 248 /* Defaults to 1. */
 249 extern enum bt_component_status
 250 bt_component_filter_set_minimum_input_count(struct bt_component *filter,
 251                 unsigned int minimum);
 252
 253 /* Defaults to 1. */
 254 extern enum bt_component_status
 255 bt_component_filter_set_maximum_input_count(struct bt_component *filter,
 256                 unsigned int maximum);
 257
 258 extern enum bt_component_status
 259 bt_component_filter_get_input_count(struct bt_component *filter,
 260                 unsigned int *count);
 261
 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);
 266
 267 /**
 268  * Create an instance of a component from a component class.
 269  *
 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
 274  */
 275 extern struct bt_component *bt_component_create(
 276                 struct bt_component_class *component_class, const char *name,
 277                 struct bt_value *params);
 278
 279 /**
 280  * Get component's name.
 281  *
 282  * @param component     Component instance of which to get the name
 283  * @returns             Returns a pointer to the component's name
 284  */
 285 extern const char *bt_component_get_name(struct bt_component *component);
 286
 287 /**
 288  * Set component's name.
 289  *
 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
 293  */
 294 extern enum bt_component_status bt_component_set_name(
 295                 struct bt_component *component, const char *name);
 296
 297 /**
 298  * Get component's class.
 299  *
 300  * @param component     Component instance of which to get the class
 301  * @returns             The component's class
 302  */
 303 extern struct bt_component_class *bt_component_get_class(
 304                 struct bt_component *component);
 305
 306 #ifdef __cplusplus
 307 }
 308 #endif
 309
 310 #endif /* BABELTRACE_COMPONENT_COMPONENT_H */