Logo ROOT  
Reference Guide
 
Loading...
Searching...
No Matches
RNTupleTypes.hxx
Go to the documentation of this file.
1/// \file ROOT/RNTupleTypes.hxx
2/// \ingroup NTuple
3/// \author Jakob Blomer <jblomer@cern.ch>
4/// \date 2018-10-04
5
6/*************************************************************************
7 * Copyright (C) 1995-2020, Rene Brun and Fons Rademakers. *
8 * All rights reserved. *
9 * *
10 * For the licensing terms see $ROOTSYS/LICENSE. *
11 * For the list of contributors see $ROOTSYS/README/CREDITS. *
12 *************************************************************************/
13
14#ifndef ROOT_RNTupleTypes
15#define ROOT_RNTupleTypes
16
17#include <ROOT/RConfig.hxx>
18
19#include <cstddef>
20#include <cstdint>
21#include <limits>
22#include <ostream>
23#include <type_traits>
24#include <variant>
25
26namespace ROOT {
27
28/// Helper types to present an offset column as array of collection sizes.
29/// See RField<RNTupleCardinality<SizeT>> for details.
30template <typename SizeT>
32 static_assert(std::is_same_v<SizeT, std::uint32_t> || std::is_same_v<SizeT, std::uint64_t>,
33 "RNTupleCardinality is only supported with std::uint32_t or std::uint64_t template parameters");
34
35 using ValueType = SizeT;
36
38 explicit constexpr RNTupleCardinality(ValueType value) : fValue(value) {}
40 {
41 fValue = value;
42 return *this;
43 }
44 operator ValueType() const { return fValue; }
45
47};
48
49// clang-format off
50/**
51\class ROOT::ENTupleColumnType
52\ingroup NTuple
53\brief The available trivial, native content types of a column
54
55More complex types, such as classes, get translated into columns of such simple types by the RField.
56When changed, remember to update
57 - RColumnElement::Generate()
58 - RColumnElement::GetTypeName()
59 - RColumnElement::GetValidBitRange()
60 - RColumnElement template specializations / packing & unpacking
61 - If necessary, endianess handling for the packing + unit test in ntuple_endian
62 - RNTupleSerializer::[Des|S]erializeColumnType
63*/
64// clang-format on
66 kUnknown = 0,
67 // type for root columns of (nested) collections; offsets are relative to the current cluster
70 // 96 bit column that is a pair of a kIndex64 and a 32bit dispatch tag to a column ID;
71 // used to serialize std::variant.
72 kSwitch,
73 kByte,
74 kChar,
75 kBit,
76 kReal64,
77 kReal32,
78 kReal16,
79 kInt64,
80 kUInt64,
81 kInt32,
82 kUInt32,
83 kInt16,
84 kUInt16,
85 kInt8,
86 kUInt8,
99 kMax,
100};
101
102/// The fields in the RNTuple data model tree can carry different structural information about the type system.
103/// Collection fields have an offset column and subfields with arbitrary cardinality, record fields have no
104/// materialization on the primitive column layer and an arbitrary number of subfields. Plain fields are either
105/// leafs (e.g., `float`) or "wrapper fields" with exactly one child that has the same cardinality
106/// (number of elements in the data set modulo field repetitions) as the parent (e.g., std::atomic<T>).
107// IMPORTANT: if you add members, remember to change the related `operator<<` below.
108enum class ENTupleStructure : std::uint16_t {
109 kInvalid,
110 kPlain,
112 kRecord,
113 kVariant,
114 kStreamer,
115 kUnknown,
116
117 // for backwards compatibility
118 kLeaf R__DEPRECATED(6, 42, "use instead ROOT::ENTupleStructure::kPlain") = kPlain
119};
120
121inline std::ostream &operator<<(std::ostream &os, ENTupleStructure structure)
122{
123 static const char *const names[] = {"Invalid", "Plain", "Collection", "Record", "Variant", "Streamer", "Unknown"};
124 static_assert((std::size_t)ENTupleStructure::kUnknown + 1 == std::size(names));
125
126 if (R__likely(static_cast<std::size_t>(structure) <= std::size(names)))
128 else
129 os << "(invalid)";
130 return os;
131}
132
133/// Integer type long enough to hold the maximum number of entries in a column
134using NTupleSize_t = std::uint64_t;
135constexpr NTupleSize_t kInvalidNTupleIndex = std::uint64_t(-1);
136
137/// Distriniguishes elements of the same type within a descriptor, e.g. different fields
138using DescriptorId_t = std::uint64_t;
139constexpr DescriptorId_t kInvalidDescriptorId = std::uint64_t(-1);
140
141/// Addresses a column element or field item relative to a particular cluster, instead of a global NTupleSize_t index
189
190/// RNTupleLocator payload that is common for object stores using 64bit location information.
191/// This might not contain the full location of the content. In particular, for page locators this information may be
192/// used in conjunction with the cluster and column ID.
194private:
195 std::uint64_t fLocation = 0;
196
197public:
199 explicit RNTupleLocatorObject64(std::uint64_t location) : fLocation(location) {}
200 bool operator==(const RNTupleLocatorObject64 &other) const { return fLocation == other.fLocation; }
201 std::uint64_t GetLocation() const { return fLocation; }
202};
203
204/// Generic information about the physical location of data. Values depend on the concrete storage type. E.g.,
205/// for a local file `fPosition` might be a 64bit file offset. Referenced objects on storage can be compressed
206/// and therefore we need to store their actual size.
208public:
209 /// Values for the _Type_ field in non-disk locators. Serializable types must have the MSb == 0; see
210 /// `doc/BinaryFormatSpecification.md` for details
211 enum ELocatorType : std::uint8_t {
212 // The kTypeFile locator may translate to an on-disk standard locator (type 0x00) or a large locator (type 0x01),
213 // if the size of the referenced data block is >2GB
214 kTypeFile = 0x00,
215 kTypeDAOS = 0x02,
216
220 };
221
222private:
223 std::uint64_t fNBytesOnStorage = 0;
224 /// Simple on-disk locators consisting of a 64-bit offset use variant type `uint64_t`; extended locators have
225 /// `fPosition.index()` > 0
226 std::variant<std::uint64_t, RNTupleLocatorObject64> fPosition{};
227 /// For non-disk locators, the value for the _Type_ field. This makes it possible to have different type values even
228 /// if the payload structure is identical.
230 /// Reserved for use by concrete storage backends
231 std::uint8_t fReserved = 0;
232
233public:
234 RNTupleLocator() = default;
235
236 bool operator==(const RNTupleLocator &other) const
237 {
238 return fPosition == other.fPosition && fNBytesOnStorage == other.fNBytesOnStorage && fType == other.fType;
239 }
240
241 std::uint64_t GetNBytesOnStorage() const { return fNBytesOnStorage; }
242 ELocatorType GetType() const { return fType; }
243 std::uint8_t GetReserved() const { return fReserved; }
244
247 void SetReserved(std::uint8_t reserved) { fReserved = reserved; }
248
249 template <typename T>
250 T GetPosition() const
251 {
252 return std::get<T>(fPosition);
253 }
254
255 template <typename T>
256 void SetPosition(T position)
257 {
258 fPosition = position;
259 }
260};
261
262namespace Internal {
263
264/// The in-memory representation of a 32bit or 64bit on-disk index column. Wraps the integer in a
265/// named type so that templates can distinguish between integer data columns and index columns.
267public:
268 using ValueType = std::uint64_t;
269
270private:
272
273public:
274 RColumnIndex() = default;
275 explicit constexpr RColumnIndex(ValueType value) : fValue(value) {}
277 {
278 fValue = value;
279 return *this;
280 }
282 {
283 fValue += value;
284 return *this;
285 }
287 {
288 auto result = *this;
289 fValue++;
290 return result;
291 }
292 operator ValueType() const { return fValue; }
293};
294
295/// Holds the index and the tag of a kSwitch column
297private:
299 std::uint32_t fTag = 0;
300
301public:
302 RColumnSwitch() = default;
303 RColumnSwitch(ROOT::NTupleSize_t index, std::uint32_t tag) : fIndex(index), fTag(tag) {}
305 std::uint32_t GetTag() const { return fTag; }
306};
307
308inline constexpr ENTupleColumnType kTestFutureColumnType =
309 static_cast<ENTupleColumnType>(std::numeric_limits<std::underlying_type_t<ENTupleColumnType>>::max() - 1);
310
312 static_cast<ROOT::ENTupleStructure>(std::numeric_limits<std::underlying_type_t<ROOT::ENTupleStructure>>::max() - 1);
313
316
317} // namespace Internal
318} // namespace ROOT
319
320#endif
#define R__likely(expr)
Definition RConfig.hxx:595
ROOT::Detail::TRangeCast< T, true > TRangeDynCast
TRangeDynCast is an adapter class that allows the typed iteration through a TCollection.
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
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 Atom_t Int_t ULong_t ULong_t unsigned char prop_list Atom_t Atom_t Atom_t Time_t type
The in-memory representation of a 32bit or 64bit on-disk index column.
constexpr RColumnIndex(ValueType value)
RColumnIndex & operator=(const ValueType value)
RColumnIndex & operator+=(const ValueType value)
Holds the index and the tag of a kSwitch column.
std::uint32_t GetTag() const
ROOT::NTupleSize_t GetIndex() const
RColumnSwitch(ROOT::NTupleSize_t index, std::uint32_t tag)
Addresses a column element or field item relative to a particular cluster, instead of a global NTuple...
RNTupleLocalIndex operator-(ROOT::NTupleSize_t off) const
ROOT::NTupleSize_t fIndexInCluster
RNTupleLocalIndex operator++(int)
bool operator==(RNTupleLocalIndex other) const
RNTupleLocalIndex operator+(ROOT::NTupleSize_t off) const
ROOT::NTupleSize_t GetIndexInCluster() const
constexpr RNTupleLocalIndex(ROOT::DescriptorId_t clusterId, ROOT::NTupleSize_t indexInCluster)
RNTupleLocalIndex & operator++()
RNTupleLocalIndex(const RNTupleLocalIndex &other)=default
RNTupleLocalIndex & operator=(const RNTupleLocalIndex &other)=default
bool operator!=(RNTupleLocalIndex other) const
ROOT::DescriptorId_t fClusterId
ROOT::DescriptorId_t GetClusterId() const
RNTupleLocator payload that is common for object stores using 64bit location information.
bool operator==(const RNTupleLocatorObject64 &other) const
RNTupleLocatorObject64(std::uint64_t location)
std::uint64_t GetLocation() const
Generic information about the physical location of data.
std::uint64_t GetNBytesOnStorage() const
bool operator==(const RNTupleLocator &other) const
RNTupleLocator()=default
ELocatorType
Values for the Type field in non-disk locators.
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...
std::uint8_t fReserved
Reserved for use by concrete storage backends.
std::uint8_t GetReserved() const
void SetPosition(T position)
void SetType(ELocatorType type)
ELocatorType GetType() const
void SetReserved(std::uint8_t reserved)
void SetNBytesOnStorage(std::uint64_t nBytesOnStorage)
ELocatorType fType
For non-disk locators, the value for the Type field.
std::uint64_t fNBytesOnStorage
constexpr ROOT::ENTupleStructure kTestFutureFieldStructure
constexpr RNTupleLocator::ELocatorType kTestLocatorType
std::ostream & operator<<(std::ostream &os, const RConcurrentHashColl::HashValue &h)
Namespace for new ROOT classes and functions.
std::uint64_t DescriptorId_t
Distriniguishes elements of the same type within a descriptor, e.g. different fields.
constexpr NTupleSize_t kInvalidNTupleIndex
std::uint64_t NTupleSize_t
Integer type long enough to hold the maximum number of entries in a column.
constexpr DescriptorId_t kInvalidDescriptorId
ENTupleStructure
The fields in the RNTuple data model tree can carry different structural information about the type s...
ENTupleColumnType
Helper types to present an offset column as array of collection sizes.
RNTupleCardinality & operator=(const ValueType value)
constexpr RNTupleCardinality(ValueType value)