ReadCoordinator.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 "NumericAddressedRegisterCatalogue.h"
#include "RawConverter.h"
#include "SupportedUserTypes.h"
 
#include <cstring>
#include <list>
#include <map>
#include <memory>
#include <typeindex>
#include <vector>
 
namespace ChimeraTK::detail {
 
  /********************************************************************************************************************/
 
  class ReadCoordinator {
   public:
    struct GroupKey {
      NumericAddressedRegisterInfo::Type dataType{};
      uint32_t width{};
      int32_t nFractionalBits{};
      bool signedFlag{};
      DataType rawType;
      std::type_index userType{typeid(std::nullptr_t)};
      bool isRaw{};
 
      auto operator<=>(const GroupKey&) const = default;
    };
 
    template<typename UserType>
    struct Consumer {
      Consumer(size_t offset, size_t pitch, size_t count, std::vector<UserType>& stagingBuffer);
 
      size_t byteOffset{}; // offset of first sample within the raw buffer
      size_t stride{};     // elementPitchBits / 8 (equal to the element data width for a non-strided consumer)
      size_t nSamples{};
      std::vector<UserType>& staging;
    };
 
    struct GroupBase {
      [[nodiscard]] virtual bool consumersEmpty() const = 0;
 
      virtual void rawCopy(const std::vector<uint8_t>& rawBuffer) = 0;
 
      virtual ~GroupBase() = default;
 
      bool isRaw{};
      std::unique_ptr<RawConverter::ConverterLoopHelper> converterLoopHelper;
    };
 
    template<typename UserType>
    struct Group : GroupBase {
      [[nodiscard]] bool consumersEmpty() const override;
 
      void rawCopy(const std::vector<uint8_t>& rawBuffer) override;
 
      std::list<Consumer<UserType>> consumers;
    };
 
    template<typename UserType>
    class Registration {
     public:
      Registration() = default;
 
      Registration(ReadCoordinator* owner, const NumericAddressedRegisterInfo& info, bool isRaw, size_t byteOffset,
          size_t stride, size_t nSamples);
 
      ~Registration();
 
      Registration(const Registration&) = delete;
      Registration& operator=(const Registration&) = delete;
 
      Registration(Registration&& other) noexcept;
      Registration& operator=(Registration&& other) noexcept;
 
      void reset();
 
      [[nodiscard]] std::vector<UserType>& staging();
 
     private:
      friend class ReadCoordinator;
 
      ReadCoordinator* _owner{nullptr};
      size_t _groupId{}; // the consumer's group, see _groups
      std::list<Consumer<UserType>>::iterator _it;
 
      // Heap-allocated so its address (which the registered Consumer references) stays stable when the registration is
      // moved; the moveable handle owns it, the buffer's data pointer changes on each swap, never its address.
      std::unique_ptr<std::vector<UserType>> _staging;
    };
 
    ReadCoordinator() = default;
 
    ReadCoordinator(const ReadCoordinator&) = delete;
    ReadCoordinator(ReadCoordinator&&) noexcept = delete;
    ReadCoordinator& operator=(const ReadCoordinator&) = delete;
    ReadCoordinator& operator=(ReadCoordinator&&) noexcept = delete;
 
    ~ReadCoordinator() = default;
 
    [[nodiscard]] bool empty() const;
 
    void run(const std::vector<uint8_t>& rawBuffer);
 
    template<class UserType, typename RawType, RawConverter::SignificantBitsCase sc, RawConverter::FractionalCase fc,
        bool isSigned>
    void doPostReadImpl(RawConverter::Converter<UserType, RawType, sc, fc, isSigned> converter, size_t groupId);
 
    template<class UserType, typename RawType, RawConverter::SignificantBitsCase sc, RawConverter::FractionalCase fc,
        bool isSigned>
    void doPreWriteImpl(RawConverter::Converter<UserType, RawType, sc, fc, isSigned> converter, size_t groupId);
 
   private:
    template<typename>
    friend class Registration;
 
    // _groups stores the type-erased groups keyed by their stable, monotonically increasing groupId; _groupIndex maps
    // each group key to that groupId. The groupId is a non-positional identity handed to the group's
    // ConverterLoopHelper, so it can never go stale. A group is removed only at teardown (it is never erased while the
    // element lives, it just loses its consumers), so the registry only ever grows or vanishes wholesale with the
    // element and needs no freed-slot tracking.
    std::map<size_t, std::unique_ptr<GroupBase>> _groups;
    std::map<GroupKey, size_t> _groupIndex;
    size_t _nextGroupId{};
    // the current read's raw buffer, set only while run() iterates the groups; null between reads
    const std::vector<uint8_t>* _rawBuffer{nullptr};
  };
 
  /********************************************************************************************************************/
 
  template<typename UserType>
  inline ReadCoordinator::Consumer<UserType>::Consumer(
      size_t offset, size_t pitch, size_t count, std::vector<UserType>& stagingBuffer)
  : byteOffset(offset), stride(pitch), nSamples(count), staging(stagingBuffer) {}
 
  /********************************************************************************************************************/
 
  template<typename UserType>
  inline bool ReadCoordinator::Group<UserType>::consumersEmpty() const {
    return consumers.empty();
  }
 
  /********************************************************************************************************************/
 
  template<typename UserType>
  inline void ReadCoordinator::Group<UserType>::rawCopy(const std::vector<uint8_t>& rawBuffer) {
    for(const auto& consumer : consumers) {
      if(consumer.nSamples == 0) {
        continue;
      }
      auto* cooked = consumer.staging.data();
      const auto* raw = rawBuffer.data() + consumer.byteOffset;
      // A raw-mode group holds consumers whose UserType is the register's raw data type: an integer of the matching
      // size and signedness (signed or unsigned). The nested if constexpr is a compile-time gate: the memcpy below is
      // instantiated only for such types and never for any other UserType (which would be undefined behaviour). The
      // outer integral guard comes first because std::make_unsigned_t is defined only for integral and enum types, so
      // the unsigned counterpart may be formed only behind it; the remaining non-integral UserTypes are excluded by it.
      // isRawType covers unsigned raw types only, while a raw-mode UserType may be signed, hence the unsigned
      // counterpart is checked. Such a use cannot be formed through the library, so no runtime fallback exists.
      if constexpr(std::is_integral_v<UserType>) {
        if constexpr(ChimeraTK::isRawType<std::make_unsigned_t<UserType>>) {
          for(size_t i = 0; i < consumer.nSamples; ++i) {
            std::memcpy(cooked + i, raw + i * consumer.stride, sizeof(UserType));
          }
        }
      }
    }
  }
 
  /********************************************************************************************************************/
 
  DECLARE_TEMPLATE_FOR_CHIMERATK_USER_TYPES(ReadCoordinator::Registration);
 
  /********************************************************************************************************************/
 
} // namespace ChimeraTK::detail