src/include/core/plugin.h

   1 /*
   2  * SysDB - src/include/core/plugin.h
   3  * Copyright (C) 2012 Sebastian 'tokkee' Harl <sh@tokkee.org>
   4  * All rights reserved.
   5  *
   6  * Redistribution and use in source and binary forms, with or without
   7  * modification, are permitted provided that the following conditions
   8  * are met:
   9  * 1. Redistributions of source code must retain the above copyright
  10  *    notice, this list of conditions and the following disclaimer.
  11  * 2. Redistributions in binary form must reproduce the above copyright
  12  *    notice, this list of conditions and the following disclaimer in the
  13  *    documentation and/or other materials provided with the distribution.
  14  *
  15  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  16  * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  17  * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  18  * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR
  19  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
  20  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
  21  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
  22  * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
  23  * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
  24  * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
  25  * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  26  */
  27
  28 #ifndef SDB_CORE_PLUGIN_H
  29 #define SDB_CORE_PLUGIN_H 1
  30
  31 #include "sysdb.h"
  32 #include "core/object.h"
  33 #include "core/time.h"
  34 #include "core/timeseries.h"
  35
  36 #include "liboconfig/oconfig.h"
  37
  38 #include <stdarg.h>
  39
  40 #ifdef __cplusplus
  41 extern "C" {
  42 #endif
  43
  44 typedef struct {
  45         sdb_time_t interval;
  46 } sdb_plugin_ctx_t;
  47 #define SDB_PLUGIN_CTX_INIT { 0 }
  48
  49 typedef struct {
  50         char *plugin_name;
  51         char *filename;
  52
  53         /* public attributes */
  54         char *description;
  55         char *copyright;
  56         char *license;
  57
  58         int   version;
  59         int   plugin_version;
  60 } sdb_plugin_info_t;
  61 #define SDB_PLUGIN_INFO_INIT { \
  62         /* plugin_name */ NULL, /* filename */ NULL, /* desc */ NULL, \
  63         /* copyright */ NULL, /* license */ NULL, \
  64         /* version */ -1, /* plugin_version */ -1 }
  65
  66 /* this should be used in the header of a plugin to avoid
  67  * missing prototype warnings/errors for the plugin init
  68  * function */
  69 #define SDB_PLUGIN_MAGIC \
  70         int sdb_module_init(sdb_plugin_info_t *info)
  71
  72 typedef struct {
  73         _Bool do_loop;
  74         sdb_time_t default_interval;
  75 } sdb_plugin_loop_t;
  76 #define SDB_PLUGIN_LOOP_INIT { 1, 0 }
  77
  78 /*
  79  * sdb_plugin_load:
  80  * Load (any type of) plugin by loading the shared object file and calling the
  81  * sdb_module_init function. If specified, 'plugin_ctx' fine-tunes the
  82  * behavior of the plugin. If specified, the plugin will be looked up in
  83  * 'basedir', else it defaults to the package libdir.
  84  */
  85 int
  86 sdb_plugin_load(const char *basedir, const char *name,
  87                 const sdb_plugin_ctx_t *plugin_ctx);
  88
  89 /*
  90  * sdb_plugin_set_info:
  91  * Fill in the fields of the sdb_plugin_info_t object passed to the
  92  * sdb_module_init function. This information is used to identify the plugin
  93  * and also to provide additional information to the user.
  94  */
  95 enum {
  96         SDB_PLUGIN_INFO_DESC,          /* plugin description: string */
  97         SDB_PLUGIN_INFO_COPYRIGHT,     /* plugin copyright: string */
  98         SDB_PLUGIN_INFO_LICENSE,       /* plugin license: string */
  99         SDB_PLUGIN_INFO_VERSION,       /* libsysdb version: integer */
 100         SDB_PLUGIN_INFO_PLUGIN_VERSION /* plugin version: integer */
 101 };
 102
 103 int
 104 sdb_plugin_set_info(sdb_plugin_info_t *info, int type, ...);
 105
 106 /*
 107  * plugin callback functions:
 108  * See the description of the respective register function for what arguments
 109  * the callbacks expect.
 110  *
 111  * The specified name of callback functions is prepended with the plugin name
 112  * before being registered with the core.
 113  */
 114
 115 typedef int (*sdb_plugin_config_cb)(oconfig_item_t *ci);
 116 typedef int (*sdb_plugin_init_cb)(sdb_object_t *user_data);
 117 typedef int (*sdb_plugin_collector_cb)(sdb_object_t *user_data);
 118 typedef char *(*sdb_plugin_cname_cb)(const char *name,
 119                 sdb_object_t *user_data);
 120 typedef int (*sdb_plugin_shutdown_cb)(sdb_object_t *user_data);
 121 typedef int (*sdb_plugin_log_cb)(int prio, const char *msg,
 122                 sdb_object_t *user_data);
 123
 124 typedef sdb_timeseries_t *(*sdb_plugin_fetch_ts_cb)(const char *id,
 125                 sdb_timeseries_opts_t *opts, sdb_object_t *user_data);
 126
 127 /*
 128  * sdb_plugin_register_config:
 129  * Register a "config" function. This will be used to pass on the
 130  * configuration for a plugin. The plugin has to make sure that the function
 131  * can be called multiple times in order to process multiple <Plugin> blocks
 132  * specified in the configuration file(s).
 133  *
 134  * Returns:
 135  *  - 0 on success
 136  *  - a negative value else
 137  */
 138 int
 139 sdb_plugin_register_config(sdb_plugin_config_cb callback);
 140
 141 /*
 142  * sdb_plugin_register_init:
 143  * Register an "init" function. All "init" functions will be called after
 144  * finishing the config parsing and before starting any other work. The
 145  * functions will be called in the same order as they have been registered,
 146  * that is, functions of different plugins will be called in the same order as
 147  * the appropriate "Load" statements in the config file.
 148  *
 149  * If the "init" function returns a non-zero value, *all* callbacks of the
 150  * plugin will be unloaded.
 151  *
 152  * Arguments:
 153  *  - user_data: If specified, this will be passed on to each call of the
 154  *    callback. The function will take ownership of the object, that is,
 155  *    increment the reference count by one. In case the caller does not longer
 156  *    use the object for other purposes, it should thus deref it.
 157  *
 158  * Returns:
 159  *  - 0 on success
 160  *  - a negative value else
 161  */
 162 int
 163 sdb_plugin_register_init(const char *name, sdb_plugin_init_cb callback,
 164                 sdb_object_t *user_data);
 165
 166 /*
 167  * sdb_plugin_register_collector:
 168  * Register a "collector" function. This is where a backend is doing its main
 169  * work. This function will be called whenever an update of a backend has been
 170  * requested (either by regular interval or by user request). The backend
 171  * should then query the appropriate data-source and submit all values to the
 172  * core.
 173  *
 174  * Arguments:
 175  *  - interval: Specifies the regular interval at which to update the backend.
 176  *    If this is NULL, global settings will be used.
 177  *  - user_data: If specified, this will be passed on to each call of the
 178  *    callback. The function will take ownership of the object, that is,
 179  *    increment the reference count by one. In case the caller does not longer
 180  *    use the object for other purposes, it should thus deref it.
 181  *
 182  * Returns:
 183  *  - 0 on success
 184  *  - a negative value else
 185  */
 186 int
 187 sdb_plugin_register_collector(const char *name,
 188                 sdb_plugin_collector_cb callback,
 189                 const sdb_time_t *interval, sdb_object_t *user_data);
 190
 191 /*
 192  * sdb_plugin_register_cname:
 193  * Register a "cname" (canonicalize name) function. This type of function is
 194  * called whenever a host is stored. It accepts the hostname and returns a
 195  * canonicalized hostname which will then be used to actually store the host.
 196  * If multiple such callbacks are registered, each one of them will be called
 197  * in the order they have been registered, each one receiving the result of
 198  * the previous callback. If the function returns NULL, the original hostname
 199  * is not changed. Any other value has to be dynamically allocated. It will be
 200  * freed later on by the core.
 201  *
 202  * Returns:
 203  *  - 0 on success
 204  *  - a negative value else
 205  */
 206 int
 207 sdb_plugin_register_cname(const char *name, sdb_plugin_cname_cb callback,
 208                 sdb_object_t *user_data);
 209
 210 /*
 211  * sdb_plugin_register_shutdown:
 212  * Register a "shutdown" function to be called after stopping all update
 213  * processes and before shutting down the daemon.
 214  *
 215  * Arguments:
 216  *  - user_data: If specified, this will be passed on to each call of the
 217  *    callback. The function will take ownership of the object, that is,
 218  *    increment the reference count by one. In case the caller does not longer
 219  *    use the object for other purposes, it should thus deref it.
 220  */
 221 int
 222 sdb_plugin_register_shutdown(const char *name,
 223                 sdb_plugin_shutdown_cb callback,
 224                 sdb_object_t *user_data);
 225
 226 /*
 227  * sdb_plugin_register_log:
 228  * Register a "log" function to be called whenever logging is to be done.
 229  *
 230  * Arguments:
 231  *  - user_data: If specified, this will be passed on to each call of the
 232  *    callback. The function will take ownership of the object, that is,
 233  *    increment the reference count by one. In case the caller does not longer
 234  *    use the object for other purposes, it should thus deref it.
 235  */
 236 int
 237 sdb_plugin_register_log(const char *name, sdb_plugin_log_cb callback,
 238                 sdb_object_t *user_data);
 239
 240 /*
 241  * sdb_plugin_register_ts_fetcher:
 242  * Register a "time-series fetcher" function to be called whenever retrieving
 243  * a time-series from a data-store. The callback will receive an identifier
 244  * describing where to retrieve the data from (e.g. a filename or some kind of
 245  * URL) and options which further describe the query.
 246  *
 247  * The name is used literally (without prepending the plugin name) to look up
 248  * the appropriate fetcher callback.
 249  *
 250  * Arguments:
 251  *  - user_data: If specified, this will be passed on to each call of the
 252  *    callback. The function will take ownership of the object, that is,
 253  *    increment the reference count by one. In case the caller does not longer
 254  *    use the object for other purposes, it should thus deref it.
 255  */
 256 int
 257 sdb_plugin_register_ts_fetcher(const char *name,
 258                 sdb_plugin_fetch_ts_cb callback, sdb_object_t *user_data);
 259
 260 /*
 261  * sdb_plugin_get_ctx, sdb_plugin_set_ctx:
 262  * The plugin context defines a set of settings that are available whenever a
 263  * plugin has been called. It may be used to pass around various information
 264  * between the different component of the library without having each and
 265  * every plugin care about it.
 266  *
 267  * If non-NULL, sdb_plugin_set_ctx stores the previous context in the location
 268  * pointed to by 'old'.
 269  */
 270 sdb_plugin_ctx_t
 271 sdb_plugin_get_ctx(void);
 272 int
 273 sdb_plugin_set_ctx(sdb_plugin_ctx_t ctx, sdb_plugin_ctx_t *old);
 274
 275 /*
 276  * sdb_plugin_current:
 277  * Retrieve information about the plugin (if any) from which the current call
 278  * into the core originated. The return value may not be modified.
 279  *
 280  * Returns:
 281  *  - information about the current plugin if we were called from some
 282  *    plugin's callback function
 283  *  - NULL else
 284  */
 285 const sdb_plugin_info_t *
 286 sdb_plugin_current(void);
 287
 288 /*
 289  * sdb_plugin_configure:
 290  * Configure the plugin called 'name' using the config tree 'ci'. The plugin
 291  * name is the same as the one used when loading the plugin.
 292  *
 293  * Returns:
 294  *  - 0 on success
 295  *  - a negative value else
 296  */
 297 int
 298 sdb_plugin_configure(const char *name, oconfig_item_t *ci);
 299
 300 /*
 301  * sdb_plugin_reconfigure_init, sdb_plugin_reconfigure_finish:
 302  * Reconfigure all plugins. This happens in multiple steps: first, call
 303  * sdb_plugin_reconfigure_init to deconfigure all plugins by calling their
 304  * config callbacks with a NULL config tree and unregistering all callbacks.
 305  * Then, sdb_plugin_configure and other functions may be used to provide the
 306  * new configuration or load new plugins. For all plugins which were already
 307  * loaded before, sdb_module_init will be called with a NULL argument when
 308  * reloading them.
 309  * Finally, sdb_plugin_reconfigure_finish will clean up leftover pieces, like
 310  * unloading plugins which are no longer in use.
 311  *
 312  * Returns:
 313  *  - 0 on success
 314  *  - a negative value else
 315  */
 316 int
 317 sdb_plugin_reconfigure_init(void);
 318 int
 319 sdb_plugin_reconfigure_finish(void);
 320
 321 /*
 322  * sdb_plugin_init_all:
 323  * Initialize all plugins using their registered "init" function.
 324  *
 325  * Returns:
 326  * The number of failed initializations.
 327  */
 328 int
 329 sdb_plugin_init_all(void);
 330
 331 /*
 332  * sdb_plugin_shutdown_all:
 333  * Shutdown all plugins using their registered "shutdown" function.
 334  *
 335  * Returns:
 336  * The number of failed shutdowns.
 337  */
 338 int
 339 sdb_plugin_shutdown_all(void);
 340
 341 /*
 342  * sdb_plugin_collector_loop:
 343  * Loop until loop->do_loop is false, calling the next collector function on
 344  * each iteration and once its next update interval is passed.
 345  *
 346  * Returns:
 347  *  - 0 on success
 348  *  - a negative value else
 349  */
 350 int
 351 sdb_plugin_collector_loop(sdb_plugin_loop_t *loop);
 352
 353 /*
 354  * sdb_plugin_cname:
 355  * Returns the canonicalized hostname. The given hostname argument has to
 356  * point to dynamically allocated memory and might be freed by the function.
 357  * The return value will also be dynamically allocated (but it might be
 358  * unchanged) and has to be freed by the caller.
 359  */
 360 char *
 361 sdb_plugin_cname(char *hostname);
 362
 363 /*
 364  * sdb_plugin_log:
 365  * Log the specified message using all registered log callbacks. The message
 366  * will be logged with the specified priority.
 367  */
 368 int
 369 sdb_plugin_log(int prio, const char *msg);
 370
 371 /*
 372  * sdb_plugin_logf:
 373  * Log a formatted message. See sdb_plugin_log for more information.
 374  */
 375 int
 376 sdb_plugin_vlogf(int prio, const char *fmt, va_list ap)
 377                 __attribute__((format(printf, 2, 0)));
 378 int
 379 sdb_plugin_logf(int prio, const char *fmt, ...)
 380                 __attribute__((format(printf, 2, 3)));
 381
 382 /*
 383  * sdb_plugin_fetch_timeseries:
 384  * Fetch the time-series identified by 'id' from a backend data-store of the
 385  * specified 'type'. The type has to match an existing time-series fetcher
 386  * callback's name. The identifier is passed through to the callback which
 387  * then needs to make sense of it. The time-series option specify which data
 388  * to fetch.
 389  *
 390  * Returns:
 391  *  - a time-series on success
 392  *  - NULL else
 393  */
 394 sdb_timeseries_t *
 395 sdb_plugin_fetch_timeseries(const char *type, const char *id,
 396                 sdb_timeseries_opts_t *opts);
 397
 398 #ifdef __cplusplus
 399 } /* extern "C" */
 400 #endif
 401
 402 #endif /* ! SDB_CORE_PLUGIN_H */
 403
 404 /* vim: set tw=78 sw=4 ts=4 noexpandtab : */
 405