PhaseIIInDetRawDataContainer.h

Go to the documentation of this file.

/*
  Copyright (C) 2002-2026 CERN for the benefit of the ATLAS collaboration
  */
#ifndef PHASEII_RAWDATACONTAINER_H
#define PHASEII_RAWDATACONTAINER_H
 
#include <array>
#include <vector>
#include <cassert>
#include <cstdint>
#include <cstring>
#include <atomic>
 
#include "ProxyContainer.h"
#include "ContainerList.h"
 
namespace PhaseII {
 
   template <typename Type>
   concept isAtomic = requires( Type a, typename Type::value_type b ) { a.compare_exchange_weak(b,b); };
 
   // test whether the given container type has an error container
   template <typename T_DataContainer>
   concept hasErrors = requires(T_DataContainer &a, unsigned int idx) { a.errors()[idx]; };
 
   template <typename T>
   struct GetValue {
      static auto value(const T &value) requires ( !isAtomic<T> ) { return value; }
      static auto value(const T &value) requires (  isAtomic<T> ) { return value.load(); }
   };

   struct  DataRange {
      using RangeBeginIndex_t = std::uint32_t;
      using RangeSize_t = std::uint16_t;
      using ContainerIndex_t = std::uint16_t;
      // wrap members of the DataRange into union to convince clang to
      // use this type as a value for a lock free atomic.
      union {
         struct Range {
            RangeBeginIndex_t m_beginIndex{};    
            RangeSize_t m_n{};                   
            ContainerIndex_t m_containerIndex{}; 
         } m_range;
         std::uint64_t m_compactRange;
      } m_payload;
 
      DataRange() : m_payload{.m_compactRange = std::uint64_t{} }{}
      DataRange(std::uint64_t compact_range) : m_payload{.m_compactRange = compact_range }{}
      DataRange(unsigned int  begin_val, unsigned int n, unsigned int idx)
         : m_payload{ .m_range = {static_cast<std::uint32_t>(begin_val), static_cast<std::uint16_t>(n), static_cast<std::uint16_t>(idx)} }
      {
         assert(begin_val<std::numeric_limits<std::uint32_t>::max());
         assert(n<std::numeric_limits<std::uint16_t>::max());
         assert(idx<std::numeric_limits<std::uint16_t>::max());
      }
      DataRange(std::uint32_t begin_val, std::uint16_t  n, std::uint16_t idx)
         : m_payload{ .m_range= {begin_val, n, idx} }
      {
      }
      std::uint64_t makeCompact() const {
         static_assert( sizeof(m_payload.m_range) == sizeof(std::uint64_t));
         return m_payload.m_compactRange;
      }
 
      void setSize(RangeSize_t new_size) { m_payload.m_range.m_n=new_size; }
      std::uint16_t containerIndex() const { return m_payload.m_range.m_containerIndex; }
      unsigned int beginIndex() const { return m_payload.m_range.m_beginIndex;}
      unsigned int endIndex() const { return m_payload.m_range.m_beginIndex + m_payload.m_range.m_n; }
      std::uint16_t size() const { return m_payload.m_range.m_n; }
      bool empty() const { return m_payload.m_range.m_n==0u; }
      template <typename T_ElementIndex, typename T_ContainerIndex>
      static DataRange makeDataRange(T_ElementIndex begin_index,
                                     T_ElementIndex end_index,
                                     T_ContainerIndex container_index) {
         // ensure that the inputs are within the allowed range in (debug build only!)
         // @TODO check some of these always during runtime ?
         //       Replace this convenience method into a constructor ? But an exception could be thrown here.
         assert( end_index >= begin_index ) ;
         assert( static_cast<std::uint32_t>(begin_index) == begin_index);
         assert( static_cast<std::size_t>(end_index -  begin_index) < std::numeric_limits<std::uint16_t>::max());
         assert( static_cast<std::uint16_t>(container_index) == container_index);
         return DataRange(static_cast<std::uint32_t>(begin_index),
                          static_cast<std::uint16_t>(end_index - begin_index),
                          static_cast<std::uint16_t>(container_index));
      }
   };
 

   template <class T_DataContainer, class T_RangeType>
   class IndexedRanges {
   public:
      using DataContainerType = T_DataContainer;
      using T_RangeTypeBase = decltype( GetValue<T_RangeType>::value(T_RangeType{}));

      IndexedRanges(unsigned int n_ranges, unsigned int container_list_size)
         : m_containers(container_list_size), m_range(n_ranges) {}

      bool registerOrEraseNewData(unsigned int index, const T_RangeTypeBase &new_range)
      {
         assert (index < m_range.size());
         assert( new_range.containerIndex() < m_containers.size() );
         T_RangeTypeBase is_range = m_range[index];
         if (is_range.size() != new_range.size()) {
            assert(is_range.empty());
            if (update(index, is_range, new_range)) {
               return true;
            }
         }
         // it is assumed that data is always added at the end and then registered.
         assert( new_range.beginIndex() + new_range.size() == m_containers[new_range.containerIndex()].size());
         m_containers[new_range.containerIndex()].erase_back(new_range.beginIndex());
         return false;
      }

      // @TODO declare protected ?
      bool update(unsigned int index, T_RangeTypeBase & is_range, const T_RangeTypeBase &new_range) requires( isAtomic<T_RangeType> )
      {
         assert( index < m_range.size());
         return m_range[index].compare_exchange_weak(is_range, new_range);
      }

      // @TODO declare protected ?
      bool update(unsigned int index, [[maybe_unused]] T_RangeTypeBase & is_range, const T_RangeTypeBase &new_range) requires(!isAtomic<T_RangeType>)
      {
         assert( index < m_range.size());
         m_range[index]=new_range;
         return true;
      }

      const T_DataContainer &data(unsigned int container_index) const
         { assert(container_index<m_containers.size()); return m_containers[container_index]; }

      T_DataContainer &data(unsigned int container_index)
         { assert(container_index<m_containers.size()); return m_containers[container_index]; }

      const T_RangeType &range(unsigned int index) const {
         assert(index < m_range.size());
         return m_range[index];
      }

      std::size_t size() const { return m_range.size(); }
      std::size_t empty() const { return m_range.empty(); }

      std::size_t containerListCapacity() const { return m_containers.size(); }

      const auto &errorContainer(unsigned int container_index) const requires(hasErrors<T_DataContainer>) {
         assert( container_index < m_containers.size() );
         assert( m_containers[container_index].errors().empty() || m_containers[container_index].errors().size() == m_range.size());
         return m_containers[container_index].errors();
      }

      auto &errorContainer(unsigned int container_index) requires(hasErrors<T_DataContainer>) {
         assert( container_index < m_containers.size() );
         return m_containers[container_index].errors();
      }
 
   protected:
      ContainerList<T_DataContainer> m_containers;
      std::vector<T_RangeType>       m_range;
   };
 

   struct IndexWithRange  {
      unsigned int m_beginIndex {}; 
      unsigned int m_endIndex {};   
      unsigned int m_rangeIndex {}; 

      unsigned int beginIndex() const { return m_beginIndex; }
      unsigned int endIndex() const { return m_endIndex; }
      bool empty() const { return m_endIndex == m_beginIndex; }

      const unsigned int &rangeIndex() const { return m_rangeIndex; }
 
      // only used in unit test
      bool operator==(const IndexWithRange &other) const {
         // should only be executed if the indices refer to the same range
         // thus the cached begin index should always be identical, and
         // comparison is limited to the minimum, which is only sufficient
         // if the the two indices refer to the same range, which is the
         // case when this comparison would be done as part of a range based
         // for loop.
         assert(m_endIndex == other.m_endIndex);
         assert(m_beginIndex == other.m_beginIndex);
         return m_rangeIndex == other.m_rangeIndex;
      }
   };
 
   // assumed cache line size
   static constexpr std::size_t CACHELINE = 64ul;

   // In case the raw data is filled concurrently, there will be multiple containers which may be
   // adjacent to one-another. to ensure that concurrent modification of the content of adjacent
   // containers will not change the same cache line, an alignment requirement of the the assumed
   // cache line size is chosen.
   template <std::size_t NDim>
   class alignas(CACHELINE) InDetRawDataContainer {
   public:

      bool isValid(unsigned int index) const      { return index < m_coordinates.size() && index < m_word.size(); }

      const std::array<std::int16_t,NDim> &coordinates(unsigned int index) const { assert(isValid(index)); return m_coordinates[index]; }
      std::array<std::int16_t,NDim> &coordinates(unsigned int index)             { assert(isValid(index)); return m_coordinates[index]; }
      const std::uint32_t &dataWord(unsigned int index) const                 { assert(isValid(index)); return m_word[index]; }
      std::uint32_t &dataWord(unsigned int index)                             { assert(isValid(index)); return m_word[index]; }
 
      // Test whether the container is in a sane state (for debugging).
      // The container is in a sane state if the number elements in all the vectors are synchronised.
      bool isSane() const          { return m_coordinates.size() == m_word.size(); }

      std::size_t size() const     { return m_coordinates.size(); }
      bool empty() const           { return m_coordinates.empty(); }
      std::size_t capacity() const { assert(m_coordinates.capacity() == m_word.capacity()); return m_coordinates.capacity(); }

      void reserve(std::size_t new_capacity) {
         m_coordinates.reserve(new_capacity);
         m_word.reserve(new_capacity);
         assert(isSane() && m_coordinates.capacity() == m_word.capacity());
      }

      void emplace_back(std::array<std::int16_t,NDim> &&coordinates, std::uint32_t data_word) {
         // @TODO should bail out if container is filled concurrently and the
         //       size is equal to the capacity, but the container does not know.
         m_coordinates.emplace_back(std::move(coordinates));
         m_word.emplace_back(data_word);
         assert(isSane());
      }

      void erase_back( unsigned int begin_index) {
         assert( begin_index <= m_coordinates.size());
         m_coordinates.erase( m_coordinates.begin()+begin_index, m_coordinates.end());
         m_word.erase( m_word.begin()+begin_index, m_word.end());
         assert(isSane());
      }

      static constexpr int unpack(std::uint32_t mask, unsigned int shift, unsigned int word) {
         return static_cast<int>( (word >> shift ) & mask );
      }

      static constexpr std::uint32_t pack(std::uint32_t mask, unsigned int shift, int input) {
         // test that packing is loss-less
         assert( static_cast<int>(static_cast<std::uint32_t>(input) & mask) ==input );
         return static_cast<std::uint32_t>( (input & mask) << shift );
      }

      void move(InDetRawDataContainer &dest, unsigned int start_index) {
         unsigned int copy_n_elements=size()-start_index;
         dest.m_coordinates.resize(copy_n_elements);
         dest.m_word.resize(copy_n_elements);
         std::memcpy(dest.m_coordinates.data(),m_coordinates.data()+start_index,copy_n_elements*sizeof(typename decltype(m_coordinates)::value_type));
         std::memcpy(dest.m_word.data(), m_word.data()+start_index, copy_n_elements*sizeof(typename decltype(m_word)::value_type) );
         this->erase_back(start_index);
      }
   private:
      std::vector<std::array<std::int16_t,NDim> > m_coordinates;
      std::vector<std::uint32_t>                  m_word;
   };
 
 
   using namespace Utils;

   template <class T_RawDataContainer>
   class RawDataProxyBase : public Utils::ElementProxyBase<T_RawDataContainer, unsigned int> {
   public:
      using BASE = Utils::ElementProxyBase<T_RawDataContainer, unsigned int>;
      using BASE::BASE;
 
      const auto &coordinates() const {
         return this->container().coordinates(this->index());
      }
      auto &coordinates() requires (!BASE::isConst)  {
         return this->container().coordinates(this->index());
      }
      const auto &dataWord() const {
         return this->container().dataWord(this->index());
      }
      auto &dataWord() requires (!BASE::isConst)  {
         return this->container().dataWord(this->index());
      }
   };

   template <class T_RawDataContainer, class T_RawDataProxy>
   class RawDataContainerProxy :  public ContainerProxy<T_RawDataContainer,
                                                  RawDataContainerProxy<T_RawDataContainer, T_RawDataProxy>,
                                                  T_RawDataProxy,
                                                  IndexWithRange>  {
   public:
      using BASE = ContainerProxy<T_RawDataContainer,
                                  RawDataContainerProxy<T_RawDataContainer, T_RawDataProxy>,
                                  T_RawDataProxy,
                                  IndexWithRange> ;
 
      using BASE::BASE;

      static unsigned int beginIndex([[maybe_unused]] const T_RawDataContainer *container, const IndexWithRange &range)
      {
         assert( range.empty()  || container);
         return range.beginIndex();
      }

      static unsigned int endIndex([[maybe_unused]] const T_RawDataContainer *container, const IndexWithRange &range) {
         assert( range.empty()  || container);
         return range.endIndex();
      }

      static unsigned int nextElementIndex([[maybe_unused]] const T_RawDataContainer *container, unsigned int element_index)
      {
         assert( element_index < container->size());
         return ++element_index;
      }

      const unsigned int &identifyHash() const { return this->index().rangeIndex(); }
 
      // convenience methods
      unsigned int beginIndex() const { return this->index().beginIndex(); }
      unsigned int endIndex() const { return this->index().endIndex(); }
 
   };
 
   namespace RawData {
   namespace details {
   // to define the proxy that should be used for the given raw data container.
   template <class T_RawDataContainer>
   struct traits  {
      template <AccessPolicy accessPolicy>
      using RawDataProxy = RawDataProxyBase<typename Utils::ContainerAccessHelper<T_RawDataContainer, accessPolicy>::ContainerType >;
   };
   }
   }

   // @TODO add concepts for T_RawDataContainerCollection
   template <class T_RawDataContainerCollection, class T_RawDataProxy>
   class ContainerProxyAdapter : public Utils::ElementProxyBase<T_RawDataContainerCollection,unsigned int >
   {
      using BASE = Utils::ElementProxyBase<T_RawDataContainerCollection,unsigned int >;
      using T_Range = typename T_RawDataContainerCollection::T_RangeTypeBase;
      using T_RawDataContainer = std::remove_cvref_t<decltype(std::declval<T_RawDataContainerCollection>().data(std::uint32_t{}))>;
      // Create a special index which also provided the child element range.
      static IndexWithRange getIndexWithRange(const T_RawDataContainerCollection &container, unsigned int module_index) {
         T_Range range = container.range(module_index); // container has to implement range(module_index)
         return IndexWithRange(range.beginIndex(),
                               range.endIndex(),
                               module_index);
      }
      // Get from this container collection the actual container which contains the hit data (read only).
      static const T_RawDataContainer *getRawDataContainer(const T_RawDataContainerCollection &container, unsigned int module_index) {
         T_Range range = container.range(module_index);
         return &(container.data(range.containerIndex()));
      }
      // Get from this container collection the actual container which contains the hit data (read/write).
      static T_RawDataContainer *getRawDataContainer(T_RawDataContainerCollection &container, unsigned int module_index)
         requires(!BASE::isConst)
      {
         T_Range range = container.range(module_index);
         return &(container.data(range.containerIndex()));
      }
   public:
      using BASE::BASE;

      static RawDataContainerProxy<T_RawDataContainer, T_RawDataProxy>
      create(T_RawDataContainerCollection *container, unsigned int module_index)
      {
         assert(container);
         RawDataContainerProxy<T_RawDataContainer, T_RawDataProxy> proxy( getRawDataContainer(*container,module_index),
                                                                           getIndexWithRange(*container,module_index) );
         return proxy;
      }

      static RawDataContainerProxy<const T_RawDataContainer, T_RawDataProxy>
      create(const T_RawDataContainerCollection *container, unsigned int module_index)
         requires(BASE::isConst)
      {
         assert(container);
         RawDataContainerProxy<const T_RawDataContainer, T_RawDataProxy> proxy( getRawDataContainer(*container,module_index),
                                                                                 getIndexWithRange(*container,module_index) );
         return proxy;
      }

      static unsigned int getOriginalElementIndex(const IndexWithRange &index) {
         return index.rangeIndex();
      }
   };

   template <class T_RawDataContainerCollection, class T_RawDataProxy>
   class ContainerCollectionProxy : public ContainerProxy<T_RawDataContainerCollection,
                                                          ContainerCollectionProxy<T_RawDataContainerCollection, T_RawDataProxy>,
                                                          ContainerProxyAdapter<T_RawDataContainerCollection, T_RawDataProxy>,
                                                          RootNodeIndex > {
      using BASE=ContainerProxy<T_RawDataContainerCollection,
                                ContainerCollectionProxy<T_RawDataContainerCollection, T_RawDataProxy>,
                                ContainerProxyAdapter<T_RawDataContainerCollection, T_RawDataProxy>,
                                RootNodeIndex >;
      using BASE::BASE;
   };

   template <class T_RawDataContainer>
   struct RawDataTypeTraits {
      static constexpr bool isConst = std::is_const_v<T_RawDataContainer>;
      static constexpr Utils::AccessPolicy accessPolicy=AccessPolicyHelper<isConst>::accessPolicy;
      using ContainerNonConst = std::remove_cvref_t<T_RawDataContainer>;
 
      // the collection should be based on the non const container
      using ContainerCollection = typename Utils::ContainerAccessHelper<PhaseII::IndexedRanges<ContainerNonConst, std::atomic<PhaseII::DataRange> >,
                                                                        accessPolicy>::ContainerType;
      // but the proxies if (const) refer to the const collection and finally the const container.
      using RawDataProxy = typename RawData::details::traits<ContainerNonConst>::template RawDataProxy<accessPolicy>;
      using RawDataContainerProxy  = PhaseII::RawDataContainerProxy<typename Utils::ContainerAccessHelper<T_RawDataContainer,
                                                                                                          accessPolicy>::ContainerType,
                                                                    RawDataProxy >;
      using ContainerProxyAdapter  = PhaseII::ContainerProxyAdapter<typename Utils::ContainerAccessHelper<ContainerCollection,
                                                                                                          accessPolicy>::ContainerType,
                                                                    RawDataProxy>;
      using ContainerCollectionProxy = PhaseII::ContainerCollectionProxy<typename Utils::ContainerAccessHelper<ContainerCollection,
                                                                                                               accessPolicy>::ContainerType,
                                                                         RawDataProxy>;
   };

   template <class T_RawDataContainerCollection>
   inline auto makeRawDataCollectionProxy(const T_RawDataContainerCollection &collection) {
      using T_RawDataContainer = typename T_RawDataContainerCollection::DataContainerType;
      static_assert( RawDataTypeTraits<const T_RawDataContainer>::ContainerCollectionProxy::isConst);
      using ContainerNonConst = std::remove_cvref_t<T_RawDataContainerCollection>;
      static_assert( std::is_base_of_v<typename RawDataTypeTraits<const T_RawDataContainer>::ContainerCollectionProxy::ContainerNonConst,
                                       ContainerNonConst>);
      return typename RawDataTypeTraits<const T_RawDataContainer>::ContainerCollectionProxy(&collection);
   }

   template <class T_RawDataContainerCollection>
   inline auto makeRawDataCollectionProxy(T_RawDataContainerCollection &collection) {
      using T_RawDataContainer = typename T_RawDataContainerCollection::DataContainerType;
      return typename RawDataTypeTraits<T_RawDataContainer>::ContainerCollectionProxy(&collection);
   }
}
#endif