2023-09-04 12:21:37 +02:00
|
|
|
/* Hook functions.
|
2019-03-26 15:33:47 +01:00
|
|
|
*
|
|
|
|
* Every node or path can register hook functions which is called for every
|
|
|
|
* processed sample. This can be used to debug the data flow, get statistics
|
|
|
|
* or alter the sample contents.
|
|
|
|
*
|
2022-03-15 09:18:01 -04:00
|
|
|
* Author: Steffen Vogel <post@steffenvogel.de>
|
2022-03-15 09:28:57 -04:00
|
|
|
* SPDX-FileCopyrightText: 2014-2023 Institute for Automation of Complex Power Systems, RWTH Aachen University
|
2022-07-04 18:20:03 +02:00
|
|
|
* SPDX-License-Identifier: Apache-2.0
|
2019-03-26 15:33:47 +01:00
|
|
|
*/
|
|
|
|
|
|
|
|
#pragma once
|
|
|
|
|
|
|
|
#include <villas/exceptions.hpp>
|
2021-08-10 10:12:48 -04:00
|
|
|
#include <villas/list.hpp>
|
2019-03-26 15:33:47 +01:00
|
|
|
#include <villas/log.hpp>
|
|
|
|
#include <villas/plugin.hpp>
|
|
|
|
#include <villas/signal.hpp>
|
2021-08-10 10:12:48 -04:00
|
|
|
#include <villas/signal_list.hpp>
|
2019-03-26 15:33:47 +01:00
|
|
|
|
|
|
|
namespace villas {
|
|
|
|
namespace node {
|
|
|
|
|
2021-08-10 10:12:48 -04:00
|
|
|
// Forward declarations
|
|
|
|
class Node;
|
|
|
|
class Path;
|
|
|
|
struct Sample;
|
|
|
|
class HookFactory;
|
|
|
|
|
2019-03-26 15:33:47 +01:00
|
|
|
class Hook {
|
|
|
|
|
2021-08-10 10:12:48 -04:00
|
|
|
friend HookFactory;
|
|
|
|
|
2019-06-23 16:13:23 +02:00
|
|
|
public:
|
2021-08-10 10:12:48 -04:00
|
|
|
using Ptr = std::shared_ptr<Hook>;
|
2023-09-07 11:46:39 +02:00
|
|
|
|
2019-06-23 16:13:23 +02:00
|
|
|
enum class Flags {
|
2021-07-06 16:25:14 +02:00
|
|
|
BUILTIN = (1 << 0), // Should we add this hook by default to every path?.
|
|
|
|
PATH = (1 << 1), // This hook type is used by paths.
|
|
|
|
NODE_READ = (1 << 2), // This hook type is used by nodes.
|
|
|
|
NODE_WRITE = (1 << 3) // This hook type is used by nodes.
|
2019-06-23 16:13:23 +02:00
|
|
|
};
|
2023-09-07 11:46:39 +02:00
|
|
|
|
2019-06-23 16:13:23 +02:00
|
|
|
enum class Reason { OK = 0, ERROR, SKIP_SAMPLE, STOP_PROCESSING };
|
|
|
|
|
2019-03-26 15:33:47 +01:00
|
|
|
protected:
|
|
|
|
Logger logger;
|
|
|
|
|
2021-08-10 10:12:48 -04:00
|
|
|
HookFactory *factory;
|
|
|
|
|
2019-06-23 16:13:23 +02:00
|
|
|
enum State state;
|
2019-03-26 15:33:47 +01:00
|
|
|
|
|
|
|
int flags;
|
2021-07-06 16:26:33 +02:00
|
|
|
unsigned
|
|
|
|
priority; // A priority to change the order of execution within one type of hook.
|
|
|
|
bool enabled; // Is this hook active?
|
2019-03-26 15:33:47 +01:00
|
|
|
|
2021-08-10 10:12:48 -04:00
|
|
|
Path *path;
|
|
|
|
Node *node;
|
2019-03-26 15:33:47 +01:00
|
|
|
|
2021-08-10 10:12:48 -04:00
|
|
|
SignalList::Ptr signals;
|
2019-03-26 15:33:47 +01:00
|
|
|
|
2021-07-06 16:25:14 +02:00
|
|
|
json_t *config; // A JSON object containing the configuration of the hook.
|
2019-03-26 15:33:47 +01:00
|
|
|
|
|
|
|
public:
|
2021-08-10 10:12:48 -04:00
|
|
|
Hook(Path *p, Node *n, int fl, int prio, bool en = true);
|
2023-09-07 11:46:39 +02:00
|
|
|
|
2021-08-10 10:12:48 -04:00
|
|
|
virtual ~Hook() {}
|
2023-09-07 11:46:39 +02:00
|
|
|
|
2021-07-06 16:25:14 +02:00
|
|
|
virtual void parse(json_t *json);
|
2023-09-07 11:46:39 +02:00
|
|
|
|
2021-08-10 10:12:48 -04:00
|
|
|
void prepare(SignalList::Ptr sigs);
|
2023-09-07 11:46:39 +02:00
|
|
|
|
2021-07-06 18:33:33 +02:00
|
|
|
Logger getLogger() { return logger; }
|
2023-09-07 11:46:39 +02:00
|
|
|
|
2019-03-26 15:33:47 +01:00
|
|
|
// Called whenever a hook is started; before threads are created.
|
2021-06-18 14:28:31 -04:00
|
|
|
virtual void start() {
|
2019-06-23 16:13:23 +02:00
|
|
|
assert(state == State::PREPARED);
|
2023-09-07 11:46:39 +02:00
|
|
|
|
2019-06-23 16:13:23 +02:00
|
|
|
state = State::STARTED;
|
2019-03-26 15:33:47 +01:00
|
|
|
}
|
2023-09-07 11:46:39 +02:00
|
|
|
|
2019-03-26 15:33:47 +01:00
|
|
|
// Called whenever a hook is stopped; after threads are destoyed.
|
2021-06-18 14:28:31 -04:00
|
|
|
virtual void stop() {
|
2019-06-23 16:13:23 +02:00
|
|
|
assert(state == State::STARTED);
|
2023-09-07 11:46:39 +02:00
|
|
|
|
2019-06-23 16:13:23 +02:00
|
|
|
state = State::STOPPED;
|
2019-03-26 15:33:47 +01:00
|
|
|
}
|
2023-09-07 11:46:39 +02:00
|
|
|
|
2021-06-18 14:28:31 -04:00
|
|
|
virtual void check() {
|
2019-06-23 16:13:23 +02:00
|
|
|
assert(state == State::PARSED);
|
2023-09-07 11:46:39 +02:00
|
|
|
|
2019-06-23 16:13:23 +02:00
|
|
|
state = State::CHECKED;
|
2021-08-10 10:12:48 -04:00
|
|
|
}
|
2023-09-07 11:46:39 +02:00
|
|
|
|
2021-06-18 14:28:31 -04:00
|
|
|
virtual void prepare() {
|
2019-06-23 16:13:23 +02:00
|
|
|
assert(state == State::CHECKED);
|
2023-09-07 11:46:39 +02:00
|
|
|
|
2019-03-26 15:33:47 +01:00
|
|
|
state = State::PREPARED;
|
2023-09-07 11:46:39 +02:00
|
|
|
}
|
|
|
|
|
2019-03-26 15:33:47 +01:00
|
|
|
// Called periodically. Period is set by global 'stats' option in the configuration file.
|
2019-06-23 16:13:23 +02:00
|
|
|
virtual void periodic() { assert(state == State::STARTED); }
|
2023-09-07 11:46:39 +02:00
|
|
|
|
2019-03-26 15:33:47 +01:00
|
|
|
// Called whenever a new simulation case is started. This is detected by a sequence no equal to zero.
|
2021-06-18 14:28:31 -04:00
|
|
|
virtual void restart() { assert(state == State::STARTED); }
|
2023-09-07 11:46:39 +02:00
|
|
|
|
2021-08-10 10:12:48 -04:00
|
|
|
// Called whenever a sample is processed.
|
2019-06-23 16:13:23 +02:00
|
|
|
virtual Reason process(struct Sample *smp) { return Reason::OK; };
|
2023-09-07 11:46:39 +02:00
|
|
|
|
2019-03-26 15:33:47 +01:00
|
|
|
unsigned getPriority() const { return priority; }
|
2023-09-07 11:46:39 +02:00
|
|
|
|
2019-03-26 15:33:47 +01:00
|
|
|
int getFlags() const { return flags; }
|
2023-09-07 11:46:39 +02:00
|
|
|
|
2021-08-10 10:12:48 -04:00
|
|
|
virtual SignalList::Ptr getSignals() const { return signals; }
|
2023-09-07 11:46:39 +02:00
|
|
|
|
2020-08-17 17:06:58 +02:00
|
|
|
json_t *getConfig() const { return config; }
|
2023-09-07 11:46:39 +02:00
|
|
|
|
2021-08-10 10:12:48 -04:00
|
|
|
HookFactory *getFactory() const { return factory; }
|
2023-09-07 11:46:39 +02:00
|
|
|
|
2019-03-26 15:33:47 +01:00
|
|
|
bool isEnabled() const { return enabled; }
|
|
|
|
};
|
|
|
|
|
2021-07-06 16:27:24 +02:00
|
|
|
class SingleSignalHook : public Hook {
|
|
|
|
|
|
|
|
protected:
|
|
|
|
unsigned signalIndex;
|
|
|
|
std::string signalName;
|
|
|
|
|
|
|
|
public:
|
2021-08-10 10:12:48 -04:00
|
|
|
SingleSignalHook(Path *p, Node *n, int fl, int prio, bool en = true)
|
2021-09-17 18:19:06 +02:00
|
|
|
: Hook(p, n, fl, prio, en), signalIndex(0) {}
|
2021-07-06 16:27:24 +02:00
|
|
|
|
|
|
|
virtual void parse(json_t *json);
|
|
|
|
|
|
|
|
virtual void prepare();
|
|
|
|
};
|
|
|
|
|
|
|
|
class MultiSignalHook : public Hook {
|
|
|
|
|
|
|
|
protected:
|
|
|
|
std::list<unsigned> signalIndices;
|
2021-11-23 14:14:13 +01:00
|
|
|
std::vector<std::string> signalNames;
|
2021-07-06 16:27:24 +02:00
|
|
|
|
|
|
|
public:
|
|
|
|
using Hook::Hook;
|
|
|
|
|
|
|
|
virtual void parse(json_t *json);
|
|
|
|
|
|
|
|
virtual void prepare();
|
|
|
|
|
|
|
|
virtual void check();
|
|
|
|
};
|
|
|
|
|
2019-04-12 09:50:42 +02:00
|
|
|
class LimitHook : public Hook {
|
|
|
|
|
|
|
|
public:
|
2021-08-10 10:12:48 -04:00
|
|
|
using Ptr = std::shared_ptr<LimitHook>;
|
2019-04-12 09:50:42 +02:00
|
|
|
using Hook::Hook;
|
2023-09-07 11:46:39 +02:00
|
|
|
|
2019-04-12 09:50:42 +02:00
|
|
|
virtual void setRate(double rate, double maxRate = -1) = 0;
|
2023-09-07 11:46:39 +02:00
|
|
|
|
2021-07-06 16:26:53 +02:00
|
|
|
virtual void parse() {
|
2019-06-23 16:13:23 +02:00
|
|
|
assert(state == State::INITIALIZED);
|
2023-09-07 11:46:39 +02:00
|
|
|
|
2019-06-23 16:13:23 +02:00
|
|
|
state = State::PARSED;
|
2019-04-15 12:27:41 +02:00
|
|
|
}
|
2023-09-07 11:46:39 +02:00
|
|
|
|
2019-04-15 12:27:41 +02:00
|
|
|
void init() {
|
|
|
|
parse();
|
|
|
|
check();
|
|
|
|
prepare();
|
|
|
|
start();
|
|
|
|
}
|
2019-04-12 09:50:42 +02:00
|
|
|
};
|
|
|
|
|
2019-03-26 15:33:47 +01:00
|
|
|
class HookFactory : public plugin::Plugin {
|
|
|
|
|
2021-08-10 10:12:48 -04:00
|
|
|
protected:
|
|
|
|
virtual void init(Hook::Ptr h) {
|
|
|
|
h->logger = getLogger();
|
|
|
|
h->factory = this;
|
|
|
|
}
|
|
|
|
|
2019-03-26 15:33:47 +01:00
|
|
|
public:
|
2020-06-14 15:00:02 +02:00
|
|
|
using plugin::Plugin::Plugin;
|
2019-03-26 15:33:47 +01:00
|
|
|
|
2021-08-10 10:12:48 -04:00
|
|
|
virtual Hook::Ptr make(Path *p, Node *n) = 0;
|
|
|
|
|
|
|
|
virtual int getFlags() const = 0;
|
2019-03-26 15:33:47 +01:00
|
|
|
|
2021-08-10 10:12:48 -04:00
|
|
|
virtual unsigned getPriority() const = 0;
|
2021-06-18 14:24:28 -04:00
|
|
|
|
2021-08-10 10:12:48 -04:00
|
|
|
virtual std::string getType() const { return "hook"; }
|
2022-03-14 15:34:10 -04:00
|
|
|
|
|
|
|
virtual bool isHidden() const { return false; }
|
2019-03-26 15:33:47 +01:00
|
|
|
};
|
|
|
|
|
2021-07-06 16:26:33 +02:00
|
|
|
template <typename T, const char *name, const char *desc, int flags = 0,
|
|
|
|
unsigned prio = 99>
|
2019-03-26 15:33:47 +01:00
|
|
|
class HookPlugin : public HookFactory {
|
|
|
|
|
|
|
|
public:
|
|
|
|
using HookFactory::HookFactory;
|
2023-09-07 11:46:39 +02:00
|
|
|
|
2021-08-10 10:12:48 -04:00
|
|
|
virtual Hook::Ptr make(Path *p, Node *n) {
|
|
|
|
auto h = std::make_shared<T>(p, n, getFlags(), getPriority());
|
2023-09-07 11:46:39 +02:00
|
|
|
|
2021-08-10 10:12:48 -04:00
|
|
|
init(h);
|
2023-09-07 11:46:39 +02:00
|
|
|
|
2021-06-18 14:24:28 -04:00
|
|
|
return h;
|
2020-06-14 15:00:02 +02:00
|
|
|
}
|
2023-09-07 11:46:39 +02:00
|
|
|
|
2021-08-10 10:12:48 -04:00
|
|
|
virtual std::string getName() const { return name; }
|
2023-09-07 11:46:39 +02:00
|
|
|
|
2021-08-10 10:12:48 -04:00
|
|
|
virtual std::string getDescription() const { return desc; }
|
2023-09-07 11:46:39 +02:00
|
|
|
|
2021-08-10 10:12:48 -04:00
|
|
|
virtual int getFlags() const { return flags; }
|
2023-09-07 11:46:39 +02:00
|
|
|
|
2021-08-10 10:12:48 -04:00
|
|
|
virtual unsigned getPriority() const { return prio; }
|
2019-03-26 15:33:47 +01:00
|
|
|
};
|
|
|
|
|
2023-08-28 09:34:02 +02:00
|
|
|
} // namespace node
|
|
|
|
} // namespace villas
|