BackendRegisterCatalogue.h

Go to the documentation of this file.

// SPDX-FileCopyrightText: Deutsches Elektronen-Synchrotron DESY, MSK, ChimeraTK Project <chimeratk-support@desy.de>
// SPDX-License-Identifier: LGPL-3.0-or-later
#pragma once
 
#include "async/DataConsistencyRealm.h"
#include "RegisterCatalogue.h"
 
#include <boost/make_shared.hpp>
#include <boost/range/adaptors.hpp>
 
namespace ChimeraTK {
 
  template<typename BackendRegisterInfo>
  class const_BackendRegisterCatalogueImplIterator;
 
  template<typename BackendRegisterInfo>
  class BackendRegisterCatalogueImplIterator;
 
  /********************************************************************************************************************/
  /* Register catalogue container class definitions ******************************************************************/
  /********************************************************************************************************************/
 
  class BackendRegisterCatalogueBase {
   public:
    BackendRegisterCatalogueBase() = default;
 
    BackendRegisterCatalogueBase(BackendRegisterCatalogueBase&& other) = default;
 
    BackendRegisterCatalogueBase& operator=(BackendRegisterCatalogueBase&& other) = default;
 
    virtual ~BackendRegisterCatalogueBase() = default;
 
    // Copy constructor/assignment is deleted. It could be implemented (need to take care of pointers in
    // insertionOrderedCatalogue), but currently there is no need for this and hence it is not done.
    BackendRegisterCatalogueBase(const BackendRegisterCatalogueBase& other) = delete;
    BackendRegisterCatalogueBase& operator=(const BackendRegisterCatalogueBase& other) = delete;
 
    [[nodiscard]] virtual RegisterInfo getRegister(const RegisterPath& registerPathName) const = 0;
 
    [[nodiscard]] virtual bool hasRegister(const RegisterPath& registerPathName) const = 0;
 
    [[nodiscard]] virtual size_t getNumberOfRegisters() const = 0;
 
    [[nodiscard]] virtual std::unique_ptr<const_RegisterCatalogueImplIterator> getConstIteratorBegin() const = 0;
 
    [[nodiscard]] virtual std::unique_ptr<const_RegisterCatalogueImplIterator> getConstIteratorEnd() const = 0;
 
    [[nodiscard]] virtual std::unique_ptr<BackendRegisterCatalogueBase> clone() const = 0;
 
    [[nodiscard]] virtual std::shared_ptr<async::DataConsistencyRealm> getDataConsistencyRealm(
        const std::vector<size_t>& qualifiedAsyncDomainId) const;
 
    [[nodiscard]] virtual RegisterPath getDataConsistencyKeyRegisterPath(
        const std::vector<size_t>& qualifiedAsyncDomainId) const;
 
    [[nodiscard]] virtual HiddenRange hiddenRegisters() const = 0;
  };
 
  /********************************************************************************************************************/
 
  template<typename BackendRegisterInfo>
  class BackendRegisterCatalogue : public BackendRegisterCatalogueBase {
   public:
    [[nodiscard]] virtual BackendRegisterInfo getBackendRegister(const RegisterPath& registerPathName) const;
 
    [[nodiscard]] bool hasRegister(const RegisterPath& registerPathName) const override;
 
    [[nodiscard]] RegisterInfo getRegister(const RegisterPath& registerPathName) const final;
 
    // Return the number of registers in the catalogue, excluding hidden registers.
    [[nodiscard]] size_t getNumberOfRegisters() const override;
 
    [[nodiscard]] std::unique_ptr<const_RegisterCatalogueImplIterator> getConstIteratorBegin() const override;
 
    [[nodiscard]] std::unique_ptr<const_RegisterCatalogueImplIterator> getConstIteratorEnd() const override;
 
    [[nodiscard]] std::unique_ptr<BackendRegisterCatalogueBase> clone() const override;
 
    void addRegister(const BackendRegisterInfo& registerInfo);
 
    void removeRegister(const RegisterPath& name);
 
    void modifyRegister(const BackendRegisterInfo& registerInfo);
 
    [[nodiscard]] BackendRegisterCatalogueImplIterator<BackendRegisterInfo> begin() {
      return BackendRegisterCatalogueImplIterator<BackendRegisterInfo>{_iteratedCatalogue.begin()};
    }
 
    [[nodiscard]] BackendRegisterCatalogueImplIterator<BackendRegisterInfo> end() {
      return BackendRegisterCatalogueImplIterator<BackendRegisterInfo>{_iteratedCatalogue.end()};
    }
 
    [[nodiscard]] const_BackendRegisterCatalogueImplIterator<BackendRegisterInfo> begin() const {
      return const_BackendRegisterCatalogueImplIterator<BackendRegisterInfo>{_iteratedCatalogue.begin()};
    }
 
    [[nodiscard]] const_BackendRegisterCatalogueImplIterator<BackendRegisterInfo> end() const {
      return const_BackendRegisterCatalogueImplIterator<BackendRegisterInfo>{_iteratedCatalogue.end()};
    }
 
    [[nodiscard]] const_BackendRegisterCatalogueImplIterator<BackendRegisterInfo> cbegin() const {
      return const_BackendRegisterCatalogueImplIterator<BackendRegisterInfo>{_iteratedCatalogue.begin()};
    }
 
    [[nodiscard]] const_BackendRegisterCatalogueImplIterator<BackendRegisterInfo> cend() const {
      return const_BackendRegisterCatalogueImplIterator<BackendRegisterInfo>{_iteratedCatalogue.end()};
    }
 
    [[nodiscard]] HiddenRange hiddenRegisters() const override {
      auto filtered = _catalogue | boost::adaptors::filtered([](auto const& kv) { return kv.second.isHidden(); }) |
          boost::adaptors::transformed([](const auto& kv) -> const BackendRegisterInfoBase& { return kv.second; });
 
      return HiddenRange(filtered.begin(), filtered.end());
    }
 
   protected:
    void fillFromThis(BackendRegisterCatalogue<BackendRegisterInfo>* target) const;
 
   private:
    // Always access the catalogue through the member functions. Modifications need special care to keep the two
    // containers synchronised, hence these members are made private.
    // The map _catalogue should contain all registers, including "hidden" ones. An exception might be "dynamic"
    // registers which only exist when someone is looking for them (potentially with time-dependent behaviour). Also
    // some backends might still implement "hidden" registers without filling them here.
    std::map<RegisterPath, BackendRegisterInfo> _catalogue;
 
    // The _iteratedCatalogue is used to the present the user the registers in a nice way, excluding "hidden" registers.
    // It will be ordered by insertion (call to addRegister()), so e.g. the ordering in the map file can be kept.
    std::vector<BackendRegisterInfo*> _iteratedCatalogue;
  };
 
  /********************************************************************************************************************/
  /* Iterator class definitions **************************************************************************************/
  /********************************************************************************************************************/
 
  template<typename BackendRegisterInfo>
  class const_BackendRegisterCatalogueImplIterator : public const_RegisterCatalogueImplIterator {
   public:
    explicit const_BackendRegisterCatalogueImplIterator(typename std::vector<BackendRegisterInfo*>::const_iterator it);
 
    void increment() override;
 
    void decrement() override;
 
    const BackendRegisterInfoBase* get() override;
 
    [[nodiscard]] bool isEqual(
        const std::unique_ptr<const_RegisterCatalogueImplIterator>& rightHandSide) const override;
 
    [[nodiscard]] std::unique_ptr<const_RegisterCatalogueImplIterator> clone() const override;
 
    const_BackendRegisterCatalogueImplIterator& operator++();
 
    const_BackendRegisterCatalogueImplIterator operator++(int);
 
    const_BackendRegisterCatalogueImplIterator& operator--();
 
    const_BackendRegisterCatalogueImplIterator operator--(int);
 
    const BackendRegisterInfo& operator*() const;
 
    const BackendRegisterInfo* operator->() const;
 
    explicit operator RegisterCatalogue::const_iterator() const;
 
    bool operator==(const const_BackendRegisterCatalogueImplIterator& rightHandSide) const;
 
    bool operator!=(const const_BackendRegisterCatalogueImplIterator& rightHandSide) const;
 
   protected:
    typename std::vector<BackendRegisterInfo*>::const_iterator theIterator;
  };
 
  /********************************************************************************************************************/
 
  template<typename BackendRegisterInfo>
  class BackendRegisterCatalogueImplIterator {
   public:
    BackendRegisterCatalogueImplIterator() = default;
 
    explicit BackendRegisterCatalogueImplIterator(typename std::vector<BackendRegisterInfo*>::iterator theIterator_);
 
    BackendRegisterCatalogueImplIterator& operator++();
 
    BackendRegisterCatalogueImplIterator operator++(int);
 
    BackendRegisterCatalogueImplIterator& operator--();
 
    BackendRegisterCatalogueImplIterator operator--(int);
 
    BackendRegisterInfo& operator*() const;
 
    BackendRegisterInfo* operator->() const;
 
    explicit operator RegisterCatalogue::const_iterator() const;
 
    bool operator==(const BackendRegisterCatalogueImplIterator& rightHandSide) const;
 
    bool operator!=(const BackendRegisterCatalogueImplIterator& rightHandSide) const;
 
   protected:
    typename std::vector<BackendRegisterInfo*>::iterator theIterator;
  };
 
  /********************************************************************************************************************/
  /********************************************************************************************************************/
 
  /********************************************************************************************************************/
  /* Register catalogue container implementations ********************************************************************/
  /********************************************************************************************************************/
 
  template<typename BackendRegisterInfo>
  RegisterInfo BackendRegisterCatalogue<BackendRegisterInfo>::getRegister(const RegisterPath& name) const {
    return RegisterInfo(std::make_unique<BackendRegisterInfo>(getBackendRegister(name)));
  }
 
  /********************************************************************************************************************/
 
  template<typename BackendRegisterInfo>
  BackendRegisterInfo BackendRegisterCatalogue<BackendRegisterInfo>::getBackendRegister(
      const RegisterPath& name) const {
    try {
      return _catalogue.at(name);
    }
    catch(std::out_of_range&) {
      throw ChimeraTK::logic_error("BackendRegisterCatalogue::getRegister(): Register '" + name + "' does not exist.");
    }
  }
 
  /********************************************************************************************************************/
 
  template<typename BackendRegisterInfo>
  bool BackendRegisterCatalogue<BackendRegisterInfo>::hasRegister(const RegisterPath& registerPathName) const {
    return _catalogue.find(registerPathName) != _catalogue.end();
  }
 
  /********************************************************************************************************************/
 
  template<typename BackendRegisterInfo>
  size_t BackendRegisterCatalogue<BackendRegisterInfo>::getNumberOfRegisters() const {
    return _iteratedCatalogue.size();
  }
 
  /********************************************************************************************************************/
 
  template<typename BackendRegisterInfo>
  std::unique_ptr<const_RegisterCatalogueImplIterator> BackendRegisterCatalogue<
      BackendRegisterInfo>::getConstIteratorBegin() const {
    auto it =
        std::make_unique<const_BackendRegisterCatalogueImplIterator<BackendRegisterInfo>>(_iteratedCatalogue.cbegin());
    return it;
  }
 
  /********************************************************************************************************************/
 
  template<typename BackendRegisterInfo>
  std::unique_ptr<const_RegisterCatalogueImplIterator> BackendRegisterCatalogue<
      BackendRegisterInfo>::getConstIteratorEnd() const {
    auto it =
        std::make_unique<const_BackendRegisterCatalogueImplIterator<BackendRegisterInfo>>(_iteratedCatalogue.cend());
    return it;
  }
 
  /********************************************************************************************************************/
 
  template<typename BackendRegisterInfo>
  std::unique_ptr<BackendRegisterCatalogueBase> BackendRegisterCatalogue<BackendRegisterInfo>::clone() const {
    // FIXME: Change BackendRegisterCatalogue to CRTP, i.e. it has the DERIVED class as template parameter.
    // Like this the correct catalogue type is already created here and inheriting backends can call this clone,
    // then cast to the actual type and fill the rest of it's properties. Would get rid of the "fillFromThis()"
    // workaround and safe clone() implementations in case no data members are added.
 
    // Create a new instance of a BackendRegisterCatalogue with the correct type.
    // Inheriting backends will create the derrived type here.
    std::unique_ptr<BackendRegisterCatalogueBase> c = std::make_unique<BackendRegisterCatalogue<BackendRegisterInfo>>();
    // Fill the contents of the BackendRegisterCatalogue base class into the target c. This is accessing the
    // private variables and ensures consistency.
    fillFromThis(dynamic_cast<BackendRegisterCatalogue<BackendRegisterInfo>*>(c.get()));
    // Derived backends will copy/clone their additional data members here, before
    // returning the unique_ptr. The compiler will return it via copy elision.
    return c;
  }
 
  /********************************************************************************************************************/
 
  template<typename BackendRegisterInfo>
  void BackendRegisterCatalogue<BackendRegisterInfo>::fillFromThis(
      BackendRegisterCatalogue<BackendRegisterInfo>* target) const {
    // copy all registers, including hidden registers
    for(auto& p : _catalogue) {
      target->_catalogue[p.first] = getBackendRegister(p.first);
    }
    // create insertion-order-correct vector of non-hidden registers, pointing to the new RegisterInfo copies
    for(auto& ptr : _iteratedCatalogue) {
      target->_iteratedCatalogue.push_back(&target->_catalogue[ptr->getRegisterName()]);
    }
  }
 
  /********************************************************************************************************************/
 
  template<typename BackendRegisterInfo>
  void BackendRegisterCatalogue<BackendRegisterInfo>::addRegister(const BackendRegisterInfo& registerInfo) {
    if(hasRegister(registerInfo.getRegisterName())) {
      throw ChimeraTK::logic_error("BackendRegisterCatalogue::addRegister(): Register with the name " +
          registerInfo.getRegisterName() + " already exists!");
    }
    _catalogue[registerInfo.getRegisterName()] = registerInfo;
    if(!registerInfo.isHidden()) {
      _iteratedCatalogue.push_back(&_catalogue[registerInfo.getRegisterName()]);
    }
  }
 
  /********************************************************************************************************************/
 
  template<typename BackendRegisterInfo>
  void BackendRegisterCatalogue<BackendRegisterInfo>::removeRegister(const RegisterPath& name) {
    // check existence
    if(!hasRegister(name)) {
      throw ChimeraTK::logic_error(
          "BackendRegisterCatalogue::removeRegister(): Register '" + name + "' does not exist.");
    }
 
    // remove from insertion-ordered vector
    auto it = std::find_if(
        _iteratedCatalogue.begin(), _iteratedCatalogue.end(), [&](auto reg) { return reg->getRegisterName() == name; });
    assert(it != _iteratedCatalogue.end());
    _iteratedCatalogue.erase(it);
 
    // remove from catalogue map
    auto removed = _catalogue.erase(name);
    assert(removed == 1);
  }
 
  /********************************************************************************************************************/
 
  template<typename BackendRegisterInfo>
  void BackendRegisterCatalogue<BackendRegisterInfo>::modifyRegister(const BackendRegisterInfo& registerInfo) {
    if(!hasRegister(registerInfo.getRegisterName())) {
      throw ChimeraTK::logic_error("BackendRegisterCatalogue::modifyRegister(): Register '" +
          registerInfo.getRegisterName() + "' cannot be modified because it does not exist!");
    }
    _catalogue[registerInfo.getRegisterName()] = registerInfo;
    // We don't have to touch the insertionOrderedCatalogue because is stores references, and this has not changed.
  }
 
  /********************************************************************************************************************/
  /* Iterator implementations ****************************************************************************************/
  /********************************************************************************************************************/
 
  template<typename BackendRegisterInfo>
  const_BackendRegisterCatalogueImplIterator<BackendRegisterInfo>::const_BackendRegisterCatalogueImplIterator(
      typename std::vector<BackendRegisterInfo*>::const_iterator it)
  : theIterator(it) {}
 
  /********************************************************************************************************************/
 
  template<typename BackendRegisterInfo>
  void const_BackendRegisterCatalogueImplIterator<BackendRegisterInfo>::increment() {
    ++theIterator;
  }
 
  /********************************************************************************************************************/
 
  template<typename BackendRegisterInfo>
  void const_BackendRegisterCatalogueImplIterator<BackendRegisterInfo>::decrement() {
    --theIterator;
  }
 
  /********************************************************************************************************************/
 
  template<typename BackendRegisterInfo>
  const BackendRegisterInfoBase* const_BackendRegisterCatalogueImplIterator<BackendRegisterInfo>::get() {
    return *theIterator;
  }
 
  /********************************************************************************************************************/
 
  template<typename BackendRegisterInfo>
  bool const_BackendRegisterCatalogueImplIterator<BackendRegisterInfo>::isEqual(
      const std::unique_ptr<const_RegisterCatalogueImplIterator>& rightHandSide) const {
    auto rhs_casted = dynamic_cast<const_BackendRegisterCatalogueImplIterator*>(rightHandSide.get());
    return rhs_casted && rhs_casted->theIterator == theIterator;
  }
 
  /********************************************************************************************************************/
 
  template<typename BackendRegisterInfo>
  std::unique_ptr<const_RegisterCatalogueImplIterator> const_BackendRegisterCatalogueImplIterator<
      BackendRegisterInfo>::clone() const {
    return {std::make_unique<const_BackendRegisterCatalogueImplIterator>(*this)};
  }
 
  /********************************************************************************************************************/
 
  template<typename BackendRegisterInfo>
  const_BackendRegisterCatalogueImplIterator<BackendRegisterInfo>& const_BackendRegisterCatalogueImplIterator<
      BackendRegisterInfo>::operator++() {
    ++theIterator;
    return *this;
  }
 
  /********************************************************************************************************************/
 
  template<typename BackendRegisterInfo>
  const_BackendRegisterCatalogueImplIterator<BackendRegisterInfo> const_BackendRegisterCatalogueImplIterator<
      BackendRegisterInfo>::operator++(int) {
    BackendRegisterCatalogueImplIterator<BackendRegisterInfo> temp(*this);
    ++theIterator;
    return temp;
  }
 
  /********************************************************************************************************************/
 
  template<typename BackendRegisterInfo>
  const_BackendRegisterCatalogueImplIterator<BackendRegisterInfo>& const_BackendRegisterCatalogueImplIterator<
      BackendRegisterInfo>::operator--() {
    --theIterator;
    return *this;
  }
 
  /********************************************************************************************************************/
 
  template<typename BackendRegisterInfo>
  const_BackendRegisterCatalogueImplIterator<BackendRegisterInfo> const_BackendRegisterCatalogueImplIterator<
      BackendRegisterInfo>::operator--(int) {
    BackendRegisterCatalogueImplIterator<BackendRegisterInfo> temp(*this);
    --theIterator;
    return temp;
  }
 
  /********************************************************************************************************************/
 
  template<typename BackendRegisterInfo>
  const BackendRegisterInfo& const_BackendRegisterCatalogueImplIterator<BackendRegisterInfo>::operator*() const {
    return *(*theIterator);
  }
 
  /********************************************************************************************************************/
 
  template<typename BackendRegisterInfo>
  const BackendRegisterInfo* const_BackendRegisterCatalogueImplIterator<BackendRegisterInfo>::operator->() const {
    return *theIterator;
  }
 
  /********************************************************************************************************************/
 
  template<typename BackendRegisterInfo>
  bool const_BackendRegisterCatalogueImplIterator<BackendRegisterInfo>::operator==(
      const const_BackendRegisterCatalogueImplIterator& rightHandSide) const {
    return rightHandSide.theIterator == theIterator;
  }
 
  /********************************************************************************************************************/
 
  template<typename BackendRegisterInfo>
  bool const_BackendRegisterCatalogueImplIterator<BackendRegisterInfo>::operator!=(
      const const_BackendRegisterCatalogueImplIterator& rightHandSide) const {
    return rightHandSide.theIterator != theIterator;
  }
 
  /********************************************************************************************************************/
  /********************************************************************************************************************/
 
  template<typename BackendRegisterInfo>
  BackendRegisterCatalogueImplIterator<BackendRegisterInfo>::BackendRegisterCatalogueImplIterator(
      typename std::vector<BackendRegisterInfo*>::iterator theIterator_)
  : theIterator(theIterator_) {}
 
  /********************************************************************************************************************/
 
  template<typename BackendRegisterInfo>
  BackendRegisterCatalogueImplIterator<BackendRegisterInfo>& BackendRegisterCatalogueImplIterator<
      BackendRegisterInfo>::operator++() {
    ++theIterator;
    return *this;
  }
 
  /********************************************************************************************************************/
 
  template<typename BackendRegisterInfo>
  BackendRegisterCatalogueImplIterator<BackendRegisterInfo> BackendRegisterCatalogueImplIterator<
      BackendRegisterInfo>::operator++(int) {
    BackendRegisterCatalogueImplIterator<BackendRegisterInfo> temp(*this);
    ++theIterator;
    return temp;
  }
 
  /********************************************************************************************************************/
 
  template<typename BackendRegisterInfo>
  BackendRegisterCatalogueImplIterator<BackendRegisterInfo>& BackendRegisterCatalogueImplIterator<
      BackendRegisterInfo>::operator--() {
    --theIterator;
    return *this;
  }
 
  /********************************************************************************************************************/
 
  template<typename BackendRegisterInfo>
  BackendRegisterCatalogueImplIterator<BackendRegisterInfo> BackendRegisterCatalogueImplIterator<
      BackendRegisterInfo>::operator--(int) {
    BackendRegisterCatalogueImplIterator<BackendRegisterInfo> temp(*this);
    --theIterator;
    return temp;
  }
 
  /********************************************************************************************************************/
 
  template<typename BackendRegisterInfo>
  BackendRegisterInfo& BackendRegisterCatalogueImplIterator<BackendRegisterInfo>::operator*() const {
    return *(*theIterator);
  }
 
  /********************************************************************************************************************/
 
  template<typename BackendRegisterInfo>
  BackendRegisterInfo* BackendRegisterCatalogueImplIterator<BackendRegisterInfo>::operator->() const {
    return *theIterator;
  }
 
  /********************************************************************************************************************/
 
  template<typename BackendRegisterInfo>
  BackendRegisterCatalogueImplIterator<BackendRegisterInfo>::operator RegisterCatalogue::const_iterator() const {
    return RegisterCatalogue::const_iterator{
        boost::make_shared<const_BackendRegisterCatalogueImplIterator<BackendRegisterInfo>>(theIterator)};
  }
 
  /********************************************************************************************************************/
 
  template<typename BackendRegisterInfo>
  bool BackendRegisterCatalogueImplIterator<BackendRegisterInfo>::operator==(
      const BackendRegisterCatalogueImplIterator& rightHandSide) const {
    return rightHandSide.theIterator == theIterator;
  }
 
  /********************************************************************************************************************/
 
  template<typename BackendRegisterInfo>
  bool BackendRegisterCatalogueImplIterator<BackendRegisterInfo>::operator!=(
      const BackendRegisterCatalogueImplIterator& rightHandSide) const {
    return rightHandSide.theIterator != theIterator;
  }
 
  /********************************************************************************************************************/
 
} // namespace ChimeraTK