Logo ROOT  
Reference Guide
 
Loading...
Searching...
No Matches
RNTupleUtil.hxx
Go to the documentation of this file.
1/// \file ROOT/RNTupleUtil.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-2020, 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_RNTupleUtil
17#define ROOT7_RNTupleUtil
18
19#include <cstdint>
20
21#include <string>
22#include <variant>
23
24#include <ROOT/RLogger.hxx>
26
27namespace ROOT {
28
29/// Helper types to present an offset column as array of collection sizes.
30/// See RField<RNTupleCardinality<SizeT>> for details.
31template <typename SizeT>
33 static_assert(std::is_same_v<SizeT, std::uint32_t> || std::is_same_v<SizeT, std::uint64_t>,
34 "RNTupleCardinality is only supported with std::uint32_t or std::uint64_t template parameters");
35
36 using ValueType = SizeT;
37
39 explicit constexpr RNTupleCardinality(ValueType value) : fValue(value) {}
41 {
42 fValue = value;
43 return *this;
44 }
45 operator ValueType() const { return fValue; }
46
48};
49
50namespace Experimental {
51
52class RLogChannel;
53/// Log channel for RNTuple diagnostics.
54RLogChannel &NTupleLog();
55
56// clang-format off
57/**
58\class ROOT::Experimental::EColumnType
59\ingroup NTuple
60\brief The available trivial, native content types of a column
61
62More complex types, such as classes, get translated into columns of such simple types by the RField.
63When changed, remember to update
64 - RColumnElement::Generate()
65 - RColumnElement::GetTypeName()
66 - RColumnElement::GetValidBitRange()
67 - RColumnElement template specializations / packing & unpacking
68 - If necessary, endianess handling for the packing + unit test in ntuple_endian
69 - RNTupleSerializer::[Des|S]erializeColumnType
70*/
71// clang-format on
72enum class EColumnType {
73 kUnknown = 0,
74 // type for root columns of (nested) collections; offsets are relative to the current cluster
77 // 96 bit column that is a pair of a kIndex64 and a 32bit dispatch tag to a column ID;
78 // used to serialize std::variant.
79 kSwitch,
80 kByte,
81 kChar,
82 kBit,
83 kReal64,
84 kReal32,
85 kReal16,
86 kInt64,
87 kUInt64,
88 kInt32,
89 kUInt32,
90 kInt16,
91 kUInt16,
92 kInt8,
93 kUInt8,
106 kMax,
107};
108
109/// The fields in the ntuple model tree can carry different structural information about the type system.
110/// Leaf fields contain just data, collection fields resolve to offset columns, record fields have no
111/// materialization on the primitive column layer.
113
114/// Integer type long enough to hold the maximum number of entries in a column
115using NTupleSize_t = std::uint64_t;
116constexpr NTupleSize_t kInvalidNTupleIndex = std::uint64_t(-1);
117/// Wrap the integer in a struct in order to avoid template specialization clash with std::uint64_t
119 using ValueType = std::uint64_t;
120
122 explicit constexpr RClusterSize(ValueType value) : fValue(value) {}
124 {
125 fValue = value;
126 return *this;
127 }
129 {
130 fValue += value;
131 return *this;
132 }
134 {
135 auto result = *this;
136 fValue++;
137 return result;
138 }
139 operator ValueType() const { return fValue; }
140
142};
144constexpr ClusterSize_t kInvalidClusterIndex(std::uint64_t(-1));
145
147
148/// Holds the index and the tag of a kSwitch column
150private:
152 std::uint32_t fTag = 0;
153
154public:
155 RColumnSwitch() = default;
156 RColumnSwitch(ClusterSize_t index, std::uint32_t tag) : fIndex(index), fTag(tag) {}
157 ClusterSize_t GetIndex() const { return fIndex; }
158 std::uint32_t GetTag() const { return fTag; }
159};
160
161/// Uniquely identifies a physical column within the scope of the current process, used to tag pages
162using ColumnId_t = std::int64_t;
164
165/// Distriniguishes elements of the same type within a descriptor, e.g. different fields
166using DescriptorId_t = std::uint64_t;
167constexpr DescriptorId_t kInvalidDescriptorId = std::uint64_t(-1);
168
169/// Addresses a column element or field item relative to a particular cluster, instead of a global NTupleSize_t index
171private:
174
175public:
176 RClusterIndex() = default;
177 RClusterIndex(const RClusterIndex &other) = default;
178 RClusterIndex &operator=(const RClusterIndex &other) = default;
180 : fClusterId(clusterId), fIndex(index)
181 {
182 }
183
186 RClusterIndex operator++(int) /* postfix */
187 {
188 auto r = *this;
189 fIndex++;
190 return r;
191 }
192 RClusterIndex &operator++() /* prefix */
193 {
194 ++fIndex;
195 return *this;
196 }
197 bool operator==(RClusterIndex other) const { return fClusterId == other.fClusterId && fIndex == other.fIndex; }
198 bool operator!=(RClusterIndex other) const { return !(*this == other); }
199
202};
203
204/// RNTupleLocator payload that is common for object stores using 64bit location information.
205/// This might not contain the full location of the content. In particular, for page locators this information may be
206/// used in conjunction with the cluster and column ID.
208 std::uint64_t fLocation = 0;
209 bool operator==(const RNTupleLocatorObject64 &other) const { return fLocation == other.fLocation; }
210};
211
212/// Generic information about the physical location of data. Values depend on the concrete storage type. E.g.,
213/// for a local file `fPosition` might be a 64bit file offset. Referenced objects on storage can be compressed
214/// and therefore we need to store their actual size.
215/// TODO(jblomer): consider moving this to `RNTupleDescriptor`
217 /// Values for the _Type_ field in non-disk locators. Serializable types must have the MSb == 0; see
218 /// `doc/BinaryFormatSpecification.md` for details
219 enum ELocatorType : std::uint8_t {
220 // The kTypeFile locator may translate to an on-disk standard locator (type 0x00) or a large locator (type 0x01),
221 // if the size of the referenced data block is >2GB
222 kTypeFile = 0x00,
223 kTypeDAOS = 0x02,
224
228 };
229
230 std::uint64_t fBytesOnStorage = 0;
231 /// Simple on-disk locators consisting of a 64-bit offset use variant type `uint64_t`; extended locators have
232 /// `fPosition.index()` > 0
233 std::variant<std::uint64_t, RNTupleLocatorObject64> fPosition{};
234 /// For non-disk locators, the value for the _Type_ field. This makes it possible to have different type values even
235 /// if the payload structure is identical.
237 /// Reserved for use by concrete storage backends
238 std::uint8_t fReserved = 0;
239
240 bool operator==(const RNTupleLocator &other) const
241 {
242 return fPosition == other.fPosition && fBytesOnStorage == other.fBytesOnStorage && fType == other.fType;
243 }
244 template <typename T>
245 const T &GetPosition() const
246 {
247 return std::get<T>(fPosition);
248 }
249};
250
251/// Used to specify the underlying RNTuples in RNTupleProcessor and RNTupleReader::OpenFriends()
253 std::string fNTupleName;
254 std::string fStorage;
256
257 RNTupleOpenSpec(std::string_view n, std::string_view s) : fNTupleName(n), fStorage(s) {}
258};
259
260namespace Internal {
261template <typename T>
262auto MakeAliasedSharedPtr(T *rawPtr)
263{
264 const static std::shared_ptr<T> fgRawPtrCtrlBlock;
265 return std::shared_ptr<T>(fgRawPtrCtrlBlock, rawPtr);
266}
267
269 static_cast<ENTupleStructure>(std::numeric_limits<std::underlying_type_t<ENTupleStructure>>::max() - 1);
270
273
274} // namespace Internal
275
276} // namespace Experimental
277} // namespace ROOT
278
279#endif
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 r
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 result
Option_t Option_t TPoint TPoint const char GetTextMagnitude GetFillStyle GetLineColor GetLineWidth GetMarkerStyle GetTextAlign GetTextColor GetTextSize void char Point_t Rectangle_t WindowAttributes_t index
Option_t Option_t TPoint TPoint const char GetTextMagnitude GetFillStyle GetLineColor GetLineWidth GetMarkerStyle GetTextAlign GetTextColor GetTextSize void value
Addresses a column element or field item relative to a particular cluster, instead of a global NTuple...
RClusterIndex operator+(ClusterSize_t::ValueType off) const
ClusterSize_t::ValueType fIndex
RClusterIndex operator-(ClusterSize_t::ValueType off) const
bool operator==(RClusterIndex other) const
RClusterIndex & operator=(const RClusterIndex &other)=default
bool operator!=(RClusterIndex other) const
DescriptorId_t GetClusterId() const
constexpr RClusterIndex(DescriptorId_t clusterId, ClusterSize_t::ValueType index)
ClusterSize_t::ValueType GetIndex() const
RClusterIndex(const RClusterIndex &other)=default
Holds the index and the tag of a kSwitch column.
RColumnSwitch(ClusterSize_t index, std::uint32_t tag)
Common user-tunable settings for reading ntuples.
const Int_t n
Definition legend1.C:16
constexpr RNTupleLocator::ELocatorType kTestLocatorType
auto MakeAliasedSharedPtr(T *rawPtr)
constexpr ENTupleStructure kTestFutureFieldStructure
RLogChannel & NTupleLog()
Log channel for RNTuple diagnostics.
std::uint64_t NTupleSize_t
Integer type long enough to hold the maximum number of entries in a column.
constexpr ColumnId_t kInvalidColumnId
constexpr int kUnknownCompressionSettings
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))
ENTupleStructure
The fields in the ntuple model tree can carry different structural information about the type system.
constexpr DescriptorId_t kInvalidDescriptorId
tbb::task_arena is an alias of tbb::interface7::task_arena, which doesn't allow to forward declare tb...
Wrap the integer in a struct in order to avoid template specialization clash with std::uint64_t.
RClusterSize & operator=(const ValueType value)
constexpr RClusterSize(ValueType value)
RClusterSize & operator+=(const ValueType value)
RNTupleLocator payload that is common for object stores using 64bit location information.
bool operator==(const RNTupleLocatorObject64 &other) const
Generic information about the physical location of data.
ELocatorType
Values for the Type field in non-disk locators.
std::uint8_t fReserved
Reserved for use by concrete storage backends.
ELocatorType fType
For non-disk locators, the value for the Type field.
bool operator==(const RNTupleLocator &other) const
std::variant< std::uint64_t, RNTupleLocatorObject64 > fPosition
Simple on-disk locators consisting of a 64-bit offset use variant type uint64_t; extended locators ha...
Used to specify the underlying RNTuples in RNTupleProcessor and RNTupleReader::OpenFriends()
RNTupleOpenSpec(std::string_view n, std::string_view s)
Helper types to present an offset column as array of collection sizes.
RNTupleCardinality & operator=(const ValueType value)
constexpr RNTupleCardinality(ValueType value)