Logo ROOT   6.18/05
Reference Guide
RNTuple.hxx
Go to the documentation of this file.
1/// \file ROOT/RNTuple.hxx
2/// \ingroup NTuple ROOT7
3/// \author Jakob Blomer <jblomer@cern.ch>
4/// \date 2018-10-04
5/// \warning This is part of the ROOT 7 prototype! It will change without notice. It might trigger earthquakes. Feedback
6/// is welcome!
7
8/*************************************************************************
9 * Copyright (C) 1995-2019, Rene Brun and Fons Rademakers. *
10 * All rights reserved. *
11 * *
12 * For the licensing terms see $ROOTSYS/LICENSE. *
13 * For the list of contributors see $ROOTSYS/README/CREDITS. *
14 *************************************************************************/
15
16#ifndef ROOT7_RNTuple
17#define ROOT7_RNTuple
18
19#include <ROOT/RNTupleModel.hxx>
20#include <ROOT/RNTupleUtil.hxx>
21#include <ROOT/RNTupleView.hxx>
22#include <ROOT/RStringView.hxx>
23
24#include <iterator>
25#include <memory>
26#include <utility>
27
28namespace ROOT {
29namespace Experimental {
30
31class REntry;
32class RNTupleModel;
33
34namespace Detail {
35class RPageSink;
36class RPageSource;
37}
38
39namespace Detail {
40
41// clang-format off
42/**
43\class ROOT::Experimental::RNTuple
44\ingroup NTuple
45\brief The RNTuple represents a live dataset, whose structure is defined by an RNTupleModel
46
47RNTuple connects the static information of the RNTupleModel to a source or sink on physical storage.
48Reading and writing requires use of the corresponding derived class RNTupleReader or RNTupleWriter.
49RNTuple writes only complete entries (rows of the data set). The entry itself is not kept within the
50RNTuple, which allows for multiple concurrent entries for the same RNTuple. Besides reading an entire entry,
51the RNTuple can expose views that read only specific fields.
52*/
53// clang-format on
54class RNTuple {
55protected:
56 std::unique_ptr<RNTupleModel> fModel;
57 /// The number of entries is constant for reading and reflects the sum of Fill() operations when writing
59
60 /// Only the derived RNTupleReader and RNTupleWriter can be instantiated
61 explicit RNTuple(std::unique_ptr<RNTupleModel> model);
62
63public:
64 RNTuple(const RNTuple&) = delete;
65 RNTuple& operator =(const RNTuple&) = delete;
66 ~RNTuple();
67
68 RNTupleModel* GetModel() { return fModel.get(); }
69}; // RNTuple
70
71} // namespace Detail
72
73
74/**
75 * Listing of the different options that can be returned by RNTupleReader::GetInfo()
76 */
77enum class ENTupleInfo {
78 kSummary, // The ntuple name, description, number of entries
79};
80
81
82// clang-format off
83/**
84\class ROOT::Experimental::RNTupleReader
85\ingroup NTuple
86\brief An RNTuple that is used to read data from storage
87
88An input ntuple provides data from storage as C++ objects. The ntuple model can be created from the data on storage
89or it can be imposed by the user. The latter case allows users to read into a specialized ntuple model that covers
90only a subset of the fields in the ntuple. The ntuple model is used when reading complete entries.
91Individual fields can be read as well by instantiating a tree view.
92*/
93// clang-format on
95private:
96 std::unique_ptr<Detail::RPageSource> fSource;
97
98public:
99 // Browse through the entries
100 class RIterator : public std::iterator<std::forward_iterator_tag, NTupleSize_t> {
101 private:
104 public:
105 RIterator() = default;
106 explicit RIterator(NTupleSize_t index) : fIndex(index) {}
107 ~RIterator() = default;
108
109 iterator operator++(int) /* postfix */ { auto r = *this; ++fIndex; return r; }
110 iterator& operator++() /* prefix */ { ++fIndex; return *this; }
111 reference operator* () { return fIndex; }
112 pointer operator->() { return &fIndex; }
113 bool operator==(const iterator& rh) const { return fIndex == rh.fIndex; }
114 bool operator!=(const iterator& rh) const { return fIndex != rh.fIndex; }
115 };
116
117
118 static std::unique_ptr<RNTupleReader> Open(std::unique_ptr<RNTupleModel> model,
119 std::string_view ntupleName,
120 std::string_view storage);
121 static std::unique_ptr<RNTupleReader> Open(std::string_view ntupleName, std::string_view storage);
122
123 /// The user imposes an ntuple model, which must be compatible with the model found in the data on storage
124 RNTupleReader(std::unique_ptr<RNTupleModel> model, std::unique_ptr<Detail::RPageSource> source);
125 /// The model is generated from the ntuple metadata on storage
126 RNTupleReader(std::unique_ptr<Detail::RPageSource> source);
128
130
131 std::string GetInfo(const ENTupleInfo what = ENTupleInfo::kSummary);
132
133 /// Analogous to Fill(), fills the default entry of the model. Returns false at the end of the ntuple.
134 /// On I/O errors, raises an expection.
135 void LoadEntry(NTupleSize_t index) { LoadEntry(index, fModel->GetDefaultEntry()); }
136 /// Fills a user provided entry after checking that the entry has been instantiated from the ntuple model
137 void LoadEntry(NTupleSize_t index, REntry* entry) {
138 for (auto& value : *entry) {
139 value.GetField()->Read(index, &value);
140 }
141 }
142
144
145 /// Provides access to an individual field that can contain either a skalar value or a collection, e.g.
146 /// GetView<double>("particles.pt") or GetView<std::vector<double>>("particle"). It can as well be the index
147 /// field of a collection itself, like GetView<NTupleSize_t>("particle")
148 template <typename T>
149 RNTupleView<T> GetView(std::string_view fieldName) { return RNTupleView<T>(fieldName, fSource.get()); }
151 return RNTupleViewCollection(fieldName, fSource.get());
152 }
153
154 RIterator begin() { return RIterator(0); }
156};
157
158// clang-format off
159/**
160\class ROOT::Experimental::RNTupleWriter
161\ingroup NTuple
162\brief An RNTuple that gets filled with entries (data) and writes them to storage
163
164An output ntuple can be filled with entries. The caller has to make sure that the data that gets filled into an ntuple
165is not modified for the time of the Fill() call. The fill call serializes the C++ object into the column format and
166writes data into the corresponding column page buffers. Writing of the buffers to storage is deferred and can be
167triggered by Flush() or by destructing the ntuple. On I/O errors, an exception is thrown.
168*/
169// clang-format on
171private:
173 std::unique_ptr<Detail::RPageSink> fSink;
176
177public:
178 static std::unique_ptr<RNTupleWriter> Recreate(std::unique_ptr<RNTupleModel> model,
179 std::string_view ntupleName,
180 std::string_view storage);
181 RNTupleWriter(std::unique_ptr<RNTupleModel> model, std::unique_ptr<Detail::RPageSink> sink);
182 RNTupleWriter(const RNTupleWriter&) = delete;
185
186 /// The simplest user interface if the default entry that comes with the ntuple model is used
187 void Fill() { Fill(fModel->GetDefaultEntry()); }
188 /// Multiple entries can have been instantiated from the tnuple model. This method will perform
189 /// a light check whether the entry comes from the ntuple's own model
190 void Fill(REntry *entry) {
191 for (auto& value : *entry) {
192 value.GetField()->Append(value);
193 }
194 fNEntries++;
196 }
197 /// Ensure that the data from the so far seen Fill calls has been written to storage
198 void CommitCluster();
199};
200
201// clang-format off
202/**
203\class ROOT::Experimental::RCollectionNTuple
204\ingroup NTuple
205\brief A virtual ntuple for collections that can be used to some extent like a real ntuple
206*
207* This class is between a field and a ntuple. It carries the offset column for the collection and the default entry
208* taken from the collection model. It does not, however, have a tree model because the collection model has been merged
209* into the larger ntuple model.
210*/
211// clang-format on
213private:
215 std::unique_ptr<REntry> fDefaultEntry;
216public:
217 explicit RCollectionNTuple(std::unique_ptr<REntry> defaultEntry);
221
222 void Fill() { Fill(fDefaultEntry.get()); }
223 void Fill(REntry *entry) {
224 for (auto& treeValue : *entry) {
225 treeValue.GetField()->Append(treeValue);
226 }
227 fOffset++;
228 }
229
231};
232
233} // namespace Experimental
234} // namespace ROOT
235
236#endif
ROOT::R::TRInterface & r
Definition: Object.C:4
RNTuple & operator=(const RNTuple &)=delete
NTupleSize_t fNEntries
The number of entries is constant for reading and reflects the sum of Fill() operations when writing.
Definition: RNTuple.hxx:58
RNTuple(const RNTuple &)=delete
RNTuple(std::unique_ptr< RNTupleModel > model)
Only the derived RNTupleReader and RNTupleWriter can be instantiated.
Definition: RNTuple.cxx:27
std::unique_ptr< RNTupleModel > fModel
Definition: RNTuple.hxx:56
A virtual ntuple for collections that can be used to some extent like a real ntuple.
Definition: RNTuple.hxx:212
RCollectionNTuple(std::unique_ptr< REntry > defaultEntry)
Definition: RNTuple.cxx:154
RCollectionNTuple(const RCollectionNTuple &)=delete
std::unique_ptr< REntry > fDefaultEntry
Definition: RNTuple.hxx:215
RCollectionNTuple & operator=(const RCollectionNTuple &)=delete
The REntry is a collection of values in an ntuple corresponding to a complete row in the data set.
Definition: REntry.hxx:42
The RNTupleModel encapulates the schema of an ntuple.
bool operator!=(const iterator &rh) const
Definition: RNTuple.hxx:114
bool operator==(const iterator &rh) const
Definition: RNTuple.hxx:113
An RNTuple that is used to read data from storage.
Definition: RNTuple.hxx:94
static std::unique_ptr< RNTupleReader > Open(std::unique_ptr< RNTupleModel > model, std::string_view ntupleName, std::string_view storage)
Definition: RNTuple.cxx:68
RNTupleViewRange GetViewRange()
Definition: RNTuple.hxx:143
void LoadEntry(NTupleSize_t index, REntry *entry)
Fills a user provided entry after checking that the entry has been instantiated from the ntuple model...
Definition: RNTuple.hxx:137
RNTupleView< T > GetView(std::string_view fieldName)
Provides access to an individual field that can contain either a skalar value or a collection,...
Definition: RNTuple.hxx:149
std::unique_ptr< Detail::RPageSource > fSource
Definition: RNTuple.hxx:96
RNTupleReader(std::unique_ptr< RNTupleModel > model, std::unique_ptr< Detail::RPageSource > source)
The user imposes an ntuple model, which must be compatible with the model found in the data on storag...
Definition: RNTuple.cxx:39
RNTupleViewCollection GetViewCollection(std::string_view fieldName)
Definition: RNTuple.hxx:150
void LoadEntry(NTupleSize_t index)
Analogous to Fill(), fills the default entry of the model.
Definition: RNTuple.hxx:135
std::string GetInfo(const ENTupleInfo what=ENTupleInfo::kSummary)
Definition: RNTuple.cxx:85
A view for a collection, that can itself generate new ntuple views for its nested fields.
Used to loop over indexes (entries or collections) between start and end.
Definition: RNTupleView.hxx:38
An RNTupleView provides read-only access to a single field of the ntuple.
Definition: RNTupleView.hxx:86
An RNTuple that gets filled with entries (data) and writes them to storage.
Definition: RNTuple.hxx:170
void Fill(REntry *entry)
Multiple entries can have been instantiated from the tnuple model.
Definition: RNTuple.hxx:190
void CommitCluster()
Ensure that the data from the so far seen Fill calls has been written to storage.
Definition: RNTuple.cxx:139
RNTupleWriter(std::unique_ptr< RNTupleModel > model, std::unique_ptr< Detail::RPageSink > sink)
Definition: RNTuple.cxx:106
static std::unique_ptr< RNTupleWriter > Recreate(std::unique_ptr< RNTupleModel > model, std::string_view ntupleName, std::string_view storage)
Definition: RNTuple.cxx:124
static constexpr NTupleSize_t kDefaultClusterSizeEntries
Definition: RNTuple.hxx:172
RNTupleWriter(const RNTupleWriter &)=delete
RNTupleWriter & operator=(const RNTupleWriter &)=delete
std::unique_ptr< Detail::RPageSink > fSink
Definition: RNTuple.hxx:173
void Fill()
The simplest user interface if the default entry that comes with the ntuple model is used.
Definition: RNTuple.hxx:187
basic_string_view< char > string_view
ENTupleInfo
Listing of the different options that can be returned by RNTupleReader::GetInfo()
Definition: RNTuple.hxx:77
std::uint64_t NTupleSize_t
Integer type long enough to hold the maximum number of entries in a column.
Definition: RNTupleUtil.hxx:44
constexpr NTupleSize_t kInvalidNTupleIndex
Definition: RNTupleUtil.hxx:45
Namespace for new ROOT classes and functions.
Definition: StringConv.hxx:21
Wrap the 32bit integer in a struct in order to avoid template specialization clash with std::uint32_t...
Definition: RNTupleUtil.hxx:47