Reads RNTuple data from storage.
The RNTupleReader provides access to data stored in the RNTuple binary format as C++ objects, using an RNTupleModel. It infers this model from the RNTuple's on-disk metadata, or uses a model imposed by the user. The latter case allows users to read into a specialized RNTuple model that covers only a subset of the fields in the RNTuple. The RNTuple model is used when reading complete entries through LoadEntry(). Individual fields can be read as well by instantiating a tree view.
Definition at line 66 of file RNTupleReader.hxx.
Classes | |
class | RIterator |
Public Member Functions | |
~RNTupleReader () | |
RIterator | begin () |
std::unique_ptr< RNTupleReader > | Clone () |
std::unique_ptr< ROOT::REntry > | CreateEntry () |
void | EnableMetrics () |
Enable performance measurements (decompression time, bytes read from storage, etc.) | |
RIterator | end () |
ROOT::RNTupleCollectionView | GetCollectionView (ROOT::DescriptorId_t fieldId) |
Provides access to a collection field from its on-disk ID, that can itself generate new RNTupleViews for its nested fields. | |
ROOT::RNTupleCollectionView | GetCollectionView (std::string_view fieldName) |
Provides access to a collection field, that can itself generate new RNTupleViews for its nested fields. | |
const ROOT::RNTupleDescriptor & | GetDescriptor () |
Returns a cached copy of the page source descriptor. | |
template<typename T > | |
ROOT::RNTupleDirectAccessView< T > | GetDirectAccessView (ROOT::DescriptorId_t fieldId) |
Provides direct access to the I/O buffers of a mappable (sub)field from its on-disk ID. | |
template<typename T > | |
ROOT::RNTupleDirectAccessView< T > | GetDirectAccessView (std::string_view fieldName) |
Provides direct access to the I/O buffers of a mappable (sub)field. | |
ROOT::RNTupleGlobalRange | GetEntryRange () |
Returns an iterator over the entry indices of the RNTuple. | |
const Experimental::Detail::RNTupleMetrics & | GetMetrics () const |
const ROOT::RNTupleModel & | GetModel () |
ROOT::NTupleSize_t | GetNEntries () const |
template<typename T > | |
ROOT::RNTupleView< T > | GetView (ROOT::DescriptorId_t fieldId) |
Provides access to an individual (sub)field from its on-disk ID. | |
template<typename T > | |
ROOT::RNTupleView< T > | GetView (ROOT::DescriptorId_t fieldId, std::shared_ptr< T > objPtr) |
Provides access to an individual (sub)field from its on-disk ID, reading its values into objPtr . | |
template<typename T > | |
ROOT::RNTupleView< T > | GetView (ROOT::DescriptorId_t fieldId, T *rawPtr) |
Provides access to an individual (sub)field from its on-disk ID, reading its values into rawPtr . | |
ROOT::RNTupleView< void > | GetView (ROOT::DescriptorId_t fieldId, void *rawPtr, const std::type_info &ti) |
Provides access to an individual (sub)field from its on-disk ID, reading its values into objPtr as the type provided by ti . | |
ROOT::RNTupleView< void > | GetView (ROOT::DescriptorId_t fieldId, void *rawPtr, std::string_view typeName) |
Provides access to an individual (sub)field from its on-disk ID, reading its values into rawPtr as the type provided by typeName . | |
template<typename T > | |
ROOT::RNTupleView< T > | GetView (std::string_view fieldName) |
Provides access to an individual (sub)field, e.g. | |
template<typename T > | |
ROOT::RNTupleView< T > | GetView (std::string_view fieldName, std::shared_ptr< T > objPtr) |
Provides access to an individual (sub)field, reading its values into objPtr . | |
template<typename T > | |
ROOT::RNTupleView< T > | GetView (std::string_view fieldName, T *rawPtr) |
Provides access to an individual (sub)field, reading its values into rawPtr . | |
ROOT::RNTupleView< void > | GetView (std::string_view fieldName, void *rawPtr, const std::type_info &ti) |
Provides access to an individual (sub)field, reading its values into rawPtr as the type provided by ti . | |
ROOT::RNTupleView< void > | GetView (std::string_view fieldName, void *rawPtr, std::string_view typeName) |
Provides access to an individual (sub)field, reading its values into rawPtr as the type provided by typeName . | |
void | LoadEntry (ROOT::NTupleSize_t index) |
Fills the default entry of the model. | |
void | LoadEntry (ROOT::NTupleSize_t index, ROOT::REntry &entry) |
Fills a user provided entry after checking that the entry has been instantiated from the RNTuple model. | |
void | PrintInfo (const ENTupleInfo what=ENTupleInfo::kSummary, std::ostream &output=std::cout) const |
Prints a detailed summary of the RNTuple, including a list of fields. | |
void | Show (ROOT::NTupleSize_t index, std::ostream &output=std::cout) |
Shows the values of the i-th entry/row, starting with 0 for the first entry. | |
Private Member Functions | |
RNTupleReader (std::unique_ptr< Internal::RPageSource > source, const ROOT::RNTupleReadOptions &options) | |
The model is generated from the RNTuple metadata on storage. | |
RNTupleReader (std::unique_ptr< ROOT::RNTupleModel > model, std::unique_ptr< Internal::RPageSource > source, const ROOT::RNTupleReadOptions &options) | |
void | ConnectModel (ROOT::RNTupleModel &model) |
RNTupleReader * | GetDisplayReader () |
void | InitPageSource (bool enableMetrics) |
ROOT::DescriptorId_t | RetrieveFieldId (std::string_view fieldName) const |
Private Attributes | |
std::optional< ROOT::RNTupleDescriptor > | fCachedDescriptor |
The RNTuple descriptor in the page source is protected by a read-write lock. | |
std::optional< ROOT::RNTupleDescriptor::RCreateModelOptions > | fCreateModelOptions |
If not nullopt, these will be used when creating the model. | |
std::unique_ptr< RNTupleReader > | fDisplayReader |
We use a dedicated on-demand reader for Show(). | |
Experimental::Detail::RNTupleMetrics | fMetrics |
std::unique_ptr< ROOT::RNTupleModel > | fModel |
Needs to be destructed before fSource. | |
std::unique_ptr< Internal::RPageSource > | fSource |
std::unique_ptr< Internal::RPageStorage::RTaskScheduler > | fUnzipTasks |
Set as the page source's scheduler for parallel page decompression if implicit multi-threading (IMT) is on. | |
#include <ROOT/RNTupleReader.hxx>
|
private |
Definition at line 58 of file RNTupleReader.cxx.
|
explicitprivate |
The model is generated from the RNTuple metadata on storage.
Definition at line 73 of file RNTupleReader.cxx.
|
default |
|
inline |
Definition at line 423 of file RNTupleReader.hxx.
|
inline |
Definition at line 166 of file RNTupleReader.hxx.
|
private |
Definition at line 25 of file RNTupleReader.cxx.
std::unique_ptr< ROOT::REntry > ROOT::RNTupleReader::CreateEntry | ( | ) |
Definition at line 143 of file RNTupleReader.cxx.
|
inline |
Enable performance measurements (decompression time, bytes read from storage, etc.)
Example: inspect the reader metrics after loading every entry
Definition at line 442 of file RNTupleReader.hxx.
|
inline |
Definition at line 424 of file RNTupleReader.hxx.
|
inline |
Provides access to a collection field from its on-disk ID, that can itself generate new RNTupleViews for its nested fields.
Definition at line 418 of file RNTupleReader.hxx.
|
inline |
Provides access to a collection field, that can itself generate new RNTupleViews for its nested fields.
Raises an exception if:
Definition at line 404 of file RNTupleReader.hxx.
const ROOT::RNTupleDescriptor & ROOT::RNTupleReader::GetDescriptor | ( | ) |
Returns a cached copy of the page source descriptor.
The returned pointer remains valid until the next call to LoadEntry() or to any of the views returned from the reader.
Definition at line 248 of file RNTupleReader.cxx.
|
inline |
Provides direct access to the I/O buffers of a mappable (sub)field from its on-disk ID.
Definition at line 390 of file RNTupleReader.hxx.
|
inline |
Provides direct access to the I/O buffers of a mappable (sub)field.
Raises an exception if there is no field with the given name. Attempting to access the values of a direct-access view for non-mappable fields will yield compilation errors.
Definition at line 381 of file RNTupleReader.hxx.
|
private |
Definition at line 219 of file RNTupleReader.cxx.
|
inline |
Returns an iterator over the entry indices of the RNTuple.
Example: iterate over all entries and print each entry in JSON format
Definition at line 244 of file RNTupleReader.hxx.
|
inline |
Definition at line 443 of file RNTupleReader.hxx.
const ROOT::RNTupleModel & ROOT::RNTupleReader::GetModel | ( | ) |
Definition at line 133 of file RNTupleReader.cxx.
|
inline |
Definition at line 174 of file RNTupleReader.hxx.
|
inline |
Provides access to an individual (sub)field from its on-disk ID.
Definition at line 325 of file RNTupleReader.hxx.
|
inline |
Provides access to an individual (sub)field from its on-disk ID, reading its values into objPtr
.
Definition at line 336 of file RNTupleReader.hxx.
|
inline |
Provides access to an individual (sub)field from its on-disk ID, reading its values into rawPtr
.
Definition at line 347 of file RNTupleReader.hxx.
|
inline |
Provides access to an individual (sub)field from its on-disk ID, reading its values into objPtr
as the type provided by ti
.
Definition at line 369 of file RNTupleReader.hxx.
|
inline |
Provides access to an individual (sub)field from its on-disk ID, reading its values into rawPtr
as the type provided by typeName
.
Definition at line 358 of file RNTupleReader.hxx.
|
inline |
Provides access to an individual (sub)field, e.g.
GetView<Particle>("particle")
, GetView<double>("particle.pt")
or GetView<std::vector<Particle>>("particles")
. It is possible to directly get the size of a collection (without reading the collection itself) using RNTupleCardinality: GetView<ROOT::RNTupleCardinality<std::uint64_t>>("particles")
.
Raises an exception if there is no field with the given name.
Example: iterate over a field named "pt" of type float
Definition at line 267 of file RNTupleReader.hxx.
|
inline |
Provides access to an individual (sub)field, reading its values into objPtr
.
Raises an exception if there is no field with the given name.
Example: iterate over a field named "pt" of type float
Definition at line 291 of file RNTupleReader.hxx.
|
inline |
Provides access to an individual (sub)field, reading its values into rawPtr
.
Definition at line 300 of file RNTupleReader.hxx.
|
inline |
Provides access to an individual (sub)field, reading its values into rawPtr
as the type provided by ti
.
Definition at line 316 of file RNTupleReader.hxx.
|
inline |
Provides access to an individual (sub)field, reading its values into rawPtr
as the type provided by typeName
.
Definition at line 308 of file RNTupleReader.hxx.
|
private |
Definition at line 43 of file RNTupleReader.cxx.
|
inline |
Fills the default entry of the model.
Raises an exception when index
is greater than the number of entries present in the RNTuple
Definition at line 213 of file RNTupleReader.hxx.
|
inline |
Fills a user provided entry after checking that the entry has been instantiated from the RNTuple model.
Definition at line 224 of file RNTupleReader.hxx.
|
static |
Definition at line 98 of file RNTupleReader.cxx.
|
static |
Definition at line 124 of file RNTupleReader.cxx.
|
static |
The caller imposes the way the model is reconstructed.
Definition at line 113 of file RNTupleReader.cxx.
|
static |
Open an RNTuple for reading.
Throws an RException if there is no RNTuple with the given name.
Example: open an RNTuple and print the number of entries
Definition at line 90 of file RNTupleReader.cxx.
|
static |
Definition at line 104 of file RNTupleReader.cxx.
|
static |
The caller imposes a model, which must be compatible with the model found in the data on storage.
Definition at line 82 of file RNTupleReader.cxx.
void ROOT::RNTupleReader::PrintInfo | ( | const ENTupleInfo | what = ENTupleInfo::kSummary, |
std::ostream & | output = std::cout ) const |
Prints a detailed summary of the RNTuple, including a list of fields.
Example: print summary information to stdout
Example: print detailed column storage data to stderr
For use of ENTupleInfo::kMetrics, see EnableMetrics.
Definition at line 148 of file RNTupleReader.cxx.
|
private |
Definition at line 256 of file RNTupleReader.cxx.
void ROOT::RNTupleReader::Show | ( | ROOT::NTupleSize_t | index, |
std::ostream & | output = std::cout ) |
Shows the values of the i-th entry/row, starting with 0 for the first entry.
By default, prints the output in JSON format. Uses the visitor pattern to traverse through each field of the given entry.
Definition at line 226 of file RNTupleReader.cxx.
|
private |
The RNTuple descriptor in the page source is protected by a read-write lock.
We don't expose that to the users of RNTupleReader::GetDescriptor(). Instead, if descriptor information is needed, we clone the descriptor. Using the descriptor's generation number, we know if the cached descriptor is stale. Retrieving descriptor data from an RNTupleReader is supposed to be for testing and information purposes, not on a hot code path.
Definition at line 84 of file RNTupleReader.hxx.
|
private |
If not nullopt, these will be used when creating the model.
Definition at line 87 of file RNTupleReader.hxx.
|
private |
We use a dedicated on-demand reader for Show().
Printing data uses all the fields from the full model even if the analysis code uses only a subset of fields. The display reader is a clone of the original reader.
Definition at line 78 of file RNTupleReader.hxx.
|
private |
Definition at line 85 of file RNTupleReader.hxx.
|
private |
Needs to be destructed before fSource.
Definition at line 74 of file RNTupleReader.hxx.
|
private |
Definition at line 72 of file RNTupleReader.hxx.
|
private |
Set as the page source's scheduler for parallel page decompression if implicit multi-threading (IMT) is on.
Needs to be destructed after the page source is destructed (and thus be declared before)
Definition at line 70 of file RNTupleReader.hxx.