include/babeltrace/plugin/plugin-system.h

   1 #ifndef BABELTRACE_PLUGIN_SYSTEM_H
   2 #define BABELTRACE_PLUGIN_SYSTEM_H
   3
   4 /*
   5  * BabelTrace - Babeltrace Plug-in System Interface
   6  *
   7  * This interface is provided for plug-ins to use the Babeltrace
   8  * plug-in system facilities.
   9  *
  10  * Copyright 2015 Jérémie Galarneau <jeremie.galarneau@efficios.com>
  11  *
  12  * Author: Jérémie Galarneau <jeremie.galarneau@efficios.com>
  13  *
  14  * Permission is hereby granted, free of charge, to any person obtaining a copy
  15  * of this software and associated documentation files (the "Software"), to deal
  16  * in the Software without restriction, including without limitation the rights
  17  * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
  18  * copies of the Software, and to permit persons to whom the Software is
  19  * furnished to do so, subject to the following conditions:
  20  *
  21  * The above copyright notice and this permission notice shall be included in
  22  * all copies or substantial portions of the Software.
  23  *
  24  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  25  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  26  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  27  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  28  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  29  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  30  * SOFTWARE.
  31  */
  32
  33 #include <babeltrace/plugin/notification/notification.h>
  34 #include <stdint.h>
  35
  36 #ifdef __cplusplus
  37 extern "C" {
  38 #endif
  39
  40 struct bt_notification;
  41 struct bt_notification_iterator;
  42 struct bt_component;
  43 struct bt_component_factory;
  44 struct bt_value;
  45
  46 typedef enum bt_component_status (*bt_plugin_register_func)(
  47                 struct bt_component_factory *factory);
  48
  49 /**
  50  * Component private data deallocation function type.
  51  *
  52  * @param component     Component instance
  53  */
  54 typedef void (*bt_component_destroy_cb)(struct bt_component *component);
  55
  56 /**
  57  * Component initialization function type.
  58  *
  59  * A component's private data and required callbacks must be set by this
  60  * function.
  61  *
  62  * @param component     Component instance
  63  * @param params        A dictionary of component parameters
  64  * @returns             One of #bt_component_status values
  65  */
  66 typedef enum bt_component_status (*bt_component_init_cb)(
  67                 struct bt_component *component, struct bt_value *params);
  68
  69 /**
  70  * Get a component's private data.
  71  *
  72  * @param component     Component of which to get the private data
  73  * @returns             Component's private data
  74  */
  75 extern void *bt_component_get_private_data(struct bt_component *component);
  76
  77 /**
  78  * Set a component's private data.
  79  *
  80  * @param component     Component of which to set the private data
  81  * @param data          Component private data
  82  * @returns             One of #bt_component_status values
  83  */
  84 extern enum bt_component_status bt_component_set_private_data(
  85                 struct bt_component *component, void *data);
  86
  87 /**
  88  * Set a component's private data cleanup function.
  89  *
  90  * @param component     Component of which to set the private data destruction
  91  *                      function
  92  * @param data          Component private data clean-up function
  93  * @returns             One of #bt_component_status values
  94  */
  95 extern enum bt_component_status bt_component_set_destroy_cb(
  96                 struct bt_component *component,
  97                 bt_component_destroy_cb destroy);
  98
  99 /** bt_component_souce */
 100 /**
 101  * Iterator initialization function type.
 102  *
 103  * A notification iterator's private data, deinitialization, next, and get
 104  * callbacks must be set by this function.
 105  *
 106  * @param source        Source component instance
 107  * @param iterator      Notification iterator instance
 108  */
 109 typedef enum bt_component_status (*bt_component_source_init_iterator_cb)(
 110                 struct bt_component *, struct bt_notification_iterator *);
 111
 112 /**
 113  * Set a source component's iterator initialization function.
 114  *
 115  * @param source        Source component instance
 116  * @param init_iterator Notification iterator initialization callback
 117  */
 118 extern enum bt_component_status
 119 bt_component_source_set_iterator_init_cb(struct bt_component *source,
 120                 bt_component_source_init_iterator_cb init_iterator);
 121
 122 /** bt_component_sink */
 123 /**
 124  * Notification consumption function type.
 125  *
 126  * @param sink          Sink component instance
 127  * @returns             One of #bt_component_status values
 128  */
 129 typedef enum bt_component_status (*bt_component_sink_consume_cb)(
 130                 struct bt_component *);
 131
 132 /**
 133  * Iterator addition function type.
 134  *
 135  * A sink component may choose to refuse the addition of an iterator
 136  * by not returning BT_COMPONENT_STATUS_OK.
 137  *
 138  * @param sink          Sink component instance
 139  * @returns             One of #bt_component_status values
 140  */
 141 typedef enum bt_component_status (*bt_component_sink_add_iterator_cb)(
 142                 struct bt_component *, struct bt_notification_iterator *);
 143
 144 /**
 145  * Set a sink component's consumption callback.
 146  *
 147  * @param sink          Sink component instance
 148  * @param consume       Consumption callback
 149  * @returns             One of #bt_component_status values
 150  */
 151 extern enum bt_component_status
 152 bt_component_sink_set_consume_cb(struct bt_component *sink,
 153                 bt_component_sink_consume_cb consume);
 154
 155 /**
 156  * Set a sink component's iterator addition callback.
 157  *
 158  * @param sink          Sink component instance
 159  * @param add_iterator  Iterator addition callback
 160  * @returns             One of #bt_component_status values
 161  */
 162 extern enum bt_component_status
 163 bt_component_sink_set_add_iterator_cb(struct bt_component *sink,
 164                 bt_component_sink_add_iterator_cb add_iterator);
 165
 166 /* Defaults to 1. */
 167 extern enum bt_component_status
 168 bt_component_sink_set_minimum_input_count(struct bt_component *sink,
 169                 unsigned int minimum);
 170
 171 /* Defaults to 1. */
 172 extern enum bt_component_status
 173 bt_component_sink_set_maximum_input_count(struct bt_component *sink,
 174                 unsigned int maximum);
 175
 176 extern enum bt_component_status
 177 bt_component_sink_get_input_count(struct bt_component *sink,
 178                 unsigned int *count);
 179
 180 /* May return NULL after an interator has reached its end. */
 181 extern enum bt_component_status
 182 bt_component_sink_get_input_iterator(struct bt_component *sink,
 183                 unsigned int input, struct bt_notification_iterator **iterator);
 184
 185 /** bt_component_filter */
 186 /**
 187  * Iterator initialization function type.
 188  *
 189  * A notification iterator's private data, deinitialization, next, and get
 190  * callbacks must be set by this function.
 191  *
 192  * @param filter        Filter component instance
 193  * @param iterator      Notification iterator instance
 194  */
 195 typedef enum bt_component_status (*bt_component_filter_init_iterator_cb)(
 196                 struct bt_component *, struct bt_notification_iterator *);
 197
 198 /**
 199  * Iterator addition function type.
 200  *
 201  * A filter component may choose to refuse the addition of an iterator
 202  * by not returning BT_COMPONENT_STATUS_OK.
 203  *
 204  * @param filter        Filter component instance
 205  * @returns             One of #bt_component_status values
 206  */
 207 typedef enum bt_component_status (*bt_component_filter_add_iterator_cb)(
 208                 struct bt_component *, struct bt_notification_iterator *);
 209
 210 /**
 211  * Set a filter component's iterator initialization function.
 212  *
 213  * @param filter        Filter component instance
 214  * @param init_iterator Notification iterator initialization callback
 215  */
 216 extern enum bt_component_status
 217 bt_component_filter_set_iterator_init_cb(struct bt_component *filter,
 218                 bt_component_filter_init_iterator_cb init_iterator);
 219
 220 /**
 221  * Set a filter component's iterator addition callback.
 222  *
 223  * @param filter        Filter component instance
 224  * @param add_iterator  Iterator addition callback
 225  * @returns             One of #bt_component_status values
 226  */
 227 extern enum bt_component_status
 228 bt_component_filter_set_add_iterator_cb(struct bt_component *filter,
 229                 bt_component_filter_add_iterator_cb add_iterator);
 230
 231 /* Defaults to 1. */
 232 extern enum bt_component_status
 233 bt_component_filter_set_minimum_input_count(struct bt_component *filter,
 234                 unsigned int minimum);
 235
 236 /* Defaults to 1. */
 237 extern enum bt_component_status
 238 bt_component_filter_set_maximum_input_count(struct bt_component *filter,
 239                 unsigned int maximum);
 240
 241 extern enum bt_component_status
 242 bt_component_filter_get_input_count(struct bt_component *filter,
 243                 unsigned int *count);
 244
 245 /* May return NULL after an interator has reached its end. */
 246 extern enum bt_component_status
 247 bt_component_filter_get_input_iterator(struct bt_component *filter,
 248                 unsigned int input, struct bt_notification_iterator **iterator);
 249
 250 /** bt_notification_iterator */
 251 /**
 252  * Function returning an iterator's current notification.
 253  *
 254  * @param iterator      Notification iterator instance
 255  * @returns             A notification instance
 256  */
 257 typedef struct bt_notification *(*bt_notification_iterator_get_cb)(
 258                 struct bt_notification_iterator *iterator);
 259
 260 /**
 261  * Function advancing an iterator's position of one element.
 262  *
 263  * @param iterator      Notification iterator instance
 264  * @returns             One of #bt_notification_iterator_status values
 265  */
 266 typedef enum bt_notification_iterator_status (*bt_notification_iterator_next_cb)(
 267                 struct bt_notification_iterator *iterator);
 268
 269 /**
 270  * Function advancing an iterator's position to a given time (relative to Epoch).
 271  *
 272  * @param iterator      Notification iterator instance
 273  * @param time          Time at which to seek, expressed in ns since Epoch
 274  * @returns             One of #bt_notification_iterator_status values
 275  */
 276 typedef enum bt_notification_iterator_status
 277                 (*bt_notification_iterator_seek_time_cb)(
 278                 struct bt_notification_iterator *iterator, int64_t time);
 279
 280 /**
 281  * Function cleaning-up an iterator's private data on destruction.
 282  *
 283  * @param iterator      Notification iterator instance
 284  */
 285 typedef void (*bt_notification_iterator_destroy_cb)(
 286                 struct bt_notification_iterator *iterator);
 287
 288 /**
 289  * Set an iterator's "get" callback which return the current notification.
 290  *
 291  * @param iterator      Notification iterator instance
 292  * @param get           Notification return callback
 293  * @returns             One of #bt_notification_iterator_status values
 294  */
 295 extern enum bt_notification_iterator_status
 296 bt_notification_iterator_set_get_cb(struct bt_notification_iterator *iterator,
 297                 bt_notification_iterator_get_cb get);
 298
 299 /**
 300  * Set an iterator's "next" callback which advances the iterator's position.
 301  *
 302  * @param iterator      Notification iterator instance
 303  * @param next          Iterator "next" callback
 304  * @returns             One of #bt_notification_iterator_status values
 305  */
 306 extern enum bt_notification_iterator_status
 307 bt_notification_iterator_set_next_cb(struct bt_notification_iterator *iterator,
 308                 bt_notification_iterator_next_cb next);
 309
 310 /**
 311  * Set an iterator's "seek_time" callback which sets the iterator's position to
 312  *      provided time (in ns since Epoch).
 313  *
 314  * @param iterator      Notification iterator instance
 315  * @param seek_timetime Iterator "seek_time" callback
 316  * @returns             One of #bt_notification_iterator_status values
 317  */
 318 extern enum bt_notification_iterator_status
 319 bt_notification_iterator_set_seek_time_cb(struct bt_notification_iterator *iterator,
 320                 bt_notification_iterator_seek_time_cb seek_time);
 321
 322 /**
 323  * Set an iterator's "destroy" callback.
 324  *
 325  * @param iterator      Notification iterator instance
 326  * @param next          Iterator destruction callback
 327  * @returns             One of #bt_notification_iterator_status values
 328  */
 329 extern enum bt_notification_iterator_status
 330 bt_notification_iterator_set_destroy_cb(
 331                 struct bt_notification_iterator *iterator,
 332                 bt_notification_iterator_destroy_cb destroy);
 333
 334 /**
 335  * Set an iterator's private data.
 336  *
 337  * @param iterator      Notification iterator instance
 338  * @param data          Iterator private data
 339  * @returns             One of #bt_notification_iterator_status values
 340  */
 341 extern enum bt_notification_iterator_status
 342 bt_notification_iterator_set_private_data(
 343                 struct bt_notification_iterator *iterator, void *data);
 344
 345 /**
 346  * Get an iterator's private data.
 347  *
 348  * @param iterator      Notification iterator instance
 349  * @returns             Iterator instance private data
 350  */
 351 extern void *bt_notification_iterator_get_private_data(
 352                 struct bt_notification_iterator *iterator);
 353
 354 #ifdef __cplusplus
 355 }
 356 #endif
 357
 358 #endif /* BABELTRACE_PLUGIN_SYSTEM_H */