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#include <string>
21#include <string_view>
22#include <type_traits>
23#include <variant>
24
25#include <ROOT/RError.hxx>
26#include <ROOT/RLogger.hxx>
27
28namespace ROOT {
29
30/// Helper types to present an offset column as array of collection sizes.
31/// See RField<RNTupleCardinality<SizeT>> for details.
32template <typename SizeT>
34 static_assert(std::is_same_v<SizeT, std::uint32_t> || std::is_same_v<SizeT, std::uint64_t>,
35 "RNTupleCardinality is only supported with std::uint32_t or std::uint64_t template parameters");
36
37 using ValueType = SizeT;
38
40 explicit constexpr RNTupleCardinality(ValueType value) : fValue(value) {}
42 {
43 fValue = value;
44 return *this;
45 }
46 operator ValueType() const { return fValue; }
47
49};
50
51class RLogChannel;
52
53namespace Experimental {
54
55/// Log channel for RNTuple diagnostics.
57
58// clang-format off
59/**
60\class ROOT::Experimental::ENTupleColumnType
61\ingroup NTuple
62\brief The available trivial, native content types of a column
63
64More complex types, such as classes, get translated into columns of such simple types by the RField.
65When changed, remember to update
66 - RColumnElement::Generate()
67 - RColumnElement::GetTypeName()
68 - RColumnElement::GetValidBitRange()
69 - RColumnElement template specializations / packing & unpacking
70 - If necessary, endianess handling for the packing + unit test in ntuple_endian
71 - RNTupleSerializer::[Des|S]erializeColumnType
72*/
73// clang-format on
75 kUnknown = 0,
76 // type for root columns of (nested) collections; offsets are relative to the current cluster
79 // 96 bit column that is a pair of a kIndex64 and a 32bit dispatch tag to a column ID;
80 // used to serialize std::variant.
81 kSwitch,
82 kByte,
83 kChar,
84 kBit,
85 kReal64,
86 kReal32,
87 kReal16,
88 kInt64,
89 kUInt64,
90 kInt32,
91 kUInt32,
92 kInt16,
93 kUInt16,
94 kInt8,
95 kUInt8,
108 kMax,
109};
110
111/// The fields in the ntuple model tree can carry different structural information about the type system.
112/// Leaf fields contain just data, collection fields resolve to offset columns, record fields have no
113/// materialization on the primitive column layer.
115
116/// Integer type long enough to hold the maximum number of entries in a column
117using NTupleSize_t = std::uint64_t;
118constexpr NTupleSize_t kInvalidNTupleIndex = std::uint64_t(-1);
119
120/// Distriniguishes elements of the same type within a descriptor, e.g. different fields
121using DescriptorId_t = std::uint64_t;
122constexpr DescriptorId_t kInvalidDescriptorId = std::uint64_t(-1);
123
124/// Addresses a column element or field item relative to a particular cluster, instead of a global NTupleSize_t index
126private:
129
130public:
131 RNTupleLocalIndex() = default;
138
140
142
143 RNTupleLocalIndex operator++(int) /* postfix */
144 {
145 auto r = *this;
147 return r;
148 }
149
151 {
153 return *this;
154 }
155
157 {
158 return fClusterId == other.fClusterId && fIndexInCluster == other.fIndexInCluster;
159 }
160
161 bool operator!=(RNTupleLocalIndex other) const { return !(*this == other); }
162
165};
166
167/// RNTupleLocator payload that is common for object stores using 64bit location information.
168/// This might not contain the full location of the content. In particular, for page locators this information may be
169/// used in conjunction with the cluster and column ID.
171private:
172 std::uint64_t fLocation = 0;
173
174public:
176 explicit RNTupleLocatorObject64(std::uint64_t location) : fLocation(location) {}
177 bool operator==(const RNTupleLocatorObject64 &other) const { return fLocation == other.fLocation; }
178 std::uint64_t GetLocation() const { return fLocation; }
179};
180
181/// Generic information about the physical location of data. Values depend on the concrete storage type. E.g.,
182/// for a local file `fPosition` might be a 64bit file offset. Referenced objects on storage can be compressed
183/// and therefore we need to store their actual size.
185public:
186 /// Values for the _Type_ field in non-disk locators. Serializable types must have the MSb == 0; see
187 /// `doc/BinaryFormatSpecification.md` for details
188 enum ELocatorType : std::uint8_t {
189 // The kTypeFile locator may translate to an on-disk standard locator (type 0x00) or a large locator (type 0x01),
190 // if the size of the referenced data block is >2GB
191 kTypeFile = 0x00,
192 kTypeDAOS = 0x02,
193
197 };
198
199private:
200 std::uint64_t fNBytesOnStorage = 0;
201 /// Simple on-disk locators consisting of a 64-bit offset use variant type `uint64_t`; extended locators have
202 /// `fPosition.index()` > 0
203 std::variant<std::uint64_t, RNTupleLocatorObject64> fPosition{};
204 /// For non-disk locators, the value for the _Type_ field. This makes it possible to have different type values even
205 /// if the payload structure is identical.
207 /// Reserved for use by concrete storage backends
208 std::uint8_t fReserved = 0;
209
210public:
211 RNTupleLocator() = default;
212
213 bool operator==(const RNTupleLocator &other) const
214 {
215 return fPosition == other.fPosition && fNBytesOnStorage == other.fNBytesOnStorage && fType == other.fType;
216 }
217
218 std::uint64_t GetNBytesOnStorage() const { return fNBytesOnStorage; }
219 ELocatorType GetType() const { return fType; }
220 std::uint8_t GetReserved() const { return fReserved; }
221
224 void SetReserved(std::uint8_t reserved) { fReserved = reserved; }
225
226 template <typename T>
227 T GetPosition() const
228 {
229 return std::get<T>(fPosition);
230 }
231
232 template <typename T>
233 void SetPosition(T position)
234 {
235 fPosition = position;
236 }
237};
238
239namespace Internal {
240
241/// The in-memory representation of a 32bit or 64bit on-disk index column. Wraps the integer in a
242/// named type so that templates can distinguish between integer data columns and index columns.
244public:
245 using ValueType = std::uint64_t;
246
247private:
249
250public:
251 RColumnIndex() = default;
252 explicit constexpr RColumnIndex(ValueType value) : fValue(value) {}
254 {
255 fValue = value;
256 return *this;
257 }
259 {
260 fValue += value;
261 return *this;
262 }
264 {
265 auto result = *this;
266 fValue++;
267 return result;
268 }
269 operator ValueType() const { return fValue; }
270};
271
272/// Holds the index and the tag of a kSwitch column
274private:
276 std::uint32_t fTag = 0;
277
278public:
279 RColumnSwitch() = default;
280 RColumnSwitch(NTupleSize_t index, std::uint32_t tag) : fIndex(index), fTag(tag) {}
281 NTupleSize_t GetIndex() const { return fIndex; }
282 std::uint32_t GetTag() const { return fTag; }
283};
284
285template <typename T>
287{
288 const static std::shared_ptr<T> fgRawPtrCtrlBlock;
289 return std::shared_ptr<T>(fgRawPtrCtrlBlock, rawPtr);
290}
291
292/// Make an array of default-initialized elements. This is useful for buffers that do not need to be initialized.
293///
294/// With C++20, this function can be replaced by std::make_unique_for_overwrite<T[]>.
295template <typename T>
296std::unique_ptr<T[]> MakeUninitArray(std::size_t size)
297{
298 // DO NOT use std::make_unique<T[]>, the array elements are value-initialized!
299 return std::unique_ptr<T[]>(new T[size]);
300}
301
302inline constexpr ENTupleColumnType kTestFutureType =
303 static_cast<ENTupleColumnType>(std::numeric_limits<std::underlying_type_t<ENTupleColumnType>>::max() - 1);
304
306 static_cast<ENTupleStructure>(std::numeric_limits<std::underlying_type_t<ENTupleStructure>>::max() - 1);
307
310
311/// Check whether a given string is a valid name according to the RNTuple specification
312RResult<void> EnsureValidNameForRNTuple(std::string_view name, std::string_view where);
313
314} // namespace Internal
315
316// TODO(jblomer): remove before branching ROOT v6.36
317using EColumnType [[deprecated("ROOT::Experimental::EColumnType moved to ROOT::Experimental::ENTupleColumnType")]] =
319
320} // namespace Experimental
321} // namespace ROOT
322
323#endif
size_t size(const MatrixT &matrix)
retrieve the size of a square matrix
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
char name[80]
Definition TGX11.cxx:110
The in-memory representation of a 32bit or 64bit on-disk index column.
RColumnIndex & operator+=(const ValueType value)
RColumnIndex & operator=(const ValueType value)
constexpr RColumnIndex(ValueType value)
Holds the index and the tag of a kSwitch column.
RColumnSwitch(NTupleSize_t index, std::uint32_t tag)
Addresses a column element or field item relative to a particular cluster, instead of a global NTuple...
bool operator==(RNTupleLocalIndex other) const
RNTupleLocalIndex & operator=(const RNTupleLocalIndex &other)=default
RNTupleLocalIndex operator-(NTupleSize_t off) const
RNTupleLocalIndex(const RNTupleLocalIndex &other)=default
constexpr RNTupleLocalIndex(DescriptorId_t clusterId, NTupleSize_t indexInCluster)
bool operator!=(RNTupleLocalIndex other) const
RNTupleLocalIndex operator+(NTupleSize_t off) const
RNTupleLocator payload that is common for object stores using 64bit location information.
bool operator==(const RNTupleLocatorObject64 &other) const
RNTupleLocatorObject64(std::uint64_t location)
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.
std::uint64_t GetNBytesOnStorage() const
void SetNBytesOnStorage(std::uint64_t nBytesOnStorage)
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...
void SetReserved(std::uint8_t reserved)
void SetType(ELocatorType type)
A log configuration for a channel, e.g.
Definition RLogger.hxx:98
RResult< void > EnsureValidNameForRNTuple(std::string_view name, std::string_view where)
Check whether a given string is a valid name according to the RNTuple specification.
constexpr RNTupleLocator::ELocatorType kTestLocatorType
auto MakeAliasedSharedPtr(T *rawPtr)
constexpr ENTupleStructure kTestFutureFieldStructure
std::unique_ptr< T[]> MakeUninitArray(std::size_t size)
Make an array of default-initialized elements.
constexpr NTupleSize_t kInvalidNTupleIndex
std::uint64_t NTupleSize_t
Integer type long enough to hold the maximum number of entries in a column.
ROOT::RLogChannel & NTupleLog()
Log channel for RNTuple diagnostics.
std::uint64_t DescriptorId_t
Distriniguishes elements of the same type within a descriptor, e.g. different fields.
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...
Helper types to present an offset column as array of collection sizes.
RNTupleCardinality & operator=(const ValueType value)
constexpr RNTupleCardinality(ValueType value)