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  * Component type.
  40  */
  41 enum bt_component_type {
  42         BT_COMPONENT_TYPE_UNKNOWN =     -1,
  43
  44         /** A source component is a notification generator. */
  45         BT_COMPONENT_TYPE_SOURCE =      0,
  46
  47         /** A sink component handles incoming notifications. */
  48         BT_COMPONENT_TYPE_SINK =        1,
  49
  50         /** A filter component implements both Source and Sink interfaces. */
  51         BT_COMPONENT_TYPE_FILTER =      2,
  52 };
  53
  54 /**
  55  * Status code. Errors are always negative.
  56  */
  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,
  62         /**
  63          * Component can't process a notification at this time
  64          * (e.g. would block), try again later.
  65          */
  66         BT_COMPONENT_STATUS_AGAIN =             2,
  67         /** General error. */
  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,
  75 };
  76
  77 struct bt_component_class;
  78 struct bt_component;
  79 struct bt_value;
  80
  81 /**
  82  * Component private data deallocation function type.
  83  *
  84  * @param component     Component instance
  85  */
  86 typedef void (*bt_component_destroy_cb)(struct bt_component *component);
  87
  88 /**
  89  * Component initialization function type.
  90  *
  91  * A component's private data and required callbacks must be set by this
  92  * function.
  93  *
  94  * @param component     Component instance
  95  * @param params        A dictionary of component parameters
  96  * @returns             One of #bt_component_status values
  97  */
  98 typedef enum bt_component_status (*bt_component_init_cb)(
  99                 struct bt_component *component, struct bt_value *params);
 100
 101
 102 /**
 103  * Get a component's private data.
 104  *
 105  * @param component     Component of which to get the private data
 106  * @returns             Component's private data
 107  */
 108 extern void *bt_component_get_private_data(struct bt_component *component);
 109
 110 /**
 111  * Set a component's private data.
 112  *
 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
 116  */
 117 extern enum bt_component_status bt_component_set_private_data(
 118                 struct bt_component *component, void *data);
 119
 120 /**
 121  * Set a component's private data cleanup function.
 122  *
 123  * @param component     Component of which to set the private data destruction
 124  *                      function
 125  * @param data          Component private data clean-up function
 126  * @returns             One of #bt_component_status values
 127  */
 128 extern enum bt_component_status bt_component_set_destroy_cb(
 129                 struct bt_component *component,
 130                 bt_component_destroy_cb destroy);
 131
 132 /** bt_component_souce */
 133 /**
 134  * Iterator initialization function type.
 135  *
 136  * A notification iterator's private data, deinitialization, next, and get
 137  * callbacks must be set by this function.
 138  *
 139  * @param source        Source component instance
 140  * @param iterator      Notification iterator instance
 141  */
 142 typedef enum bt_component_status (*bt_component_source_init_iterator_cb)(
 143                 struct bt_component *, struct bt_notification_iterator *);
 144
 145 /**
 146  * Set a source component's iterator initialization function.
 147  *
 148  * @param source        Source component instance
 149  * @param init_iterator Notification iterator initialization callback
 150  */
 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);
 154
 155 /** bt_component_sink */
 156 /**
 157  * Notification consumption function type.
 158  *
 159  * @param sink          Sink component instance
 160  * @returns             One of #bt_component_status values
 161  */
 162 typedef enum bt_component_status (*bt_component_sink_consume_cb)(
 163                 struct bt_component *);
 164
 165 /**
 166  * Iterator addition function type.
 167  *
 168  * A sink component may choose to refuse the addition of an iterator
 169  * by not returning BT_COMPONENT_STATUS_OK.
 170  *
 171  * @param sink          Sink component instance
 172  * @returns             One of #bt_component_status values
 173  */
 174 typedef enum bt_component_status (*bt_component_sink_add_iterator_cb)(
 175                 struct bt_component *, struct bt_notification_iterator *);
 176
 177 /**
 178  * Set a sink component's consumption callback.
 179  *
 180  * @param sink          Sink component instance
 181  * @param consume       Consumption callback
 182  * @returns             One of #bt_component_status values
 183  */
 184 extern enum bt_component_status
 185 bt_component_sink_set_consume_cb(struct bt_component *sink,
 186                 bt_component_sink_consume_cb consume);
 187
 188 /**
 189  * Set a sink component's iterator addition callback.
 190  *
 191  * @param sink          Sink component instance
 192  * @param add_iterator  Iterator addition callback
 193  * @returns             One of #bt_component_status values
 194  */
 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);
 198
 199 /* Defaults to 1. */
 200 extern enum bt_component_status
 201 bt_component_sink_set_minimum_input_count(struct bt_component *sink,
 202                 unsigned int minimum);
 203
 204 /* Defaults to 1. */
 205 extern enum bt_component_status
 206 bt_component_sink_set_maximum_input_count(struct bt_component *sink,
 207                 unsigned int maximum);
 208
 209 extern enum bt_component_status
 210 bt_component_sink_get_input_count(struct bt_component *sink,
 211                 unsigned int *count);
 212
 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);
 217
 218 /** bt_component_filter */
 219 /**
 220  * Iterator initialization function type.
 221  *
 222  * A notification iterator's private data, deinitialization, next, and get
 223  * callbacks must be set by this function.
 224  *
 225  * @param filter        Filter component instance
 226  * @param iterator      Notification iterator instance
 227  */
 228 typedef enum bt_component_status (*bt_component_filter_init_iterator_cb)(
 229                 struct bt_component *, struct bt_notification_iterator *);
 230
 231 /**
 232  * Iterator addition function type.
 233  *
 234  * A filter component may choose to refuse the addition of an iterator
 235  * by not returning BT_COMPONENT_STATUS_OK.
 236  *
 237  * @param filter        Filter component instance
 238  * @returns             One of #bt_component_status values
 239  */
 240 typedef enum bt_component_status (*bt_component_filter_add_iterator_cb)(
 241                 struct bt_component *, struct bt_notification_iterator *);
 242
 243 /**
 244  * Set a filter component's iterator initialization function.
 245  *
 246  * @param filter        Filter component instance
 247  * @param init_iterator Notification iterator initialization callback
 248  */
 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);
 252
 253 /**
 254  * Set a filter component's iterator addition callback.
 255  *
 256  * @param filter        Filter component instance
 257  * @param add_iterator  Iterator addition callback
 258  * @returns             One of #bt_component_status values
 259  */
 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);
 263
 264 /* Defaults to 1. */
 265 extern enum bt_component_status
 266 bt_component_filter_set_minimum_input_count(struct bt_component *filter,
 267                 unsigned int minimum);
 268
 269 /* Defaults to 1. */
 270 extern enum bt_component_status
 271 bt_component_filter_set_maximum_input_count(struct bt_component *filter,
 272                 unsigned int maximum);
 273
 274 extern enum bt_component_status
 275 bt_component_filter_get_input_count(struct bt_component *filter,
 276                 unsigned int *count);
 277
 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);
 282
 283 /**
 284  * Create an instance of a component from a component class.
 285  *
 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
 290  */
 291 extern struct bt_component *bt_component_create(
 292                 struct bt_component_class *component_class, const char *name,
 293                 struct bt_value *params);
 294
 295 /**
 296  * Get component's name.
 297  *
 298  * @param component     Component instance of which to get the name
 299  * @returns             Returns a pointer to the component's name
 300  */
 301 extern const char *bt_component_get_name(struct bt_component *component);
 302
 303 /**
 304  * Set component's name.
 305  *
 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
 309  */
 310 extern enum bt_component_status bt_component_set_name(
 311                 struct bt_component *component, const char *name);
 312
 313 /**
 314  * Get component's class.
 315  *
 316  * @param component     Component instance of which to get the class
 317  * @returns             The component's class
 318  */
 319 extern struct bt_component_class *bt_component_get_class(
 320                 struct bt_component *component);
 321
 322 #ifdef __cplusplus
 323 }
 324 #endif
 325
 326 #endif /* BABELTRACE_COMPONENT_COMPONENT_H */