/** Hook functions * * 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. * * @file * @author Steffen Vogel * @copyright 2014-2022, Institute for Automation of Complex Power Systems, EONERC * @license Apache 2.0 *********************************************************************************/ #pragma once #include #include #include #include #include #include namespace villas { namespace node { /* Forward declarations */ class Node; class Path; struct Sample; class HookFactory; class Hook { friend HookFactory; public: using Ptr = std::shared_ptr; enum class Flags { 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. */ }; enum class Reason { OK = 0, ERROR, SKIP_SAMPLE, STOP_PROCESSING }; protected: Logger logger; HookFactory *factory; enum State state; int flags; unsigned priority; /**< A priority to change the order of execution within one type of hook. */ bool enabled; /**< Is this hook active? */ Path *path; Node *node; SignalList::Ptr signals; json_t *config; /**< A JSON object containing the configuration of the hook. */ public: Hook(Path *p, Node *n, int fl, int prio, bool en = true); virtual ~Hook() { } virtual void parse(json_t *json); void prepare(SignalList::Ptr sigs); Logger getLogger() { return logger; } /** Called whenever a hook is started; before threads are created. */ virtual void start() { assert(state == State::PREPARED); state = State::STARTED; } /** Called whenever a hook is stopped; after threads are destoyed. */ virtual void stop() { assert(state == State::STARTED); state = State::STOPPED; } virtual void check() { assert(state == State::PARSED); state = State::CHECKED; } virtual void prepare() { assert(state == State::CHECKED); state = State::PREPARED; } /** Called periodically. Period is set by global 'stats' option in the configuration file. */ virtual void periodic() { assert(state == State::STARTED); } /** Called whenever a new simulation case is started. This is detected by a sequence no equal to zero. */ virtual void restart() { assert(state == State::STARTED); } /** Called whenever a sample is processed. */ virtual Reason process(struct Sample *smp) { return Reason::OK; }; unsigned getPriority() const { return priority; } int getFlags() const { return flags; } virtual SignalList::Ptr getSignals() const { return signals; } json_t * getConfig() const { return config; } HookFactory * getFactory() const { return factory; } bool isEnabled() const { return enabled; } }; class SingleSignalHook : public Hook { protected: unsigned signalIndex; std::string signalName; public: SingleSignalHook(Path *p, Node *n, int fl, int prio, bool en = true) : Hook(p, n, fl, prio, en), signalIndex(0) { } virtual void parse(json_t *json); virtual void prepare(); }; class MultiSignalHook : public Hook { protected: std::list signalIndices; std::vector signalNames; public: using Hook::Hook; virtual void parse(json_t *json); virtual void prepare(); virtual void check(); }; class LimitHook : public Hook { public: using Ptr = std::shared_ptr; using Hook::Hook; virtual void setRate(double rate, double maxRate = -1) = 0; virtual void parse() { assert(state == State::INITIALIZED); state = State::PARSED; } void init() { parse(); check(); prepare(); start(); } }; class HookFactory : public plugin::Plugin { protected: virtual void init(Hook::Ptr h) { h->logger = getLogger(); h->factory = this; } public: using plugin::Plugin::Plugin; virtual Hook::Ptr make(Path *p, Node *n) = 0; virtual int getFlags() const = 0; virtual unsigned getPriority() const = 0; virtual std::string getType() const { return "hook"; } virtual bool isHidden() const { return false; } }; template class HookPlugin : public HookFactory { public: using HookFactory::HookFactory; virtual Hook::Ptr make(Path *p, Node *n) { auto h = std::make_shared(p, n, getFlags(), getPriority()); init(h); return h; } virtual std::string getName() const { return name; } virtual std::string getDescription() const { return desc; } virtual int getFlags() const { return flags; } virtual unsigned getPriority() const { return prio; } }; } /* namespace node */ } /* namespace villas */