16#ifndef ROOT7_RPageStorage
17#define ROOT7_RPageStorage
42#include <shared_mutex>
43#include <unordered_map>
44#include <unordered_set>
48namespace Experimental {
54class RNTupleCompressor;
55struct RNTupleModelChangeset;
83 virtual void AddTask(
const std::function<
void(
void)> &taskFunc) = 0;
101 RSealedPage(
const void *buffer, std::size_t bufferSize, std::uint32_t nElements,
bool hasChecksum =
false)
137 SealedPageSequence_t::const_iterator
fFirst;
138 SealedPageSequence_t::const_iterator
fLast;
233 bool TryEvict(std::size_t targetAvailableSize, std::size_t pageSizeLimit);
407 if (
fLock !=
nullptr) {
417 if (
fLock !=
nullptr) {
475 virtual void InitImpl(
unsigned char *serializedHeader, std::uint32_t
length) = 0;
488 virtual std::vector<RNTupleLocator>
515 static std::unique_ptr<RPageSink>
Create(std::string_view ntupleName, std::string_view location,
608 bool fHasStructure =
false;
609 bool fIsAttached =
false;
651 std::size_t fRefCounter = 0;
660 std::unordered_map<DescriptorId_t, std::vector<RColumnInfo>>
fColumnInfos;
669 return fColumnInfos.at(physicalColumnId);
680 std::uint64_t fColumnOffset = 0;
696 virtual std::unique_ptr<RPageSource>
CloneImpl()
const = 0;
698 virtual void UnzipClusterImpl(
RCluster *cluster);
706 void PrepareLoadCluster(
729 static std::unique_ptr<RPageSource>
Create(std::string_view ntupleName, std::string_view location,
734 std::unique_ptr<RPageSource> Clone()
const;
763 void LoadStructure();
771 void SetEntryRange(
const REntryRange &range);
796 virtual std::vector<std::unique_ptr<RCluster>>
LoadClusters(std::span<RCluster::RKey> clusterKeys) = 0;
803 void UnzipCluster(
RCluster *cluster);
#define R__FAIL(msg)
Short-hand to return an RResult<T> in an error state; the RError is implicitly converted into RResult...
Option_t Option_t TPoint TPoint const char GetTextMagnitude GetFillStyle GetLineColor GetLineWidth GetMarkerStyle GetTextAlign GetTextColor GetTextSize void char Point_t Rectangle_t WindowAttributes_t Float_t Float_t Float_t Int_t Int_t UInt_t UInt_t Rectangle_t mask
Option_t Option_t TPoint TPoint const char GetTextMagnitude GetFillStyle GetLineColor GetLineWidth GetMarkerStyle GetTextAlign GetTextColor GetTextSize void char Point_t Rectangle_t WindowAttributes_t Float_t Float_t Float_t Int_t Int_t UInt_t UInt_t Rectangle_t Int_t Int_t Window_t TString Int_t GCValues_t GetPrimarySelectionOwner GetDisplay GetScreen GetColormap GetNativeEvent const char const char dpyName wid window const char font_name cursor keysym reg const char only_if_exist regb h Point_t winding char text const char depth char const char Int_t count const char ColorStruct_t color const char Pixmap_t Pixmap_t PictureAttributes_t attr const char char ret_data h unsigned char height h length
A thread-safe integral performance counter.
A metric element that computes its floating point value from other counters.
A collection of Counter objects with a name, a unit, and a description.
An either thread-safe or non thread safe counter for CPU ticks.
An in-memory subset of the packed and compressed pages of a cluster.
std::unordered_set< DescriptorId_t > ColumnSet_t
A column element encapsulates the translation between basic C++ types and their column representation...
A column is a storage-backed array of a simple, fixed-size type, from which pages can be mapped into ...
A helper class for piece-wise construction of an RNTupleDescriptor.
const RNTupleDescriptor & GetDescriptor() const
The serialization context is used for the piecewise serialization of a descriptor.
std::map< Int_t, TVirtualStreamerInfo * > StreamerInfoMap_t
A memory region that contains packed and compressed pages.
Abstract interface to allocate and release pages.
Base class for a sink with a physical storage backend.
RPagePersistentSink(const RPagePersistentSink &)=delete
ColumnHandle_t AddColumn(DescriptorId_t fieldId, RColumn &column) final
Register a new column.
RPagePersistentSink(RPagePersistentSink &&)=default
RStagedCluster StageCluster(NTupleSize_t nNewEntries) final
Stage the current cluster and create a new one for the following data.
std::uint64_t fNextClusterInGroup
Remembers the starting cluster id for the next cluster group.
virtual std::uint64_t StageClusterImpl()=0
Returns the number of bytes written to storage (excluding metadata)
RPagePersistentSink & operator=(RPagePersistentSink &&)=default
virtual void InitImpl(unsigned char *serializedHeader, std::uint32_t length)=0
~RPagePersistentSink() override
virtual std::vector< RNTupleLocator > CommitSealedPageVImpl(std::span< RPageStorage::RSealedPageGroup > ranges, const std::vector< bool > &mask)
Vector commit of preprocessed pages.
RNTupleSerializer::RContext fSerializationContext
Used to map the IDs of the descriptor to the physical IDs issued during header/footer serialization.
virtual RNTupleLocator CommitPageImpl(ColumnHandle_t columnHandle, const RPage &page)=0
void InitFromDescriptor(const RNTupleDescriptor &descriptor)
Initialize sink based on an existing descriptor and fill into the descriptor builder.
virtual RNTupleLocator CommitClusterGroupImpl(unsigned char *serializedPageList, std::uint32_t length)=0
Returns the locator of the page list envelope of the given buffer that contains the serialized page l...
NTupleSize_t fPrevClusterNEntries
Used to calculate the number of entries in the current cluster.
std::vector< RClusterDescriptor::RPageRange > fOpenPageRanges
Keeps track of the written pages in the currently open cluster. Indexed by column id.
const RNTupleDescriptor & GetDescriptor() const final
Return the RNTupleDescriptor being constructed.
void CommitPage(ColumnHandle_t columnHandle, const RPage &page) final
Write a page to the storage. The column must have been added before.
virtual void CommitDatasetImpl(unsigned char *serializedFooter, std::uint32_t length)=0
RPagePersistentSink & operator=(const RPagePersistentSink &)=delete
static std::unique_ptr< RPageSink > Create(std::string_view ntupleName, std::string_view location, const RNTupleWriteOptions &options=RNTupleWriteOptions())
Guess the concrete derived page source from the location.
std::unique_ptr< RCounters > fCounters
Internal::RNTupleDescriptorBuilder fDescriptorBuilder
RNTupleSerializer::StreamerInfoMap_t fStreamerInfos
Union of the streamer info records that are sent from streamer fields to the sink before committing t...
void CommitClusterGroup() final
Write out the page locations (page list envelope) for all the committed clusters since the last call ...
std::vector< RClusterDescriptor::RColumnRange > fOpenColumnRanges
Keeps track of the number of elements in the currently open cluster. Indexed by column id.
void UpdateSchema(const RNTupleModelChangeset &changeset, NTupleSize_t firstEntry) final
Incorporate incremental changes to the model into the ntuple descriptor.
void CommitSealedPage(DescriptorId_t physicalColumnId, const RPageStorage::RSealedPage &sealedPage) final
Write a preprocessed page to storage. The column must have been added before.
void CommitSealedPageV(std::span< RPageStorage::RSealedPageGroup > ranges) final
Write a vector of preprocessed pages to storage. The corresponding columns must have been added befor...
void CommitSuppressedColumn(ColumnHandle_t columnHandle) final
Commits a suppressed column for the current cluster.
void CommitStagedClusters(std::span< RStagedCluster > clusters) final
Commit staged clusters, logically appending them to the ntuple descriptor.
void EnableDefaultMetrics(const std::string &prefix)
Enables the default set of metrics provided by RPageSink.
void UpdateExtraTypeInfo(const RExtraTypeInfoDescriptor &extraTypeInfo) final
Adds an extra type information record to schema.
virtual RNTupleLocator CommitSealedPageImpl(DescriptorId_t physicalColumnId, const RPageStorage::RSealedPage &sealedPage)=0
void CommitDatasetImpl() final
A thread-safe cache of pages loaded from the page source.
An RAII wrapper used to synchronize a page sink. See GetSinkGuard().
RSinkGuard(RSinkGuard &&)=delete
RSinkGuard & operator=(const RSinkGuard &)=delete
RSinkGuard(const RSinkGuard &)=delete
RSinkGuard(std::mutex *lock)
RSinkGuard & operator=(RSinkGuard &&)=delete
Abstract interface to write data into an ntuple.
std::vector< unsigned char > fSealPageBuffer
Used as destination buffer in the simple SealPage overload.
bool IsInitialized() const
std::vector< Callback_t > fOnDatasetCommitCallbacks
RPageSink & operator=(RPageSink &&)=default
virtual RStagedCluster StageCluster(NTupleSize_t nNewEntries)=0
Stage the current cluster and create a new one for the following data.
bool fIsInitialized
Flag if sink was initialized.
virtual void UpdateExtraTypeInfo(const RExtraTypeInfoDescriptor &extraTypeInfo)=0
Adds an extra type information record to schema.
void CommitDataset()
Run the registered callbacks and finalize the current cluster and the entrire data set.
virtual void CommitSuppressedColumn(ColumnHandle_t columnHandle)=0
Commits a suppressed column for the current cluster.
virtual const RNTupleDescriptor & GetDescriptor() const =0
Return the RNTupleDescriptor being constructed.
void Init(RNTupleModel &model)
Physically creates the storage container to hold the ntuple (e.g., a keys a TFile or an S3 bucket) In...
virtual RPage ReservePage(ColumnHandle_t columnHandle, std::size_t nElements)
Get a new, empty page for the given column that can be filled with up to nElements; nElements must be...
RWritePageMemoryManager fWritePageMemoryManager
Used in ReservePage to maintain the page buffer budget.
RPageSink(RPageSink &&)=default
virtual void CommitPage(ColumnHandle_t columnHandle, const RPage &page)=0
Write a page to the storage. The column must have been added before.
const RNTupleWriteOptions & GetWriteOptions() const
Returns the sink's write options.
virtual RSinkGuard GetSinkGuard()
RPageSink & operator=(const RPageSink &)=delete
virtual void CommitClusterGroup()=0
Write out the page locations (page list envelope) for all the committed clusters since the last call ...
virtual void CommitDatasetImpl()=0
virtual std::uint64_t CommitCluster(NTupleSize_t nNewEntries)
Finalize the current cluster and create a new one for the following data.
void RegisterOnCommitDatasetCallback(Callback_t callback)
The registered callback is executed at the beginning of CommitDataset();.
RPageSink(const RPageSink &)=delete
std::function< void(RPageSink &)> Callback_t
virtual void CommitSealedPage(DescriptorId_t physicalColumnId, const RPageStorage::RSealedPage &sealedPage)=0
Write a preprocessed page to storage. The column must have been added before.
virtual void CommitStagedClusters(std::span< RStagedCluster > clusters)=0
Commit staged clusters, logically appending them to the ntuple descriptor.
virtual void InitImpl(RNTupleModel &model)=0
void DropColumn(ColumnHandle_t) final
Unregisters a column.
EPageStorageType GetType() final
Whether the concrete implementation is a sink or a source.
std::unique_ptr< RNTupleCompressor > fCompressor
Helper to zip pages and header/footer; includes a 16MB (kMAXZIPBUF) zip buffer.
virtual void UpdateSchema(const RNTupleModelChangeset &changeset, NTupleSize_t firstEntry)=0
Incorporate incremental changes to the model into the ntuple descriptor.
virtual void CommitSealedPageV(std::span< RPageStorage::RSealedPageGroup > ranges)=0
Write a vector of preprocessed pages to storage. The corresponding columns must have been added befor...
std::unique_ptr< RNTupleWriteOptions > fOptions
RSealedPage SealPage(const RPage &page, const RColumnElementBase &element)
Helper for streaming a page.
Keeps track of the requested physical column IDs and their in-memory target type via a column element...
bool HasColumnInfos(DescriptorId_t physicalColumnId) const
const std::vector< RColumnInfo > & GetColumnInfos(DescriptorId_t physicalColumnId) const
std::unordered_map< DescriptorId_t, std::vector< RColumnInfo > > fColumnInfos
Maps physical column IDs to all the requested in-memory representations.
An RAII wrapper used for the writable access to RPageSource::fDescriptor. See GetSharedDescriptorGuar...
RExclDescriptorGuard(RNTupleDescriptor &desc, std::shared_mutex &lock)
void MoveIn(RNTupleDescriptor &&desc)
RExclDescriptorGuard(const RExclDescriptorGuard &)=delete
std::shared_mutex & fLock
RExclDescriptorGuard & operator=(RExclDescriptorGuard &&)=delete
RNTupleDescriptor & fDescriptor
RExclDescriptorGuard & operator=(const RExclDescriptorGuard &)=delete
RNTupleDescriptor * operator->() const
RExclDescriptorGuard(RExclDescriptorGuard &&)=delete
An RAII wrapper used for the read-only access to RPageSource::fDescriptor. See GetExclDescriptorGuard...
const RNTupleDescriptor * operator->() const
const RNTupleDescriptor & GetRef() const
std::shared_mutex & fLock
RSharedDescriptorGuard & operator=(RSharedDescriptorGuard &&)=delete
const RNTupleDescriptor & fDescriptor
RSharedDescriptorGuard(const RSharedDescriptorGuard &)=delete
RSharedDescriptorGuard(RSharedDescriptorGuard &&)=delete
RSharedDescriptorGuard(const RNTupleDescriptor &desc, std::shared_mutex &lock)
~RSharedDescriptorGuard()
RSharedDescriptorGuard & operator=(const RSharedDescriptorGuard &)=delete
Abstract interface to read data from an ntuple.
virtual void LoadSealedPage(DescriptorId_t physicalColumnId, RClusterIndex clusterIndex, RSealedPage &sealedPage)=0
Read the packed and compressed bytes of a page into the memory buffer provided by sealedPage.
virtual void LoadStructureImpl()=0
RPagePool fPagePool
Pages that are unzipped with IMT are staged into the page pool.
EPageStorageType GetType() final
Whether the concrete implementation is a sink or a source.
RPageSource(const RPageSource &)=delete
RPageSource & operator=(RPageSource &&)=delete
std::shared_mutex fDescriptorLock
RNTupleReadOptions fOptions
std::unique_ptr< RCounters > fCounters
RNTupleDescriptor fDescriptor
RExclDescriptorGuard GetExclDescriptorGuard()
Note that the underlying lock is not recursive. See GetSharedDescriptorGuard() for further informatio...
RActivePhysicalColumns fActivePhysicalColumns
The active columns are implicitly defined by the model fields or views.
RPageSource & operator=(const RPageSource &)=delete
virtual RNTupleDescriptor AttachImpl()=0
LoadStructureImpl() has been called before AttachImpl() is called
RPageSource(RPageSource &&)=delete
const RNTupleReadOptions & GetReadOptions() const
virtual std::vector< std::unique_ptr< RCluster > > LoadClusters(std::span< RCluster::RKey > clusterKeys)=0
Populates all the pages of the given cluster ids and columns; it is possible that some columns do not...
REntryRange fEntryRange
Used by the cluster pool to prevent reading beyond the given range.
virtual RPageRef LoadPageImpl(ColumnHandle_t columnHandle, const RClusterInfo &clusterInfo, ClusterSize_t::ValueType idxInCluster)=0
virtual std::unique_ptr< RPageSource > CloneImpl() const =0
Returns a new, unattached page source for the same data set.
REntryRange GetEntryRange() const
std::map< NTupleSize_t, DescriptorId_t > fPreloadedClusters
Clusters from where pages got preloaded in UnzipClusterImpl(), ordered by first entry number of the c...
const RSharedDescriptorGuard GetSharedDescriptorGuard() const
Takes the read lock for the descriptor.
The interface of a task scheduler to schedule page (de)compression tasks.
virtual ~RTaskScheduler()=default
virtual void Wait()=0
Blocks until all scheduled tasks finished.
virtual void AddTask(const std::function< void(void)> &taskFunc)=0
Take a callable that represents a task.
Common functionality of an ntuple storage for both reading and writing.
std::deque< RSealedPage > SealedPageSequence_t
std::unique_ptr< RPageAllocator > fPageAllocator
For the time being, we will use the heap allocator for all sources and sinks. This may change in the ...
virtual ColumnHandle_t AddColumn(DescriptorId_t fieldId, RColumn &column)=0
Register a new column.
static constexpr std::size_t kNBytesPageChecksum
The page checksum is a 64bit xxhash3.
virtual void DropColumn(ColumnHandle_t columnHandle)=0
Unregisters a column.
virtual Detail::RNTupleMetrics & GetMetrics()
Returns the default metrics object.
RTaskScheduler * fTaskScheduler
const std::string & GetNTupleName() const
Returns the NTuple name.
virtual EPageStorageType GetType()=0
Whether the concrete implementation is a sink or a source.
RPageStorage & operator=(RPageStorage &&other)=default
RPageStorage & operator=(const RPageStorage &other)=delete
RPageStorage(const RPageStorage &other)=delete
RPageStorage(RPageStorage &&other)=default
void SetTaskScheduler(RTaskScheduler *taskScheduler)
RColumnHandle ColumnHandle_t
The column handle identifies a column with the current open page storage.
ColumnId_t GetColumnId(ColumnHandle_t columnHandle) const
Detail::RNTupleMetrics fMetrics
A page is a slice of a column that is mapped into memory.
Helper to maintain a memory budget for the write pages of a set of columns.
bool TryUpdate(RColumn &column, std::size_t newWritePageSize)
Try to register the new write page size for the given column.
std::size_t fCurrentAllocatedBytes
Sum of all the write page sizes (their capacity) of the columns in fColumnsSortedByPageSize
bool TryEvict(std::size_t targetAvailableSize, std::size_t pageSizeLimit)
Flush columns in order of allocated write page size until the sum of all write page allocations leave...
RWritePageMemoryManager(std::size_t maxAllocatedBytes)
std::size_t fMaxAllocatedBytes
Maximum allowed value for fCurrentAllocatedBytes, set from RNTupleWriteOptions::fPageBufferBudget.
std::set< RColumnInfo, std::greater< RColumnInfo > > fColumnsSortedByPageSize
All columns that called ReservePage() (hence TryUpdate()) at least once, sorted by their current writ...
Meta-data for a set of ntuple clusters.
Addresses a column element or field item relative to a particular cluster, instead of a global NTuple...
Base class for all ROOT issued exceptions.
The on-storage meta-data of an ntuple.
The RNTupleModel encapulates the schema of an ntuple.
Common user-tunable settings for reading ntuples.
Common user-tunable settings for storing ntuples.
The class is used as a return type for operations that can fail; wraps a value of type T or an RError...
std::uint64_t NTupleSize_t
Integer type long enough to hold the maximum number of entries in a column.
std::uint64_t DescriptorId_t
Distriniguishes elements of the same type within a descriptor, e.g. different fields.
constexpr NTupleSize_t kInvalidNTupleIndex
std::int64_t ColumnId_t
Uniquely identifies a physical column within the scope of the current process, used to tag pages.
constexpr ClusterSize_t kInvalidClusterIndex(std::uint64_t(-1))
constexpr DescriptorId_t kInvalidDescriptorId
tbb::task_arena is an alias of tbb::interface7::task_arena, which doesn't allow to forward declare tb...
The identifiers that specifies the content of a (partial) cluster.
Every concrete RColumnElement type is identified by its on-disk type (column type) and the in-memory ...
The incremental changes to a RNTupleModel
Default I/O performance counters that get registered in fMetrics.
Detail::RNTupleAtomicCounter & fSzZip
Detail::RNTupleAtomicCounter & fTimeWallZip
Detail::RNTupleTickCounter< Detail::RNTupleAtomicCounter > & fTimeCpuZip
Detail::RNTupleAtomicCounter & fSzWritePayload
Detail::RNTupleTickCounter< Detail::RNTupleAtomicCounter > & fTimeCpuWrite
Detail::RNTupleAtomicCounter & fTimeWallWrite
Detail::RNTupleAtomicCounter & fNPageCommitted
Set of optional features supported by the persistent sink.
Parameters for the SealPage() method.
const RColumnElementBase * fElement
Corresponds to the page's elements, for size calculation etc.
void * fBuffer
Location for sealed output. The memory buffer has to be large enough.
bool fAllowAlias
If false, the output buffer must not point to the input page buffer, which would otherwise be an opti...
int fCompressionSetting
Compression algorithm and level to apply.
bool fWriteChecksum
Adds a 8 byte little-endian xxhash3 checksum to the page payload.
const RPage * fPage
Input page to be sealed.
RClusterDescriptor::RPageRange fPageRange
Cluster that was staged, but not yet logically appended to the RNTuple.
std::uint64_t fNBytesWritten
std::vector< RColumnInfo > fColumnInfos
RColumnElementBase::RIdentifier fElementId
Summarizes cluster-level information that are necessary to load a certain page.
RClusterDescriptor::RPageRange::RPageInfoExtended fPageInfo
Location of the page on disk.
Default I/O performance counters that get registered in fMetrics
Detail::RNTupleTickCounter< Detail::RNTupleAtomicCounter > & fTimeCpuUnzip
Detail::RNTupleAtomicCounter & fNPageRead
Detail::RNTupleAtomicCounter & fSzReadPayload
Detail::RNTupleAtomicCounter & fTimeWallUnzip
Detail::RNTupleCalcPerf & fBandwidthReadCompressed
Detail::RNTupleAtomicCounter & fNRead
Detail::RNTupleTickCounter< Detail::RNTupleAtomicCounter > & fTimeCpuRead
Detail::RNTupleAtomicCounter & fNClusterLoaded
Detail::RNTupleAtomicCounter & fNReadV
Detail::RNTupleAtomicCounter & fNPageUnsealed
Detail::RNTupleAtomicCounter & fSzUnzip
Detail::RNTupleCalcPerf & fBandwidthReadUncompressed
Detail::RNTupleCalcPerf & fFractionReadOverhead
Detail::RNTupleAtomicCounter & fSzReadOverhead
Detail::RNTupleAtomicCounter & fTimeWallRead
Detail::RNTupleCalcPerf & fCompressionRatio
Detail::RNTupleCalcPerf & fBandwidthUnzip
Used in SetEntryRange / GetEntryRange.
DescriptorId_t fPhysicalId
A range of sealed pages referring to the same column that can be used for vector commit.
SealedPageSequence_t::const_iterator fLast
SealedPageSequence_t::const_iterator fFirst
RSealedPageGroup()=default
DescriptorId_t fPhysicalColumnId
RSealedPageGroup(DescriptorId_t d, SealedPageSequence_t::const_iterator b, SealedPageSequence_t::const_iterator e)
A sealed page contains the bytes of a page as written to storage (packed & compressed).
const void * GetBuffer() const
void SetHasChecksum(bool hasChecksum)
void SetNElements(std::uint32_t nElements)
void SetBuffer(const void *buffer)
void SetBufferSize(std::size_t bufferSize)
RResult< void > VerifyChecksumIfEnabled() const
RResult< std::uint64_t > GetChecksum() const
Returns a failure if the sealed page has no checksum.
bool fHasChecksum
If set, the last 8 bytes of the buffer are the xxhash of the rest of the buffer.
std::uint32_t GetNElements() const
RSealedPage(RSealedPage &&other)=default
std::size_t fBufferSize
Size of the page payload and the trailing checksum (if available)
std::size_t GetBufferSize() const
bool GetHasChecksum() const
RSealedPage(const RSealedPage &other)=default
RSealedPage(const void *buffer, std::size_t bufferSize, std::uint32_t nElements, bool hasChecksum=false)
RSealedPage & operator=(const RSealedPage &other)=default
std::size_t GetDataSize() const
RSealedPage & operator=(RSealedPage &&other)=default
std::size_t fCurrentPageSize
std::size_t fInitialPageSize
bool operator>(const RColumnInfo &other) const
Wrap the integer in a struct in order to avoid template specialization clash with std::uint64_t.
Generic information about the physical location of data.