UserInputValidator.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 "AccessorConcepts.h"
#include "ArrayAccessor.h"
#include "ScalarAccessor.h"
 
#include <boost/circular_buffer.hpp>
#include <boost/fusion/container.hpp>
 
namespace ChimeraTK {
 
  // Forward-declarations
  class Module;
 
  struct UserInputValidator {
    template<typename... ACCESSORTYPES>
    void add(
        const std::string& errorMessage, const std::function<bool(void)>& isValidFunction, ACCESSORTYPES&... accessors);
 
    template<std::ranges::input_range R>
      requires push_input<std::ranges::range_value_t<R>>
    void add(const std::string& errorMessage, const std::function<bool(void)>& isValidFunction, const R& accessors);
 
    template<typename UserType, template<typename> typename Accessor>
    void setFallback(Accessor<UserType>& accessor, UserType value);
 
    template<typename UserType, template<typename> typename Accessor>
    void setFallback(Accessor<UserType>& accessor, std::vector<UserType> value);
 
    void setErrorFunction(const std::function<void(const std::string&)>& errorFunction);
 
    bool validate(const ChimeraTK::TransferElementID& change);
 
    bool validateAll();
 
    class AccessorHook {
     public:
      virtual ~AccessorHook() = default;
 
      virtual void onAddValidator([[maybe_unused]] UserInputValidator& validator) {};
 
      virtual void onReject() {};
 
      virtual void onAccept() {};
    };
 
   protected:
    static constexpr std::string_view tagValidatedVariable{"__UserInputValidator"};
 
    // Helper function to set up queue lengths of valid values. Will be called automatically for the first call to
    // validate
    void finalise();
 
    // Helper function for internal book keeping of accessors (prevent unnecessary overwrite of map entry, which might
    // result in loss of fallback values).
    template<typename UserType, template<typename> typename Accessor>
    void addAccessorIfNeeded(Accessor<UserType>& accessor);
 
    // Type-independent base class representing a variable passed at least once to add() or setFallback().
    struct VariableBase {
      enum class RejectionType { downstream, self };
      virtual ~VariableBase() = default;
      virtual void reject(RejectionType type) = 0;
      virtual void accept() = 0;
      virtual void setHistorySize(size_t size) = 0;
    };
 
    // Type-dependent representation of all known variables.
    template<typename UserType, template<typename> typename Accessor>
    struct Variable : VariableBase {
      explicit Variable(Accessor<UserType>& accessor);
      Variable() = delete;
      ~Variable() override = default;
 
      // called when validation function returned false
      void reject(RejectionType type) override;
 
      // called when validation function returned true
      void accept() override;
 
      void setHistorySize(size_t) override;
 
      // value to revert to if reject() is called. Updated through accept().
      boost::circular_buffer<std::vector<UserType>> lastAcceptedValue{};
      std::vector<UserType> fallbackValue{UserType()};
 
      // Reference to the accessor.
      Accessor<UserType>& accessor;
 
      std::size_t historyLength{1};
    };
 
    // Represents a validation condition
    struct Validator {
      explicit Validator(std::function<bool(void)> isValidTest, std::string errorMessage);
      Validator() = delete;
      Validator(const Validator& other) = default;
 
      std::function<bool(void)> isValidFunction;
      std::string errorMessage;
    };
 
    Validator* addValidator(const std::function<bool(void)>& isValidFunction, const std::string& errorMessage);
 
    template<typename UserType, template<typename> typename Accessor>
    void registerAccessorWithValidator(Accessor<UserType>& accessor, Validator* validator);
 
    // List of Validator objects
    std::list<Validator> _validators; // must not use std::vector as resizing it invalidates pointers to objects
 
    // Map to find Variable object for given TransferElementID
    std::map<ChimeraTK::TransferElementID, std::shared_ptr<VariableBase>> _variableMap;
 
    // Map to find all Validators associated with the given TransferElementID
    std::map<ChimeraTK::TransferElementID, std::vector<Validator*>> _validatorMap;
 
    // Function to be called for reporting validation errors
    std::function<void(const std::string&)> _errorFunction{
        [](const std::string& m) { logger(Logger::Severity::warning, "UserInputValidator") << m; }};
 
    std::unordered_set<ChimeraTK::TransferElementID> _downstreamInvalidatingReturnChannels;
    size_t _validationDepth{0};
    ApplicationModule* _module{nullptr};
    bool _finalised{false};
 
    friend class PyUserInputValidator;
  };
 
  /********************************************************************************************************************/
 
  template<typename UserType, template<typename> typename Accessor>
  void UserInputValidator::registerAccessorWithValidator(Accessor<UserType>& accessor, Validator* validator) {
    addAccessorIfNeeded(accessor);
    _validatorMap[accessor.getId()].push_back(validator);
  }
 
  /********************************************************************************************************************/
 
  template<typename... ACCESSORTYPES>
  void UserInputValidator::add(
      const std::string& errorMessage, const std::function<bool(void)>& isValidFunction, ACCESSORTYPES&... accessors) {
    boost::fusion::list<ACCESSORTYPES&...> accessorList{accessors...};
    static_assert(boost::fusion::size(accessorList) > 0, "Must specify at least one accessor!");
    assert(isValidFunction != nullptr);
 
    auto* validator = addValidator(isValidFunction, errorMessage);
 
    // create map of accessors to validators, also add accessors/variables to list
    boost::fusion::for_each(accessorList, [&](auto& accessor) { registerAccessorWithValidator(accessor, validator); });
  }
 
  /********************************************************************************************************************/
 
  template<std::ranges::input_range R>
    requires push_input<std::ranges::range_value_t<R>>
  void UserInputValidator::add(
      const std::string& errorMessage, const std::function<bool(void)>& isValidFunction, const R& accessors) {
    assert(isValidFunction != nullptr);
 
    // create validator and store in list
    _validators.emplace_back(isValidFunction, errorMessage);
 
    // create map of accessors to validators, also add accessors/variables to list
    for(auto& accessor : accessors) {
      addAccessorIfNeeded(accessor);
      _validatorMap[accessor.getId()].push_back(&_validators.back());
    };
  }
 
  /********************************************************************************************************************/
 
  template<typename UserType, template<typename> typename Accessor>
  void UserInputValidator::setFallback(Accessor<UserType>& accessor, UserType value) {
    addAccessorIfNeeded(accessor);
    auto pv = std::dynamic_pointer_cast<Variable<UserType, Accessor>>(_variableMap.at(accessor.getId()));
    assert(pv != nullptr);
    if(pv->fallbackValue.size() != 1) {
      throw ChimeraTK::logic_error(
          "UserInputValidator::setFallback() with scalar value called for array-typed accessor '" + accessor.getName() +
          "'.");
    }
    pv->fallbackValue[0] = value;
  }
 
  /********************************************************************************************************************/
 
  template<typename UserType, template<typename> typename Accessor>
  void UserInputValidator::setFallback(Accessor<UserType>& accessor, std::vector<UserType> value) {
    addAccessorIfNeeded(accessor);
    auto pv = std::dynamic_pointer_cast<Variable<UserType, Accessor>>(_variableMap.at(accessor.getId()));
    assert(pv != nullptr);
    if(pv->fallbackValue.size() != value.size()) {
      throw ChimeraTK::logic_error(
          "UserInputValidator::setFallback() with called with mismatching array length for accessor '" +
          accessor.getName() + "'.");
    }
    pv->fallbackValue = value;
  }
  /********************************************************************************************************************/
 
  template<typename UserType, template<typename> typename Accessor>
  void UserInputValidator::addAccessorIfNeeded(Accessor<UserType>& accessor) {
    if(_module == nullptr) {
      _module = dynamic_cast<ApplicationModule*>(dynamic_cast<Module*>(accessor.getOwner())->findApplicationModule());
    }
    if(!_variableMap.count(accessor.getId())) {
      if(Application::getInstance().getLifeCycleState() == LifeCycleState::initialisation) {
        // only add tag in initialisation phase, since later model modifications can lead to race conditions
        accessor.addTag(std::string(tagValidatedVariable));
      }
      _variableMap[accessor.getId()] = std::make_shared<Variable<UserType, Accessor>>(accessor);
 
      // Call the AccessorHook::onAddValidator() if present in the accessor
      auto hook = boost::dynamic_pointer_cast<AccessorHook>(accessor.getImpl());
      if(hook) {
        hook->onAddValidator(*this);
      }
    }
  }
  /********************************************************************************************************************/
 
  template<typename UserType, template<typename> typename Accessor>
  UserInputValidator::Variable<UserType, Accessor>::Variable(Accessor<UserType>& validatedAccessor)
  : accessor(validatedAccessor) {
    auto node = static_cast<VariableNetworkNode>(validatedAccessor);
 
    if(node.getMode() != UpdateMode::push) {
      throw ChimeraTK::logic_error("UserInputValidator can only be used with push-type inputs.");
    }
 
    if constexpr(std::derived_from<Accessor<UserType>, ChimeraTK::ScalarAccessor<UserType>>) {
      fallbackValue.resize(1);
    }
    else {
      fallbackValue.resize(accessor.getNElements());
    }
    lastAcceptedValue.set_capacity(1);
  }
 
  /********************************************************************************************************************/
 
  template<typename UserType, template<typename> typename Accessor>
  void UserInputValidator::Variable<UserType, Accessor>::reject(RejectionType type) {
    if(type == RejectionType::downstream && !lastAcceptedValue.empty()) {
      lastAcceptedValue.pop_back();
    }
    if constexpr(std::derived_from<Accessor<UserType>, ChimeraTK::ScalarAccessor<UserType>>) {
      if(lastAcceptedValue.empty()) {
        accessor = fallbackValue[0];
      }
      else {
        accessor = lastAcceptedValue.back()[0];
      }
    }
    else {
      if(lastAcceptedValue.empty()) {
        accessor = fallbackValue;
      }
      else {
        accessor = lastAcceptedValue.back();
      }
    }
 
    // Call the AccessorHook::onReject() if present in the accessor
    auto hook = boost::dynamic_pointer_cast<AccessorHook>(accessor.getImpl());
    if(hook) {
      hook->onReject();
    }
 
    if(accessor.isWriteable()) {
      accessor.write();
    }
  }
 
  /********************************************************************************************************************/
  template<typename UserType, template<typename> typename Accessor>
  void UserInputValidator::Variable<UserType, Accessor>::accept() {
    if constexpr(std::derived_from<Accessor<UserType>, ChimeraTK::ScalarAccessor<UserType>>) {
      auto savedValue = std::vector<UserType>(1);
      savedValue[0] = accessor;
      lastAcceptedValue.push_back(savedValue);
    }
    else {
      auto savedValue = std::vector<UserType>(accessor.getNElements());
      savedValue = accessor;
      lastAcceptedValue.push_back(savedValue);
    }
 
    // Call the AccessorHook::onAccept() if present in the accessor
    auto hook = boost::dynamic_pointer_cast<AccessorHook>(accessor.getImpl());
    if(hook) {
      hook->onAccept();
    }
  }
  /********************************************************************************************************************/
 
  template<typename UserType, template<typename> typename Accessor>
  void UserInputValidator::Variable<UserType, Accessor>::setHistorySize(std::size_t size) {
    historyLength = 3 * size;
    lastAcceptedValue.set_capacity(historyLength);
  }
 
  /********************************************************************************************************************/
 
} // namespace ChimeraTK