Interface for iterating over entries of vertically ("chained") and/or horizontally ("joined") combined RNTuples.
Example usage (see ntpl012_processor_chain.C and ntpl015_processor_join.C for bigger examples):
An RNTupleProcessor is created either:
The RNTupleProcessor provides an iterator which gives access to the index of the current global entry of the processor, i.e. taking into account previously processed RNTuples.
Because the schemas of each RNTuple that are part of an RNTupleProcessor may not necessarily be identical, or because it can occur that entries are only partially complete in a join-based processor, field values may be marked as "invalid", at which point their data should not be read. This is handled by the RNTupleProcessorOptionalPtr that is returned by RequestField().
Definition at line 341 of file RNTupleProcessor.hxx.
Classes | |
| class | REntryMapping |
| Maps a processor's global (outer) entry index to its inner ones. More... | |
| class | RIterator |
| Iterator over the entries of an RNTuple, or vertical concatenation thereof. More... | |
Public Member Functions | |
| RNTupleProcessor (const RNTupleProcessor &)=delete | |
| RNTupleProcessor (RNTupleProcessor &&)=delete | |
| virtual | ~RNTupleProcessor ()=default |
| RIterator | begin () |
| RIterator | end () |
| ROOT::NTupleSize_t | GetNEntriesProcessed () const |
| Get the total number of entries processed so far. | |
| const RNTupleProcessorOptions & | GetOptions () const |
| Get the options used for this processor. | |
| void | LoadEntry (const REntryMapping &mapping) |
| Load the entry identified by the entry mapping. | |
| RNTupleProcessor & | operator= (const RNTupleProcessor &)=delete |
| RNTupleProcessor & | operator= (RNTupleProcessor &&)=delete |
| void | PrintStructure (std::ostream &output=std::cout) |
| Print a graphical representation of the processor composition. | |
| RNTupleProcessorOptionalPtr< void > | RequestField (const std::string &fieldName, const std::string &typeName, void *valuePtr=nullptr) |
| Request access to a field for reading during processing. | |
| template<typename T > | |
| RNTupleProcessorOptionalPtr< T > | RequestField (const std::string &fieldName, void *valuePtr=nullptr) |
| Request access to a field for reading during processing. | |
Static Public Member Functions | |
| static std::unique_ptr< RNTupleProcessor > | Create (RNTupleOpenSpec ntuple, const RNTupleProcessorOptions &opts=RNTupleProcessorOptions()) |
| Create an RNTupleProcessor for a single RNTuple. | |
| static std::unique_ptr< RNTupleProcessor > | CreateChain (std::vector< RNTupleOpenSpec > ntuples, const RNTupleProcessorOptions &opts=RNTupleProcessorOptions()) |
| Create an RNTupleProcessor for a chain (i.e., a vertical combination) of RNTuples. | |
| static std::unique_ptr< RNTupleProcessor > | CreateChain (std::vector< std::unique_ptr< RNTupleProcessor > > innerProcessors, const RNTupleProcessorOptions &opts=RNTupleProcessorOptions()) |
| Create an RNTupleProcessor for a chain (i.e., a vertical combination) of other RNTupleProcessors. | |
Protected Member Functions | |
| RNTupleProcessor (const RNTupleProcessorOptions &options) | |
| Create a new base RNTupleProcessor. | |
| virtual void | AddAllFieldsToEntry (const Internal::RNTupleProcessorProvenance &provenance, bool includeSubfields)=0 |
| Add all known fields (from on-disk information) to the entry. | |
| virtual void | AddEntriesToJoinTable (Internal::RNTupleJoinTable &joinTable, ROOT::NTupleSize_t entryOffset=0)=0 |
| Add the entry mappings for this processor to the provided join table. | |
| virtual Internal::RNTupleProcessorEntry::FieldIndex_t | AddFieldToEntry (const std::string &canonicalFieldName, const std::string &typeName, void *valuePtr, const Internal::RNTupleProcessorProvenance &provenance)=0 |
| Add a field to the entry. | |
| virtual Internal::RNTupleProcessorEntry::FieldIndex_t | AddFieldToEntry (std::unique_ptr< ROOT::RFieldBase > field, const std::string &canonicalFieldName, void *valuePtr, const Internal::RNTupleProcessorProvenance &provenance)=0 |
| Add a field to the entry. | |
| virtual bool | CanReadFieldFromDisk (std::string_view fieldName)=0 |
| Check if a field exists on-disk and can be read by the processor. | |
| virtual void | Connect (const std::unordered_set< Internal::RNTupleProcessorEntry::FieldIndex_t > &fieldIdxs, const Internal::RNTupleProcessorProvenance &provenance, bool updateFields)=0 |
| Connect fields to the page source of the processor's underlying RNTuple(s). | |
| virtual void | Disconnect ()=0 |
| Disconnect the processor from associated physical storage. | |
| Internal::RNTupleProcessorEntry & | GetEntry () |
| Get a reference to the processor's internal entry. | |
| const Internal::RNTupleProcessorEntry & | GetEntry () const |
| Get a reference to the processor's internal entry. | |
| virtual ROOT::NTupleSize_t | GetNEntries ()=0 |
| Get the total number of entries in this processor. | |
| void | IncrementEntryMapping (REntryMapping &mapping) |
| Increment the local entry mapping by one. | |
| virtual void | Initialize (std::shared_ptr< Internal::RNTupleProcessorEntry > entry)=0 |
Initialize the processor by creating an (initially empty) fEntry, or setting an existing one. | |
| bool | IsInitialized () const |
| Check if the processor already has been initialized. | |
| virtual void | LoadEntryImpl (const REntryMapping &mapping)=0 |
| Load the entry identified by the entry mapping. | |
| virtual void | PrintStructureImpl (std::ostream &output) const =0 |
| Processor-specific implementation for printing its structure, called by PrintStructure(). | |
| virtual void | SetEntryMapping (ROOT::NTupleSize_t globalEntryNumber, REntryMapping &mapping)=0 |
| Set the local entry mapping (for nested processors), according to a global entry number. | |
Protected Attributes | |
| std::shared_ptr< Internal::RNTupleProcessorEntry > | fEntry = nullptr |
| std::unordered_set< Internal::RNTupleProcessorEntry::FieldIndex_t > | fFieldIdxs |
| ROOT::NTupleSize_t | fNEntries = kInvalidNTupleIndex |
| Total number of entries. | |
| ROOT::NTupleSize_t | fNEntriesProcessed = 0 |
| RNTupleProcessorOptions | fOptions |
Friends | |
| class | Internal::RDF::RNTupleProcessorDS |
| class | RNTupleChainProcessor |
| class | RNTupleJoinProcessor |
| class | RNTupleSingleProcessor |
| const Internal::RNTupleProcessorEntry * | ROOT::Experimental::Internal::LoadFullRNTupleProcessorEntry (RNTupleProcessor &processor, bool includeSubfields) |
| struct | ROOT::Experimental::Internal::RNTupleProcessorEntryLoader |
#include <ROOT/RNTupleProcessor.hxx>
|
inlineprotected |
Create a new base RNTupleProcessor.
| [in] | processorName | Name of the processor. By default, this is the name of the underlying RNTuple for RNTupleSingleProcessor, the name of the first processor for RNTupleChainProcessor, or the name of the primary RNTuple for RNTupleJoinProcessor. |
Definition at line 567 of file RNTupleProcessor.hxx.
|
delete |
|
delete |
|
virtualdefault |
|
protectedpure virtual |
Add all known fields (from on-disk information) to the entry.
| [in] | provenance | Provenance of the processor. |
| [in] | addFieldMode | Bitfield indicating how the fields should be added. |
Implemented in ROOT::Experimental::RNTupleSingleProcessor, ROOT::Experimental::RNTupleChainProcessor, and ROOT::Experimental::RNTupleJoinProcessor.
|
protectedpure virtual |
Add the entry mappings for this processor to the provided join table.
| [in] | joinTable | the join table to map the entries to. |
| [in] | entryOffset | In case the entry mapping is added from a chain, the offset of the entry indexes to use with respect to the processor's position in the chain. |
Implemented in ROOT::Experimental::RNTupleSingleProcessor, ROOT::Experimental::RNTupleChainProcessor, and ROOT::Experimental::RNTupleJoinProcessor.
|
protectedpure virtual |
Add a field to the entry.
| [in] | canonicalFieldName | Canonical name of the field to add. This includes the prefix of any parent fields, as well as the auxiliary processor name prefix, if present. |
| [in] | typeName | Type of the field to add. |
| [in] | valuePtr | Pointer to bind to the field's value in the entry. If this is a nullptr, a pointer will be created. |
| [in] | provenance | Provenance of the processor. |
In case the field was already present in the entry, the index of the existing field is returned.
Implemented in ROOT::Experimental::RNTupleSingleProcessor, ROOT::Experimental::RNTupleChainProcessor, and ROOT::Experimental::RNTupleJoinProcessor.
|
protectedpure virtual |
Add a field to the entry.
| [in] | field | The field to add. |
| [in] | canonicalFieldName | Canonical name of the field to add. This includes the prefix of any parent fields, as well as the auxiliary processor name prefix, if present. This is different from the field name stored in field. |
| [in] | valuePtr | Pointer to bind to the field's value in the entry. If this is a nullptr, a pointer will be created. |
| [in] | provenance | Provenance of the processor. |
In case the field was already present in the entry, the index of the existing field is returned.
Implemented in ROOT::Experimental::RNTupleSingleProcessor, ROOT::Experimental::RNTupleChainProcessor, and ROOT::Experimental::RNTupleJoinProcessor.
|
inline |
Definition at line 731 of file RNTupleProcessor.hxx.
|
protectedpure virtual |
Check if a field exists on-disk and can be read by the processor.
| [in] | fieldName | Name of the field to check. |
Implemented in ROOT::Experimental::RNTupleSingleProcessor, ROOT::Experimental::RNTupleChainProcessor, and ROOT::Experimental::RNTupleJoinProcessor.
|
protectedpure virtual |
Connect fields to the page source of the processor's underlying RNTuple(s).
| [in] | fieldIdxs | Indices of the fields to connect. |
| [in] | provenance | Provenance of the processor. |
| [in] | updateFields | Whether the fields in the entry need to be updated, because the current underlying RNTuple source changed. |
Implemented in ROOT::Experimental::RNTupleSingleProcessor, ROOT::Experimental::RNTupleChainProcessor, and ROOT::Experimental::RNTupleJoinProcessor.
|
static |
Create an RNTupleProcessor for a single RNTuple.
| [in] | ntuple | The name and storage location of the RNTuple to process. |
| [in] | opts | Options for the processor. |
Definition at line 46 of file RNTupleProcessor.cxx.
|
static |
Create an RNTupleProcessor for a chain (i.e., a vertical combination) of RNTuples.
| [in] | ntuples | A list specifying the names and locations of the RNTuples to process. |
| [in] | opts | Options for the processor. |
Definition at line 52 of file RNTupleProcessor.cxx.
|
static |
Create an RNTupleProcessor for a chain (i.e., a vertical combination) of other RNTupleProcessors.
| [in] | innerProcessors | A list with the processors to chain. |
| [in] | opts | Options for the processor. |
Definition at line 69 of file RNTupleProcessor.cxx.
|
protectedpure virtual |
Disconnect the processor from associated physical storage.
Implemented in ROOT::Experimental::RNTupleSingleProcessor, ROOT::Experimental::RNTupleChainProcessor, and ROOT::Experimental::RNTupleJoinProcessor.
|
inline |
Definition at line 732 of file RNTupleProcessor.hxx.
|
inlineprotected |
Get a reference to the processor's internal entry.
Definition at line 487 of file RNTupleProcessor.hxx.
|
inlineprotected |
Get a reference to the processor's internal entry.
Definition at line 491 of file RNTupleProcessor.hxx.
|
protectedpure virtual |
Get the total number of entries in this processor.
Implemented in ROOT::Experimental::RNTupleSingleProcessor, ROOT::Experimental::RNTupleChainProcessor, and ROOT::Experimental::RNTupleJoinProcessor.
|
inline |
Get the total number of entries processed so far.
Definition at line 582 of file RNTupleProcessor.hxx.
|
inline |
Get the options used for this processor.
Definition at line 578 of file RNTupleProcessor.hxx.
|
inlineprotected |
Increment the local entry mapping by one.
| [in] | mapping | Entry mapping to increment |
Definition at line 477 of file RNTupleProcessor.hxx.
|
protectedpure virtual |
Initialize the processor by creating an (initially empty) fEntry, or setting an existing one.
Implemented in ROOT::Experimental::RNTupleSingleProcessor, ROOT::Experimental::RNTupleChainProcessor, and ROOT::Experimental::RNTupleJoinProcessor.
|
inlineprotected |
Check if the processor already has been initialized.
Definition at line 450 of file RNTupleProcessor.hxx.
|
inline |
Load the entry identified by the entry mapping.
| [in] | mapping | Mapping to the entry to load |
Definition at line 654 of file RNTupleProcessor.hxx.
|
protectedpure virtual |
Load the entry identified by the entry mapping.
| [in] | mapping | Mapping to the entry to load |
Implemented in ROOT::Experimental::RNTupleSingleProcessor, ROOT::Experimental::RNTupleChainProcessor, and ROOT::Experimental::RNTupleJoinProcessor.
|
delete |
|
delete |
|
inline |
Print a graphical representation of the processor composition.
| [in,out] | output | Stream to print to (default is stdout). |
The structure of a processor representing a join between a single primary RNTuple and a chain of two auxiliary RNTuples will be printed as follows:
Definition at line 674 of file RNTupleProcessor.hxx.
|
protectedpure virtual |
Processor-specific implementation for printing its structure, called by PrintStructure().
| [in,out] | output | Output stream to print to. |
Implemented in ROOT::Experimental::RNTupleSingleProcessor, ROOT::Experimental::RNTupleChainProcessor, and ROOT::Experimental::RNTupleJoinProcessor.
|
inline |
Request access to a field for reading during processing.
| [in] | fieldName | Name of the requested field. |
| [in] | typeName | Type of the requested field. |
| [in] | valuePtr | Pointer to bind to the field's value in the entry. If this is a nullptr, a pointer will be created. |
valuePtr with care! Values may not always be valid for every entry during processing, for example when a field is not present in one of the chained processors or when during a join operation, no matching entry in the auxiliary processor can be found. Reading valuePtr as-is therefore comes with the risk of reading invalid data. After passing a pointer to RequestField, we strongly recommend only accessing its data through the interface of the returned RNTupleProcessorOptionalPtr, to ensure that only valid data can be read. Definition at line 643 of file RNTupleProcessor.hxx.
|
inline |
Request access to a field for reading during processing.
| T | Type of the requested field. |
| [in] | fieldName | Name of the requested field. |
| [in] | valuePtr | Pointer to bind to the field's value in the entry. If this is a nullptr, a pointer will be created. |
T, which provides access to the field's value.valuePtr with care! Values may not always be valid for every entry during processing, for example when a field is not present in one of the chained processors or when during a join operation, no matching entry in the auxiliary processor can be found. Reading valuePtr as-is therefore comes with the risk of reading invalid data. After passing a pointer to RequestField, we strongly recommend only accessing its data through the interface of the returned RNTupleProcessorOptionalPtr, to ensure that only valid data can be read. Definition at line 601 of file RNTupleProcessor.hxx.
|
protectedpure virtual |
Set the local entry mapping (for nested processors), according to a global entry number.
| [in] | entryNumber | Global entry number to map to |
| [in] | mapping | Entry mapping to update |
Implemented in ROOT::Experimental::RNTupleSingleProcessor, ROOT::Experimental::RNTupleChainProcessor, and ROOT::Experimental::RNTupleJoinProcessor.
|
friend |
Definition at line 349 of file RNTupleProcessor.hxx.
|
friend |
Definition at line 347 of file RNTupleProcessor.hxx.
|
friend |
Definition at line 348 of file RNTupleProcessor.hxx.
|
friend |
Definition at line 346 of file RNTupleProcessor.hxx.
|
friend |
|
friend |
Definition at line 342 of file RNTupleProcessor.hxx.
|
protected |
Definition at line 435 of file RNTupleProcessor.hxx.
|
protected |
Definition at line 436 of file RNTupleProcessor.hxx.
|
protected |
Total number of entries.
Only to be used internally by the processor, not meant to be exposed in the public interface.
Definition at line 440 of file RNTupleProcessor.hxx.
|
protected |
Definition at line 442 of file RNTupleProcessor.hxx.
|
protected |
Definition at line 433 of file RNTupleProcessor.hxx.