// SPDX-FileCopyrightText: Helmholtz-Zentrum Dresden-Rossendorf, FWKE, ChimeraTK Project <chimeratk-support@desy.de>
// SPDX-License-Identifier: LGPL-3.0-or-later
#pragma once
/*!
* \author Klaus Zenker (HZDR)
* \date 10.08.2018
* \page historydoc Server based history module
* \section historyintro Server based history
* Some control systems offer a variable history but some do not. In this case
* the \c ServerHistory can be used to create a history ring buffer on the
* server. If only a local history is needed consider to use the \c MicroDAQ
* module. In order to do so you connect the variable that should have a history
* on the server to the \c ServerHistory module. The history length is set
* during module construction and fixed per module. Every time one of the
* variable handled by the history module is updated it will be filled into the
* history buffer. The buffer length (history length) can not be changed during
* runtime. Finally, one can create an addition buffer for each history
* buffer that includes the time stamps of each data point in the history buffer.
* This is useful if not all history buffers are filled with the same rate or the
* rate is not known.
*
*
* Output variables created by the \c ServerHistory module are named like their
* feeding process variables with a prefixed name that is set when the process
* variables is added to the history module. In case of Array type feeding
* process variables n history buffers are created (where n is the Array size)
* and the element index i is appended to the feeding process variable name. In
* consequence an input array of length i will result in i output history
* arrays. The following tags are added to the history output variable:
* - name of the history module
*
* The connection of variables with the 'history' tag to the ServerHistory module is
* done automatically.
* \attention Only variables of modules defined before constructing the ServerHistory
* module are considered.
*
* It is also possible to connect a DeviceModule to the ServerHistory module.
* Variables of Devices have no tags and therefor they will not be automatically connected
* to the SereverHistory module. One has to call addSource().
* In addition a trigger in case the variables are not push type. It is given as optional
* parameter to the \c addSource method.
* If the device variables are writable they are of push type. In this case
* the trigger will not be added. One has to use the LogicalNameMapping backend to
* force the device variables to be read only by using the \c forceReadOnly plugin.
* Using the LogicalNameMapping backend also allows to select individual device
* process variables to be connected to the \c ServerHistory.
*
*
* The following example shows how to integrate the \c ServerHistory module.
* \code
* sruct TestModule: public ChimeraTK::ApplicationModule{
* chimeraTK::ScalarOutput<float> measurement{this, "measurement", "" ,
* "measurement variable", {"history"}};
* ...
* };
* struct myApp : public ChimeraTK::Application{
*
* history::ServerHistory<float> history{this, "ServerHistory", "History for
* certain scalara float variables", 20}; // History buffer length is 20
*
* ChimeraTK::ControlSystemModule cs;
*
* ChimeraTK::ConnectingDeviceModule dev{this, "Dummy", "Trigger/tick"};
*
* ChimeraTK::PeriodicTrigger trigger{this, "Trigger", "Trigger used for other modules"};
*
*
* TestModule test{ this, "test", "" };
* ...
* };
*
*
* void myAPP::intitialise(){
* // The variable of the TestModule will show up in the control system as history/test/measurement automatically
* (identified by the tag).
* // Add a device. Updating of the history buffer is trigger external by the given trigger
* history.addSource(&dev,"device_history",trigger.tick);
* ChimeraTK::Application::initialise();
* ...
* }
*
* \endcode
*
* \remark Before starting the main loop of the server history module \c readAnyGroup() is called.
* This seems to block until all connected variables are written once. So if the history buffers
* are not filled make sure all variables are written. If they are not written in the module main loop,
* write them once before the main loop of the module containing the history variables.
*/
#include "ApplicationModule.h"
#include "ArrayAccessor.h"
#include "DeviceModule.h"
#include "VariableGroup.h"
#include <unordered_set>
#include <ChimeraTK/SupportedUserTypes.h>
#include <string>
#include <tuple>
#include <vector>
namespace ChimeraTK { namespace history {
struct AccessorAttacher;
template<typename UserType>
struct HistoryEntry {
HistoryEntry(bool enableHistory)
: data(std::vector<ArrayOutput<UserType>>{}), timeStamp(std::vector<ArrayOutput<uint64_t>>{}),
withTimeStamps(enableHistory) {}
std::vector<ArrayOutput<UserType>> data;
std::vector<ArrayOutput<uint64_t>> timeStamp;
bool withTimeStamps;
};
class ServerHistory : public ApplicationModule {
public:
/**
* Constructor.
* Addition parameters to a normal application module constructor:
* \param owner Module owner passed to ApplicationModule constructor.
* \param name Module name passed to ApplicationModule constructor.
* \param description Module description passed to ApplicationModule constructor.
* \param historyLength Length of the history buffers.
* \param enableTimeStamps An additional
* ring buffer per variable will be added that holds the time stamps corresponding to the data ring buffer entries.
* \param hierarchyModifier Flag passed to ApplicationModule constructor.
* \param tags Module tags passed to ApplicationModule constructor.
*/
ServerHistory(EntityOwner* owner, const std::string& name, const std::string& description,
size_t historyLength = 1200, bool enableTimeStamps = false,
HierarchyModifier hierarchyModifier = HierarchyModifier::none,
const std::unordered_set<std::string>& tags = {});
/** Default constructor, creates a non-working module. Can be used for late
* initialisation. */
ServerHistory() : _historyLength(1200), _enbaleTimeStamps(false) {}
/**
* Ad variables of a device to the ServerHistory. Calls virtualiseFromCatalog to get access to the internal variables.
*
* \param source For all variables of this module ring buffers are created.
* Use the LogicalNameMapping to create a virtual device module that holds all variables that should be
* passed to the history module.
* \param namePrefix This prefix is added to variable names added to the root directory in the process variable
* tree. E.g. a prefix \c history for a variable names data will appear as history/dummy/data
* if dummy is the name of the source module.
* \param submodule If only a submodule should be added give the name.
* It does not work do create a submodule of the DeviceModule itself!
* \param trigger This trigger is used for all poll type variable found in the source module.
*/
void addSource(const DeviceModule& source, const RegisterPath& namePrefix, const std::string& submodule = "",
const VariableNetworkNode& trigger = {});
/**
* Just gets the device module from the ConnectingDeviceModule before calling the DeviceModule version of addSource.
*/
void addSource(ConnectingDeviceModule* source, const RegisterPath& namePrefix, const std::string& submodule = "",
const VariableNetworkNode& trigger = {});
void prepare() override;
void mainLoop() override;
void findTagAndAppendToModule(VirtualModule& virtualParent, const std::string& tag, bool eliminateAllHierarchies,
bool eliminateFirstHierarchy, bool negate, VirtualModule& root) const override;
private:
void prepareHierarchy(const RegisterPath& namePrefix);
/**
* See public method for documentation.
*/
void addSource(const Module& source, const RegisterPath& namePrefix, const VariableNetworkNode& trigger = {});
template<typename UserType>
VariableNetworkNode getAccessor(const std::string& variableName, const size_t& nElements);
/** Map of VariableGroups required to build the hierarchies. The key it the
* full path name. */
std::map<std::string, VariableGroup> groupMap;
/** boost::fusion::map of UserTypes to std::lists containing the
* ArrayPushInput and ArrayOutput accessors. These accessors are dynamically
* created by the AccessorAttacher. */
template<typename UserType>
using AccessorList = std::list<std::pair<ArrayPushInput<UserType>, HistoryEntry<UserType>>>;
TemplateUserTypeMapNoVoid<AccessorList> _accessorListMap;
/** boost::fusion::map of UserTypes to std::lists containing the names of the
* accessors. Technically there would be no need to use TemplateUserTypeMap
* for this (as type does not depend on the UserType), but since these lists
* must be filled consistently with the accessorListMap, the same construction
* is used here. */
template<typename UserType>
using NameList = std::list<std::string>;
TemplateUserTypeMapNoVoid<NameList> _nameListMap;
/** Overall variable name list, used to detect name collisions */
std::list<std::string> _overallVariableList;
size_t _historyLength;
bool _enbaleTimeStamps;
friend struct AccessorAttacher;
};
}} // namespace ChimeraTK::history