DeviceModule.h

// SPDX-FileCopyrightText: Deutsches Elektronen-Synchrotron DESY, MSK, ChimeraTK Project <chimeratk-support@desy.de>
// SPDX-License-Identifier: LGPL-3.0-or-later
#pragma once

#include "ControlSystemModule.h"
#include "Module.h"
#include "ModuleGroup.h"
#include "RecoveryHelper.h"
#include "ScalarAccessor.h"
#include "StatusAccessor.h"
#include "StatusWithMessage.h"
#include "VariableGroup.h"
#include "VariableNetworkNode.h"
#include "VirtualModule.h"

#include <ChimeraTK/Device.h>
#include <ChimeraTK/ForwardDeclarations.h>
#include <ChimeraTK/RegisterPath.h>

#include <boost/thread/latch.hpp>

namespace ChimeraTK {
  class Application;
  class DeviceModule;
  namespace history {
    struct ServerHistory;
  } // namespace history

  namespace detail {
    struct CircularDependencyDetector;
  } // namespace detail

  /*********************************************************************************************************************/

  namespace detail {
    struct DeviceModuleProxy : Module {
      DeviceModuleProxy(const DeviceModule& owner, const std::string& registerNamePrefix);

      DeviceModuleProxy(DeviceModuleProxy&& other);

      DeviceModuleProxy() = default;

      VariableNetworkNode operator()(const std::string& registerName, UpdateMode mode,
          const std::type_info& valueType = typeid(AnyType), size_t nElements = 0) const;

      VariableNetworkNode operator()(const std::string& registerName, const std::type_info& valueType,
          size_t nElements = 0, UpdateMode mode = UpdateMode::poll) const;

      VariableNetworkNode operator()(const std::string& variableName) const override;
      Module& operator[](const std::string& moduleName) const override;

      const Module& virtualise() const override;

      void connectTo(const Module& target, VariableNetworkNode trigger = {}) const override;

      ModuleType getModuleType() const override { return ModuleType::Device; }

      DeviceModuleProxy& operator=(DeviceModuleProxy&& other);

     private:
      friend class ChimeraTK::DeviceModule;
      const DeviceModule* _myowner;
      std::string _registerNamePrefix;
    };
  } // namespace detail

  /*********************************************************************************************************************/

  /** Implements access to a ChimeraTK::Device.
   */
  class DeviceModule : public Module {
   public:
    /**
     *  Create (non-connecting) DeviceModule
     *
     *  The device represented by this DeviceModule is identified by either the device alias found in the DMAP file or
     *  directly a CDD.
     *
     *  A callback function to initialise the device can be registered as an optional argument (see
     *  addInitialisationHandler() for more information).
     *
     *  Connecting the device to other modules is up to the user, hence using this class directly is discouraged in
     *  new applications. Instead use the ConnectingDeviceModule.
     */
    DeviceModule(Application* application, const std::string& deviceAliasOrCDD,
        std::function<void(DeviceModule*)> initialisationHandler = nullptr);

    /** Destructor */
    virtual ~DeviceModule();

    /** Move operation with the move constructor */
    DeviceModule(DeviceModule&& other) { operator=(std::move(other)); }

    /** Move assignment */
    DeviceModule& operator=(DeviceModule&& other);

    /** The subscript operator returns a VariableNetworkNode which can be used in
     * the Application::initialise()
     *  function to connect the register with another variable. */
    VariableNetworkNode operator()(const std::string& registerName, UpdateMode mode,
        const std::type_info& valueType = typeid(AnyType), size_t nElements = 0) const;

    VariableNetworkNode operator()(const std::string& registerName, const std::type_info& valueType,
        size_t nElements = 0, UpdateMode mode = UpdateMode::poll) const;

    VariableNetworkNode operator()(const std::string& variableName) const override;

    Module& operator[](const std::string& moduleName) const override;

    const Module& virtualise() const override;

    void connectTo(const Module& target, VariableNetworkNode trigger = {}) const override;

    ModuleType getModuleType() const override { return ModuleType::Device; }

    /** Use this function to report an exception. It should be called whenever a
     * ChimeraTK::runtime_error has been caught when trying to interact with this
     * device. It is primarily used by the ExceptionHandlingDecorator, but also user modules
     * can report exception and trigger the recovery mechanism like this. */
    void reportException(std::string errMsg);

    void prepare() override;

    void run() override;

    void terminate() override;

    VersionNumber getCurrentVersionNumber() const override { return currentVersionNumber; }

    void setCurrentVersionNumber(VersionNumber versionNumber) override;

    VersionNumber currentVersionNumber{nullptr};

    /** This function connects DeviceError VariableGroup to ControlSystem*/
    void defineConnections() override;

    mutable Device device;

    DataValidity getDataValidity() const override { return DataValidity::ok; }

    void incrementDataFaultCounter() override;

    void decrementDataFaultCounter() override;

    /** Add initialisation handlers to the device.
     *
     *  Initialisation handlers are called after the device has been opened, or after the device is recovering
     *  from an error (i.e. an accessor has thrown an exception and Device::isFunctional() returns true afterwards).
     *
     *  You can add multiple handlers. They are executed in the sequence in which they are registered. If a handler
     *  has been registered in the constructor, it is called first.
     *
     *  The handler function is called from the DeviceModule thread (not from the thread with the accessor that threw
     * the exception). It is handed a pointer to the instance of the DeviceModule where the handler was registered. The
     * handler function may throw a ChimeraTK::runtime_error, so you don't have to catch errors thrown when accessing
     * the Device inside the handler. After a handler has thrown an exception, the following handlers are not called.
     * The DeviceModule will wait until the Device reports isFunctional() again and retry. The exception is reported to
     * other modules and the control system.
     *
     *  Notice: Especially in network based devices which do not hold a permanent connection, it is not always possible
     *  to predict whether the next read()/write() will succeed. In this case the Device will always report
     * isFunctional() and one just has to retry. In this case the DeviceModule will start the initialisation sequence
     * every 500 ms.
     */
    void addInitialisationHandler(std::function<void(DeviceModule*)> initialisationHandler);

    /** A trigger that indicated that the device just became available again an error (in contrast to the
     *  error status which is also send when the device goes away).
     *  The output is public so your module can connect to it and trigger re-sending of variables that
     *  have to be send to the device again. e.g. after this has re-booted.
     *  Attention: It is not send the first time the device is being opened. In this case the normal startup
     *  mechanism takes care that the data is send.
     *  Like the deviceError, it is automatically published to the control systen to ensure that there is at least one
     *  consumer connected.
     */
    ScalarOutput<int> deviceBecameFunctional{
        this, "deviceBecameFunctional", "", ""}; // should be changed to data type void

    /** Add a TransferElement to the list DeviceModule::writeRecoveryOpen. This list will be written during a recovery,
     * after the constant accessors DeviceModule::writeAfterOpen are written. This is locked by a unique_lock.
     * You can get a shared_lock with getRecoverySharedLock(). */
    void addRecoveryAccessor(boost::shared_ptr<RecoveryHelper> recoveryAccessor);

    /** Each call to this function gives a unique number. It is atomically increased with each call.
     *  The smallest valid write order is 1.
     */
    uint64_t writeOrder();

    /** Returns a shared lock for the DeviceModule::recoveryMutex. This locks writing
     * the list DeviceModule::writeRecoveryOpen, during a recovery.*/
    boost::shared_lock<boost::shared_mutex> getRecoverySharedLock();

    /**
     *  Wait for initial values coming from the device. This function will block until the device is opened and
     *  initialised, and initial values can be read from it.
     */
    void waitForInitialValues();

    std::list<EntityOwner*> getInputModulesRecursively(std::list<EntityOwner*> startList) override;

    size_t getCircularNetworkHash() override;

    /**
     *  Return associated device alias resp. URI
     */
    std::string getDeviceAliasOrURI() const { return deviceAliasOrURI; }

   protected:
    // populate virtualisedModuleFromCatalog based on the information in the
    // device's catalogue
    VirtualModule& virtualiseFromCatalog() const;

    mutable VirtualModule virtualisedModuleFromCatalog{"INVALID", "", ModuleType::Invalid};
    mutable bool virtualisedModuleFromCatalog_isValid{false};

    std::string deviceAliasOrURI;
    ChimeraTK::RegisterPath registerNamePrefix;

    // List of proxies accessed through the operator[]. This is mutable since
    // it is little more than a cache and thus does not change the logical state
    // of this module
    mutable std::map<std::string, detail::DeviceModuleProxy> proxies;

    // create or return a proxy for a submodule (full hierarchy)
    detail::DeviceModuleProxy& getProxy(const std::string& fullName) const;

    /** A  VariableGroup for exception status and message. It can be protected, as
     * it is automatically connected to the control system in
     * DeviceModule::defineConnections() */
    StatusWithMessage deviceError{this, "DeviceError/status", "Error status of the device"};

    /** The thread waiting for reportException(). It runs handleException() */
    boost::thread moduleThread;

    /** Queue used for communication between reportException() and the
     * moduleThread. */
    cppext::future_queue<std::string> errorQueue{5};

    /** Mutex to protect deviceHasError.
        Attention: In testable mode this mutex must only be locked when holding the testable mode mutex!*/
    boost::shared_mutex errorMutex;

    /** Version number of the last exception. Only access under the error mutex. */
    VersionNumber exceptionVersionNumber = {};
    // Intentionally not initialised with nullptr. It is propagated as long as the device is not successfully opened.

    /** The error flag whether the device is functional. protected by the errorMutex. */
    bool deviceHasError{true};

    /** Use this function to read the exception version number. It is locking the variable mutex correctly for you. */
    VersionNumber getExceptionVersionNumber();

    /** This functions tries to open the device and set the deviceError. Once done it notifies the waiting thread(s).
     *  The function is running an endless loop inside its own thread (moduleThread). */
    void handleException();

    /** List of TransferElements to be written after the device has been recovered.
     *  See function addRecoveryAccessor() for details.*/
    std::list<boost::shared_ptr<RecoveryHelper>> recoveryHelpers;

    Application* owner{nullptr};

    mutable bool deviceIsInitialized = false;

    /* The list of initialisation handler callback functions */
    std::list<std::function<void(DeviceModule*)>> initialisationHandlers;

    /** Mutex for writing the DeviceModule::writeRecoveryOpen.*/
    boost::shared_mutex recoveryMutex;

    /** Latch to halt accessors until initial values can be received.
     *  Must be a latch and not a mutex as it is locked in a different thread than unlocked. */
    bool isHoldingInitialValueLatch{true};
    boost::latch initialValueLatch{1};

    std::atomic<int64_t> synchronousTransferCounter{0};
    std::atomic<uint64_t> writeOrderCounter{0};

    std::list<RegisterPath> writeRegisterPaths;
    std::list<RegisterPath> readRegisterPaths;

    friend class Application;
    // Access to virtualiseFromCatalog() is needed by ServerHistory
    friend struct history::ServerHistory;
    // Access to virtualiseFromCatalog() is needed by MicroDAQ
    template<typename TRIGGERTYPE>
    friend class MicroDAQ;
    friend struct detail::DeviceModuleProxy;

    template<typename T>
    friend class ExceptionHandlingDecorator;

    friend class ConnectingDeviceModule;

    friend struct StatusAggregator;

    friend struct detail::CircularDependencyDetector;
  };

  /*********************************************************************************************************************/

  /**
   */
  class ConnectingDeviceModule : public ModuleGroup {
   public:
    /**
     *  Create ConnectingDeviceModule which is connected to the control system at the path of the owner.
     *
     *  deviceAliasOrURI: identifies the device by either the alias found in the DMAP file or directly a CDD.
     *
     *  triggerPath specifies a control system variable which is used as a trigger where needed.
     *
     *  initialisationHandler specifies a callback function to initialise the device (optional, default is none).
     *
     *  pathInDevice specifies a module in the device register hierarchy which should be used and connected to the
     *  control system (optional, default is "/" which connects the entire device).
     *
     *  Note about typical usage: A DeviceModule constructed with this constructer is often owned by the ModuleGroup
     *  which is using this device. The device should be a logical name mapped device so the variable hierarchy of the
     *  ModuleGroup and the Device can be matched. The logical device may be subdivided into several parts, e.g. if
     *  different parts of the device are used by independent ModuleGroups, or if different triggers are required. This
     *  is possible by use of the pathInDevice prefix. To avoid the creation of multiple DeviceBackends for the same
     *  device (which may not even be possible for some transport protocols) make sure that the device CDD is identical
     *  for all instances (the alias name does not matter, so multiple DMAP file entires pointing to the same device
     *  are possible if needed).
     *
     *  Keep in mind that mulitple DeviceModules will perform independent and asynchronous recovery procedures after
     *  an exception, even when pointing to the same device.
     */
    ConnectingDeviceModule(EntityOwner* owner, const std::string& deviceAliasOrCDD, const std::string& triggerPath = {},
        std::function<void(DeviceModule*)> initialisationHandler = nullptr, const std::string& pathInDevice = "/");

    /**
     *  Return the underlying DeviceModule
     */
    DeviceModule& getDeviceModule() { return *_dm; }

   protected:
    void defineConnections() override;

    std::string pathToConnectTo;
    std::string triggerPath;
    std::string pathInDevice;

    /// The DeviceModule represented by this ConnectingDeviceModule
    DeviceModule* _dm;

    /// Initialisation handler to add to the DeviceModule. This must be done only in defineConnections(), as otherwise
    /// the initialisation handler would need to be removed in the destructor which is not possible. Not doing so at
    /// least creates issues with move operations, especially if the initialisation handler points to a moved object.
    std::function<void(DeviceModule*)> _initHandler;

    /// Shared pointer holding the DeviceModule if (and only if) this ConnectingDeviceModule owns the DeviceModule
    boost::shared_ptr<DeviceModule> _dmHolder;
  };

} /* namespace ChimeraTK */