// SPDX-FileCopyrightText: Deutsches Elektronen-Synchrotron DESY, MSK, ChimeraTK Project <chimeratk-support@desy.de>
// SPDX-License-Identifier: LGPL-3.0-or-later
#pragma once
#include "Flags.h"
#include "VariableNetworkNode.h"
#include <list>
#include <string>
namespace ChimeraTK {
/********************************************************************************************************************/
class AccessorBase;
class Module;
class VirtualModule;
/********************************************************************************************************************/
/**
* Convenience type definition which can optionally be used as a shortcut for the type which defines a list of
* tags.
*/
using TAGS = const std::unordered_set<std::string>;
/********************************************************************************************************************/
/**
* Base class for owners of other EntityOwners (e.g. Modules) and Accessors.
* FIXME: Unify with Module class (not straight forward!).
*/
class EntityOwner {
public:
/** Constructor: Create EntityOwner by the given name with the given description. The specified list of
* tags will be added to all elements directly or indirectly owned by this instance. */
EntityOwner(
const std::string& name, const std::string& description, const std::unordered_set<std::string>& tags = {});
/** Default constructor just for late initialisation */
EntityOwner();
/** Virtual destructor to make the type polymorphic */
virtual ~EntityOwner();
/** Move constructor */
EntityOwner(EntityOwner&& other) { operator=(std::move(other)); }
EntityOwner(const EntityOwner& other) = delete;
/** Move assignment operator */
EntityOwner& operator=(EntityOwner&& other);
EntityOwner& operator=(const EntityOwner& other) = delete;
/** Get the name of the module instance */
const std::string& getName() const { return _name; }
/** Get the fully qualified name of the module instance, i.e. the name
* containing all module names further up in the hierarchy. */
virtual std::string getQualifiedName() const = 0;
/** Get the description of the module instance */
const std::string& getDescription() const { return _description; }
/** Obtain the full description including the full description of the owner.
*/
virtual std::string getFullDescription() const = 0;
/** Obtain the list of accessors/variables directly associated with this
* instance */
virtual std::list<VariableNetworkNode> getAccessorList() const { return accessorList; }
/** Obtain the list of submodules associated with this instance */
virtual std::list<Module*> getSubmoduleList() const { return moduleList; }
/** Obtain the list of accessors/variables associated with this instance and
* any submodules */
std::list<VariableNetworkNode> getAccessorListRecursive() const;
/** Obtain the list of submodules associated with this instance and any
* submodules */
std::list<Module*> getSubmoduleListRecursive() const;
/** Check whether a submodule exists by the given name (not taking into
* account eliminated hierarchies etc.) */
bool hasSubmodule(const std::string& name) const;
/** Get a submodule by the given name (not taking into account eliminated
* hierarchies etc.) */
Module* getSubmodule(const std::string& name) const;
/** Return a VirtualModule containing the part of the tree structure matching
* the given tag. The resulting VirtualModule might have virtual sub-modules,
* if this EntityOwner contains sub-EntityOwners with entities matching the
* tag. "tag" is interpreted as a regular expression (see std::regex_match).
*/
VirtualModule findTag(const std::string& tag) const;
/** Return a VirtualModule containing the part of the tree structure not
* matching the given tag. This is the negation of findTag(), this function
* will keep those variables which findTag() would remove from the tree.
* Again, "tag" is interpreted as a regular expression (see std::regex_match).
*/
VirtualModule excludeTag(const std::string& tag) const;
/** Called inside the constructor of Accessor: adds the accessor to the list
*/
void registerAccessor(VariableNetworkNode accessor);
/** Called inside the destructor of Accessor: removes the accessor from the
* list */
void unregisterAccessor(VariableNetworkNode accessor) { accessorList.remove(accessor); }
/** Register another module as a sub-module. Will be called automatically by
* all modules in their constructors. If addTags is set to false, the tags of
* this EntityOwner will not be set to the module being registered. This is
* e.g. used in the move-constructor of Module to prevent from altering the
* tags in the move operation. */
void registerModule(Module* module, bool addTags = true);
/** Unregister another module as a sub-module. Will be called automatically by
* all modules in their destructors. */
void unregisterModule(Module* module);
/** Add a tag to all Application-type nodes inside this group. It will recurse
* into any subgroups. See VariableNetworkNode::addTag() for additional
* information about tags. */
void addTag(const std::string& tag);
/** Create a VirtualModule which contains all variables of this EntityOwner in
* a flat hierarchy. It will recurse
* through all sub-modules and add all found variables directly to the
* VirtualModule. */
VirtualModule flatten();
void accept(Visitor<EntityOwner>& visitor) const { visitor.dispatch(*this); }
/** Print the full hierarchy to stdout. */
void dump(const std::string& prefix = "") const;
/** Create Graphviz dot graph and write to file. The graph will contain the
* full hierarchy of modules and variables below (and including) this module.
* Each variable will also show which tags are attached to it. ModuleGroups
* will be drawn with a double line, ApplicationModules with a bold line.
* Hierarchies which will be eliminated in the dynamic information model are
* shown with a dotted line. */
void dumpGraph(const std::string& fileName = "graph.dot") const;
/** Create a Graphiz dot graph similar to the one created with dumpGraph, but
* just show the modules and not the
* variables. This allows to get an overview over more complex applications.
*/
void dumpModuleGraph(const std::string& fileName = "graph.dot") const;
enum class ModuleType { ApplicationModule, ModuleGroup, VariableGroup, ControlSystem, Device, Invalid };
/** Return the module type of this module, or in case of a VirtualModule the
* module type this VirtualModule was derived from. */
virtual ModuleType getModuleType() const = 0;
/** Return the current version number which has been received with the last
* push-type read operation. */
virtual VersionNumber getCurrentVersionNumber() const = 0;
/** Set the current version number. This function is called by the push-type
* input accessors in their read functions. */
virtual void setCurrentVersionNumber(VersionNumber versionNumber) = 0;
/** Return the data validity flag. If any This function will be called by all output accessors in their write
* functions. */
virtual DataValidity getDataValidity() const = 0;
/** Set the data validity flag to fault and increment the fault counter. This function will be called by all input
* accessors when receiving the a faulty update if the previous update was ok. The caller of this function must
* ensure that calls to this function are paired to a subsequent call to decrementDataFaultCounter(). */
virtual void incrementDataFaultCounter() = 0;
/** Decrement the fault counter and set the data validity flag to ok if the counter has reached 0. This function
* will be called by all input accessors when receiving the an ok update if the previous update was faulty. The
* caller of this function must ensure that calles to this function are paired to a previous call to
* incrementDataFaultCounter(). */
virtual void decrementDataFaultCounter() = 0;
/** Use pointer to the module as unique identifier.*/
virtual std::list<EntityOwner*> getInputModulesRecursively(std::list<EntityOwner*> startList) = 0;
/** Get the ID of the circular dependency network (0 if none). This information is only available after
* the Application has finalised all connections.
*/
virtual size_t getCircularNetworkHash() = 0;
/**
* Create a variable name which will be automatically connected with a constant value. This can be used when
* instantiating generic modules which expect a parameter by variable name, when the parameter shall be set to
* a constant value.
*
* This function is a static member of the EntityOwner, since it is normally called in constructors of
* EntityOwners.
*/
template<typename T>
static std::string constant(T value);
/** Add the part of the tree structure matching the given tag to a
* VirtualModule. Users normally will use findTag() instead. "tag" is
* interpreted as a regular expression (see std::regex_match). */
virtual void findTagAndAppendToModule(VirtualModule& virtualParent, const std::string& tag,
bool eliminateAllHierarchies, bool eliminateFirstHierarchy, bool negate, VirtualModule& root) const;
/** Check whether this module has declared that it reached the testable mode. */
bool hasReachedTestableMode();
protected:
/** Convert HierarchyModifier into path qualification (for backwards compatibility only!) */
void applyHierarchyModifierToName(HierarchyModifier hierarchyModifier);
/** The name of this instance */
std::string _name;
/** The description of this instance */
std::string _description;
/** List of accessors owned by this instance */
std::list<VariableNetworkNode> accessorList;
/** List of modules owned by this instance */
std::list<Module*> moduleList;
/** List of tags to be added to all accessors and modules inside this module
*/
std::unordered_set<std::string> _tags;
/** Flag used by the testable mode to identify whether a thread within the EntityOwner has reached the point where
* the testable mode lock is acquired.
* @todo This should be moved to a more proper place in the hierarchy (e.g. ModuleImpl) after InternalModule class
* has been properly unified with the normal Module class. */
std::atomic<bool> testableModeReached{false};
};
/********************************************************************************************************************/
template<typename T>
std::string EntityOwner::constant(T value) {
return "@CONST@" + userTypeToUserType<std::string>(value);
}
/********************************************************************************************************************/
} /* namespace ChimeraTK */