Skip to content
XFELPP

FormatTraits

FormatTraits

Section titled “FormatTraits”
#include <sbio/formats/format_traits.hh>
template<typename T, typename IO, typename EPolicy>
concept FormatTraits

Defined in src/lib/sbio/formats/format_traits.hh:301

The FormatTraits concept defines a conforming data-format implementation.

A struct implementing the following constraints is both necessary and sufficient to serve as a data-format implementation for the rest of the generic sbio infrastructure.

There are a number of additional concepts which can be used to test for optional APIs and features of a data-format implementation.

The concept is subdivided into a number of sub-concepts for various pieces of the overall API. A conforming struct will look something like the following:

struct ImplementsFormatTraits {
  // HasBoundedDataDimensions
  // ------------------------
  static constexpr std::size_t HeaderSize { 0 };
  static constexpr std::uint16_t MaxRank { 1 };
  static constexpr std::uint16_t MaxNameSize { 1 };


  // HasCountableDataUnits
  // ---------------------
  using DataUnit = void;
  using StepIdxType = std::size_t;
  static constexpr StepIdxType ExhaustedSentinel { static_cast<StepIdxType>(-1) };


  // CanFindAndConfigureStreams
  // --------------------------
  static constexpr StreamPartitioningStrategy PartitioningStrategy {
    StreamPartitioningStrategy::SubDivide
  };


  struct DataStream : public StreamVariant<roles::Data> {};
  using StreamTypes = StreamSet<DataStream>;


  enum class DataAccessPtn : std::uint8_t { };
  static constexpr std::size_t DataAccessPtnCount { 0 };
  struct StreamParameters {};


  // CanAllocateStorage
  // ------------------
  using BrokerBufferRequirements = RequirementsList<>;
  static AllocationRequest<T> get_allocation_request(GenericStreamConfig<ImplementsFormatTraits>& cfg);


  // HasDataRequest
  // --------------
  struct DataRequest { };


  // HasStreamState
  // --------------
  struct FieldMetadata { };


  // CanDiscoverMetadata
  // -------------------------------------------
  template <IOTraits IO, class StorageViewT>
  static IOStatus discover_metadata(Stream<IO, T>* streams,
                                    StorageViewT& storage,
                                    MetadataInventory<ImplementsFormatTraits>& inv);


  // CanIndexStreams  [[ OPTIONAL ]]
  // ---------------
  template <IOTraits IO, class StorageViewT>
  static IOStatus index_stream(Stream<IO, T>* streams,
                               StorageViewT& storage,
                               StreamCatalog<ImplementsFormatTraits>& catalog,
                               IndexingCursor<ImplementsFormatTraits>& cursor,
                               const StreamParameters& cfg);


  // CanFetchStreamData
  // ------------------
  template <IOTraits IO, class StorageViewT>
  static IOStatus fetch_step(Stream<IO, T>* streams,
                             StorageViewT& storage,
                             const StreamCatalog<ImplementsFormatTraits>& catalog,
                             FetchCursor<ImplementsFormatTraits>& cursor,
                             const GenericStreamConfig<ImplementsFormatTraits>& cfg,
                             StepIdxType step_idx,
                             DataAccessPtn ptn);


  // CanResolveData && CanFillBuffer
  // -------------------------------
  // The cache belongs to the caller parallel unit (likely from SegmentCursor)
  // It stores an offset for where the requested field was found wihtin the buf.
  // It is safe to write/update that offset, without synchronization.
  static inline DataResult resolve_data(void* buf,
                                        const MetadataInventory<ImplementsFormatTraits>& inv,
                                        const DataRequest& req,
                                        PayloadOffsetCache& cache);
  static std::size_t get_payload_size(void* buf);


  template <class StorageViewT>
  static DataResult get_data_in_buffer(StorageViewT& storage,
                                       const MetadataInventory<ImplementsFormatTraits>& inv,
                                       const DataRequest& req,
                                       PayloadOffsetCache& cache,
                                       DataAccessPtn ptn,
                                       std::size_t batch_idx);
 };