2014-08-31 14:43:28 +00:00
|
|
|
/** Hook funktions
|
|
|
|
*
|
|
|
|
* Every path can register a hook function which is called for every received
|
|
|
|
* message. This can be used to debug the data flow, get statistics
|
|
|
|
* or alter the message.
|
|
|
|
*
|
|
|
|
* This file includes some examples.
|
|
|
|
*
|
|
|
|
* @file
|
2015-06-02 21:53:04 +02:00
|
|
|
* @author Steffen Vogel <stvogel@eonerc.rwth-aachen.de>
|
2017-03-03 20:20:13 -04:00
|
|
|
* @copyright 2017, Institute for Automation of Complex Power Systems, EONERC
|
2017-04-27 12:56:43 +02:00
|
|
|
* @license GNU General Public License (version 3)
|
|
|
|
*
|
|
|
|
* VILLASnode
|
|
|
|
*
|
|
|
|
* This program is free software: you can redistribute it and/or modify
|
|
|
|
* it under the terms of the GNU General Public License as published by
|
|
|
|
* the Free Software Foundation, either version 3 of the License, or
|
|
|
|
* any later version.
|
2017-05-05 19:24:16 +00:00
|
|
|
*
|
2017-04-27 12:56:43 +02:00
|
|
|
* This program is distributed in the hope that it will be useful,
|
|
|
|
* but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
|
|
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
|
|
* GNU General Public License for more details.
|
2017-05-05 19:24:16 +00:00
|
|
|
*
|
2017-04-27 12:56:43 +02:00
|
|
|
* You should have received a copy of the GNU General Public License
|
|
|
|
* along with this program. If not, see <http://www.gnu.org/licenses/>.
|
2015-09-19 18:48:00 +02:00
|
|
|
*/
|
|
|
|
/**
|
2015-05-06 11:36:51 +02:00
|
|
|
* @addtogroup hooks User-defined hook functions
|
2015-09-19 18:48:00 +02:00
|
|
|
* @ingroup path
|
2015-05-06 11:36:51 +02:00
|
|
|
* @{
|
2015-06-02 21:53:04 +02:00
|
|
|
*********************************************************************************/
|
2017-05-05 19:24:16 +00:00
|
|
|
|
2017-02-18 10:47:15 -05:00
|
|
|
#pragma once
|
2014-08-31 14:43:28 +00:00
|
|
|
|
2015-06-05 12:39:40 +02:00
|
|
|
#include <time.h>
|
2016-10-12 16:57:14 +02:00
|
|
|
#include <string.h>
|
2017-03-27 12:26:11 +02:00
|
|
|
#include <stdbool.h>
|
2015-06-05 12:39:40 +02:00
|
|
|
|
2017-04-26 11:52:22 +02:00
|
|
|
#include "log_config.h"
|
2016-06-08 22:38:50 +02:00
|
|
|
#include "queue.h"
|
|
|
|
#include "list.h"
|
2017-03-12 17:01:24 -03:00
|
|
|
#include "super_node.h"
|
2017-03-17 01:08:48 -03:00
|
|
|
#include "common.h"
|
2017-02-18 10:49:42 -05:00
|
|
|
|
2015-06-10 15:10:51 +02:00
|
|
|
/* Forward declarations */
|
2014-08-31 14:43:28 +00:00
|
|
|
struct path;
|
2015-10-09 13:30:41 +02:00
|
|
|
struct hook;
|
2016-06-08 22:38:50 +02:00
|
|
|
struct sample;
|
2017-03-12 17:01:24 -03:00
|
|
|
struct super_node;
|
2014-08-31 14:43:28 +00:00
|
|
|
|
2017-03-27 12:26:11 +02:00
|
|
|
struct hook_type {
|
|
|
|
int priority; /**< Default priority of this hook type. */
|
|
|
|
bool builtin; /**< Should we add this hook by default to every path?. */
|
2016-06-08 22:38:50 +02:00
|
|
|
|
2017-03-27 12:26:11 +02:00
|
|
|
size_t size; /**< Size of allocation for struct hook::_vd */
|
2017-05-05 19:24:16 +00:00
|
|
|
|
2017-03-27 12:26:11 +02:00
|
|
|
int (*parse)(struct hook *h, config_setting_t *cfg);
|
2016-06-08 22:38:50 +02:00
|
|
|
|
2017-03-27 12:26:11 +02:00
|
|
|
int (*init)(struct hook *h); /**< Called before path is started to parseHOOK_DESTROYs. */
|
2017-05-05 19:24:16 +00:00
|
|
|
int (*destroy)(struct hook *h); /**< Called after path has been stopped to release memory allocated by HOOK_INIT */
|
2016-06-08 22:38:50 +02:00
|
|
|
|
2017-03-27 12:26:11 +02:00
|
|
|
int (*start)(struct hook *h); /**< Called whenever a path is started; before threads are created. */
|
|
|
|
int (*stop)(struct hook *h); /**< Called whenever a path is stopped; after threads are destoyed. */
|
2017-05-05 19:24:16 +00:00
|
|
|
|
2017-03-27 12:26:11 +02:00
|
|
|
int (*periodic)(struct hook *h);/**< Called periodically. Period is set by global 'stats' option in the configuration file. */
|
|
|
|
int (*restart)(struct hook *h); /**< Called whenever a new simulation case is started. This is detected by a sequence no equal to zero. */
|
2015-06-10 15:10:51 +02:00
|
|
|
|
2017-03-27 12:26:11 +02:00
|
|
|
int (*read)(struct hook *h, struct sample *smps[], size_t *cnt); /**< Called for every single received samples. */
|
|
|
|
int (*write)(struct hook *h, struct sample *smps[], size_t *cnt); /**< Called for every single sample which will be sent. */
|
2017-03-17 01:08:48 -03:00
|
|
|
};
|
|
|
|
|
2015-09-19 18:48:00 +02:00
|
|
|
/** Descriptor for user defined hooks. See hooks[]. */
|
2015-06-10 15:10:51 +02:00
|
|
|
struct hook {
|
2017-03-17 01:08:48 -03:00
|
|
|
enum state state;
|
2017-03-17 02:52:59 -03:00
|
|
|
|
2017-03-17 01:08:48 -03:00
|
|
|
struct sample *prev, *last;
|
2017-03-27 12:26:11 +02:00
|
|
|
struct path *path;
|
2017-05-05 19:24:16 +00:00
|
|
|
|
2017-03-17 01:08:48 -03:00
|
|
|
struct hook_type *_vt; /**< C++ like Vtable pointer. */
|
2016-06-08 22:38:50 +02:00
|
|
|
void *_vd; /**< Private data for this hook. This pointer can be used to pass data between consecutive calls of the callback. */
|
2017-05-05 19:24:16 +00:00
|
|
|
|
2017-03-17 02:52:59 -03:00
|
|
|
int priority; /**< A priority to change the order of execution within one type of hook. */
|
2014-08-31 14:43:28 +00:00
|
|
|
};
|
|
|
|
|
2016-01-15 15:34:28 +01:00
|
|
|
/** Save references to global nodes, paths and settings */
|
2017-03-27 12:26:11 +02:00
|
|
|
int hook_init(struct hook *h, struct hook_type *vt, struct path *p);
|
2016-10-22 20:42:05 -04:00
|
|
|
|
2017-03-17 01:08:48 -03:00
|
|
|
/** Parse a single hook.
|
|
|
|
*
|
|
|
|
* A hook definition is composed of the hook name and optional parameters
|
|
|
|
* seperated by a colon.
|
|
|
|
*
|
|
|
|
* Examples:
|
|
|
|
* "print:stdout"
|
|
|
|
*/
|
|
|
|
int hook_parse(struct hook *h, config_setting_t *cfg);
|
2016-01-15 15:34:28 +01:00
|
|
|
|
2017-03-17 01:08:48 -03:00
|
|
|
int hook_destroy(struct hook *h);
|
2016-01-15 15:34:28 +01:00
|
|
|
|
2017-03-27 12:26:11 +02:00
|
|
|
int hook_start(struct hook *h);
|
|
|
|
int hook_stop(struct hook *h);
|
|
|
|
|
|
|
|
int hook_periodic(struct hook *h);
|
|
|
|
int hook_restart(struct hook *h);
|
|
|
|
|
|
|
|
int hook_read(struct hook *h, struct sample *smps[], size_t *cnt);
|
|
|
|
int hook_write(struct hook *h, struct sample *smps[], size_t *cnt);
|
|
|
|
|
|
|
|
size_t hook_read_list(struct list *hs, struct sample *smps[], size_t cnt);
|
|
|
|
size_t hook_write_list(struct list *hs, struct sample *smps[], size_t cnt);
|
|
|
|
|
2017-03-05 10:06:32 -04:00
|
|
|
/** Compare two hook functions with their priority. Used by list_sort() */
|
|
|
|
int hook_cmp_priority(const void *a, const void *b);
|
2016-01-14 22:52:08 +01:00
|
|
|
|
2017-03-17 02:52:59 -03:00
|
|
|
/** Parses an object of hooks
|
2016-11-20 12:59:37 -05:00
|
|
|
*
|
2017-03-17 02:52:59 -03:00
|
|
|
* Example:
|
|
|
|
*
|
|
|
|
* {
|
|
|
|
* stats = {
|
|
|
|
* output = "stdout"
|
|
|
|
* },
|
|
|
|
* skip_first = {
|
|
|
|
* seconds = 10
|
|
|
|
* },
|
|
|
|
* hooks = [ "print" ]
|
|
|
|
* }
|
2016-11-20 12:59:37 -05:00
|
|
|
*/
|
2017-04-26 11:52:22 +02:00
|
|
|
int hook_parse_list(struct list *list, config_setting_t *cfg, struct path *p);
|