Logo ROOT  
Reference Guide
 
Loading...
Searching...
No Matches
RFieldBase.hxx
Go to the documentation of this file.
1/// \file ROOT/RFieldBase.hxx
2/// \ingroup NTuple
3/// \author Jakob Blomer <jblomer@cern.ch>
4/// \date 2018-10-09
5
6/*************************************************************************
7 * Copyright (C) 1995-2019, 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_RFieldBase
15#define ROOT_RFieldBase
16
17#include <ROOT/RColumn.hxx>
19#include <ROOT/RError.hxx>
20#include <ROOT/RFieldUtils.hxx>
21#include <ROOT/RNTupleRange.hxx>
22#include <ROOT/RNTupleTypes.hxx>
23
24#include <atomic>
25#include <cstddef>
26#include <functional>
27#include <iterator>
28#include <memory>
29#include <new>
30#include <string>
31#include <string_view>
32#include <typeinfo>
33#include <type_traits>
34#include <vector>
35
36namespace ROOT {
37
38class REntry;
39class RFieldBase;
40class RClassField;
41
42namespace Detail {
43class RFieldVisitor;
44} // namespace Detail
45
46namespace Experimental {
47
48namespace Detail {
49class RRawPtrWriteEntry;
50} // namespace Detail
51
52} // namespace Experimental
53
54namespace Internal {
55
56class RPageSink;
57class RPageSource;
58struct RFieldCallbackInjector;
59struct RFieldRepresentationModifier;
60
61// TODO(jblomer): find a better way to not have these methods in the RFieldBase public API
62void CallFlushColumnsOnField(RFieldBase &);
63void CallCommitClusterOnField(RFieldBase &);
67CallFieldBaseCreate(const std::string &fieldName, const std::string &typeName, const ROOT::RCreateFieldOptions &options,
69
70} // namespace Internal
71
72// clang-format off
73/**
74\class ROOT::RFieldBase
75\ingroup NTuple
76\brief A field translates read and write calls from/to underlying columns to/from tree values
77
78A field is a serializable C++ type or a container for a collection of subfields. The RFieldBase and its
79type-safe descendants provide the object to column mapper. They map C++ objects to primitive columns. The
80mapping is trivial for simple types such as 'double'. Complex types resolve to multiple primitive columns.
81The field knows based on its type and the field name the type(s) and name(s) of the columns.
82
83Note: the class hierarchy starting at RFieldBase is not meant to be extended by user-provided child classes.
84This is and can only be partially enforced through C++.
85*/
86// clang-format on
88 friend class ROOT::RClassField; // to mark members as artificial
89 friend class ROOT::Experimental::Detail::RRawPtrWriteEntry; // to call Append()
90 friend struct ROOT::Internal::RFieldCallbackInjector; // used for unit tests
91 friend struct ROOT::Internal::RFieldRepresentationModifier; // used for unit tests
97 Internal::CallFieldBaseCreate(const std::string &fieldName, const std::string &typeName,
98 const ROOT::RCreateFieldOptions &options, const ROOT::RNTupleDescriptor *desc,
100
101 using ReadCallback_t = std::function<void(void *)>;
102
103protected:
104 /// A functor to release the memory acquired by CreateValue() (memory and constructor).
105 /// This implementation works for types with a trivial destructor. More complex fields implement a derived deleter.
106 /// The deleter is operational without the field object and thus can be used to destruct/release a value after
107 /// the field has been destructed.
108 class RDeleter {
109 public:
110 virtual ~RDeleter() = default;
111 virtual void operator()(void *objPtr, bool dtorOnly)
112 {
113 if (!dtorOnly)
114 operator delete(objPtr);
115 }
116 };
117
118 /// A deleter for templated RFieldBase descendents where the value type is known.
119 template <typename T>
120 class RTypedDeleter : public RDeleter {
121 public:
122 void operator()(void *objPtr, bool dtorOnly) final
123 {
124 std::destroy_at(static_cast<T *>(objPtr));
126 }
127 };
128
129 // We cannot directly use RFieldBase::RDeleter as a shared pointer deleter due to splicing. We use this
130 // wrapper class to store a polymorphic pointer to the actual deleter.
132 std::unique_ptr<RFieldBase::RDeleter> fDeleter;
133 void operator()(void *objPtr) { fDeleter->operator()(objPtr, false /* dtorOnly*/); }
134 explicit RSharedPtrDeleter(std::unique_ptr<RFieldBase::RDeleter> deleter) : fDeleter(std::move(deleter)) {}
135 };
136
137public:
138 static constexpr std::uint32_t kInvalidTypeVersion = -1U;
139 enum {
140 /// No constructor needs to be called, i.e. any bit pattern in the allocated memory represents a valid type
141 /// A trivially constructible field has a no-op ConstructValue() implementation
143 /// The type is cleaned up just by freeing its memory. I.e. the destructor performs a no-op.
145 /// A field of a fundamental type that can be directly mapped via RField<T>::Map(), i.e. maps as-is to a single
146 /// column
148 /// The TClass checksum is set and valid
150 /// This field is an instance of RInvalidField and can be safely `static_cast` to it
152 /// This field is a user defined type that was missing dictionaries and was reconstructed from the on-disk
153 /// information
155
156 /// Shorthand for types that are both trivially constructible and destructible
158 };
159
160 using ColumnRepresentation_t = std::vector<ROOT::ENTupleColumnType>;
161
162 /// During its lifetime, a field undergoes the following possible state transitions:
163 ///
164 /// [*] --> Unconnected --> ConnectedToSink ----
165 /// | | |
166 /// | --> ConnectedToSource ---> [*]
167 /// | |
168 /// -------------------------------
169 enum class EState {
173 };
174
175 // clang-format off
176 /**
177 \class ROOT::RFieldBase::RColumnRepresentations
178 \ingroup NTuple
179 \brief The list of column representations a field can have.
180
181 Some fields have multiple possible column representations, e.g. with or without split encoding.
182 All column representations supported for writing also need to be supported for reading. In addition,
183 fields can support extra column representations for reading only, e.g. a 64bit integer reading from a
184 32bit column.
185 The defined column representations must be supported by corresponding column packing/unpacking implementations,
186 i.e. for the example above, the unpacking of 32bit ints to 64bit pages must be implemented in RColumnElement.hxx
187 */
188 // clang-format on
190 public:
191 /// A list of column representations
192 using Selection_t = std::vector<ColumnRepresentation_t>;
193
196
197 /// The first column list from `fSerializationTypes` is the default for writing.
201
202 private:
204 /// The union of the serialization types and the deserialization extra types passed during construction.
205 /// Duplicates the serialization types list but the benefit is that GetDeserializationTypes() does not need to
206 /// compile the list.
208 }; // class RColumnRepresentations
209
210 class RValue;
211 class RBulkValues;
212
213private:
214 /// The field name relative to its parent field
215 std::string fName;
216 /// The C++ type captured by this field
217 std::string fType;
218 /// The role of this field in the data model structure
220 /// For fixed sized arrays, the array length
221 std::size_t fNRepetitions;
222 /// A field qualifies as simple if it is mappable (which implies it has a single principal column),
223 /// and it is not an artificial field and has no post-read callback
225 /// A field that is not backed on disk but computed, e.g. a default-constructed missing field or
226 /// a field whose data is created by I/O customization rules. Subfields of artificial fields are
227 /// artificial, too.
228 bool fIsArtificial = false;
229 /// When the columns are connected to a page source or page sink, the field represents a field id in the
230 /// corresponding RNTuple descriptor. This on-disk ID is set in RPageSink::Create() for writing and by
231 /// RFieldDescriptor::CreateField() when recreating a field / model from the stored descriptor.
233 /// Free text set by the user
234 std::string fDescription;
235 /// Changed by ConnectTo[Sink,Source], reset by Clone()
237
239 {
240 for (const auto &func : fReadCallbacks)
241 func(target);
242 }
243
244 /// Translate an entry index to a column element index of the principal column and vice versa. These functions
245 /// take into account the role and number of repetitions on each level of the field hierarchy as follows:
246 /// - Top level fields: element index == entry index
247 /// - Record fields propagate their principal column index to the principal columns of direct descendant fields
248 /// - Collection and variant fields set the principal column index of their children to 0
249 ///
250 /// The column element index also depends on the number of repetitions of each field in the hierarchy, e.g., given a
251 /// field with type `std::array<std::array<float, 4>, 2>`, this function returns 8 for the innermost field.
253
254 /// Flushes data from active columns
255 void FlushColumns();
256 /// Flushes data from active columns to disk and calls CommitClusterImpl()
257 void CommitCluster();
258 /// Fields and their columns live in the void until connected to a physical page storage. Only once connected, data
259 /// can be read or written. In order to find the field in the page storage, the field's on-disk ID has to be set.
260 /// \param firstEntry The global index of the first entry with on-disk data for the connected field
262 /// Connects the field and its subfield tree to the given page source. Once connected, data can be read.
263 /// Only unconnected fields may be connected, i.e. the method is not idempotent. The field ID has to be set prior to
264 /// calling this function. For subfields, a field ID may or may not be set. If the field ID is unset, it will be
265 /// determined using the page source descriptor, based on the parent field ID and the subfield name.
267
269 {
270 fIsSimple = false;
271 fIsArtificial = true;
272 for (auto &field : fSubfields) {
273 field->SetArtificial();
274 }
275 }
276
277protected:
278 struct RBulkSpec;
279
280 /// Collections and classes own subfields
281 std::vector<std::unique_ptr<RFieldBase>> fSubfields;
282 /// Subfields point to their mother field
284 /// All fields that have columns have a distinct main column. E.g., for simple fields (`float`, `int`, ...), the
285 /// principal column corresponds to the field type. For collection fields except fixed-sized arrays,
286 /// the main column is the offset field. Class fields have no column of their own.
287 /// When reading, points to any column of the column team of the active representation. Usually, this is just
288 /// the first column.
289 /// When writing, points to the first column index of the currently active (not suppressed) column representation.
291 /// Some fields have a second column in its column representation. In this case, `fAuxiliaryColumn` points into
292 /// `fAvailableColumns` to the column that immediately follows the column `fPrincipalColumn` points to.
294 /// The columns are connected either to a sink or to a source (not to both); they are owned by the field.
295 /// Contains all columns of all representations in order of representation and column index.
296 std::vector<std::unique_ptr<ROOT::Internal::RColumn>> fAvailableColumns;
297 /// Properties of the type that allow for optimizations of collections of that type
298 std::uint32_t fTraits = 0;
299 /// A typedef or using name that was used when creating the field
300 std::string fTypeAlias;
301 /// List of functions to be called after reading a value
302 std::vector<ReadCallback_t> fReadCallbacks;
303 /// C++ type version cached from the descriptor after a call to ConnectPageSource()
305 /// TClass checksum cached from the descriptor after a call to ConnectPageSource(). Only set
306 /// for classes with dictionaries.
307 std::uint32_t fOnDiskTypeChecksum = 0;
308 /// Pointers into the static vector returned by RColumnRepresentations::GetSerializationTypes() when
309 /// SetColumnRepresentatives() is called. Otherwise (if empty) GetColumnRepresentatives() returns a vector
310 /// with a single element, the default representation. Always empty for artificial fields.
311 std::vector<std::reference_wrapper<const ColumnRepresentation_t>> fColumnRepresentatives;
312
313 /// Factory method for the field's type. The caller owns the returned pointer
314 void *CreateObjectRawPtr() const;
315
316 /// Helpers for generating columns. We use the fact that most fields have the same C++/memory types
317 /// for all their column representations.
318 /// Where possible, we call the helpers not from the header to reduce compilation time.
319 template <std::uint32_t ColumnIndexT, typename HeadT, typename... TailTs>
321 {
323 auto &column = fAvailableColumns.emplace_back(
324 ROOT::Internal::RColumn::Create<HeadT>(representation[ColumnIndexT], ColumnIndexT, representationIndex));
325
326 // Initially, the first two columns become the active column representation
328 fPrincipalColumn = column.get();
329 } else if (representationIndex == 0 && !fAuxiliaryColumn) {
330 fAuxiliaryColumn = column.get();
331 } else {
332 // We currently have no fields with more than 2 columns in its column representation
334 }
335
336 if constexpr (sizeof...(TailTs))
338 }
339
340 /// For writing, use the currently set column representative
341 template <typename... ColumnCppTs>
343 {
344 if (fColumnRepresentatives.empty()) {
345 fAvailableColumns.reserve(sizeof...(ColumnCppTs));
346 GenerateColumnsImpl<0, ColumnCppTs...>(GetColumnRepresentations().GetSerializationDefault(), 0);
347 } else {
348 const auto N = fColumnRepresentatives.size();
349 fAvailableColumns.reserve(N * sizeof...(ColumnCppTs));
350 for (unsigned i = 0; i < N; ++i) {
352 }
353 }
354 }
355
356 /// For reading, use the on-disk column list
357 template <typename... ColumnCppTs>
359 {
360 std::uint16_t representationIndex = 0;
361 do {
363 if (onDiskTypes.empty())
364 break;
367 if (representationIndex > 0) {
368 for (std::size_t i = 0; i < sizeof...(ColumnCppTs); ++i) {
369 fAvailableColumns[i]->MergeTeams(
370 *fAvailableColumns[representationIndex * sizeof...(ColumnCppTs) + i].get());
371 }
372 }
374 } while (true);
375 }
376
377 /// Implementations in derived classes should return a static RColumnRepresentations object. The default
378 /// implementation does not attach any columns to the field.
379 virtual const RColumnRepresentations &GetColumnRepresentations() const;
380 /// Implementations in derived classes should create the backing columns corresponding to the field type for
381 /// writing. The default implementation does not attach any columns to the field.
382 virtual void GenerateColumns() {}
383 /// Implementations in derived classes should create the backing columns corresponding to the field type for reading.
384 /// The default implementation does not attach any columns to the field. The method should check, using the page
385 /// source and `fOnDiskId`, if the column types match and throw if they don't.
386 virtual void GenerateColumns(const ROOT::RNTupleDescriptor & /*desc*/) {}
387 /// Returns the on-disk column types found in the provided descriptor for `fOnDiskId` and the given
388 /// representation index. If there are no columns for the given representation index, return an empty
389 /// ColumnRepresentation_t list. Otherwise, the returned reference points into the static array returned by
390 /// GetColumnRepresentations().
391 /// Throws an exception if the types on disk don't match any of the deserialization types from
392 /// GetColumnRepresentations().
395 /// When connecting a field to a page sink, the field's default column representation is subject
396 /// to adjustment according to the write options. E.g., if compression is turned off, encoded columns
397 /// are changed to their unencoded counterparts.
399
400 /// Called by Clone(), which additionally copies the on-disk ID
401 virtual std::unique_ptr<RFieldBase> CloneImpl(std::string_view newName) const = 0;
402
403 /// Constructs value in a given location of size at least GetValueSize(). Called by the base class' CreateValue().
404 virtual void ConstructValue(void *where) const = 0;
405 virtual std::unique_ptr<RDeleter> GetDeleter() const { return std::make_unique<RDeleter>(); }
406 /// Allow derived classes to call ConstructValue(void *) and GetDeleter() on other (sub)fields.
407 static void CallConstructValueOn(const RFieldBase &other, void *where) { other.ConstructValue(where); }
408 static std::unique_ptr<RDeleter> GetDeleterOf(const RFieldBase &other) { return other.GetDeleter(); }
409
410 /// Operations on values of complex types, e.g. ones that involve multiple columns or for which no direct
411 /// column type exists.
412 virtual std::size_t AppendImpl(const void *from);
413 virtual void ReadGlobalImpl(ROOT::NTupleSize_t globalIndex, void *to);
414 virtual void ReadInClusterImpl(RNTupleLocalIndex localIndex, void *to);
415
416 /// Write the given value into columns. The value object has to be of the same type as the field.
417 /// Returns the number of uncompressed bytes written.
418 std::size_t Append(const void *from);
419
420 /// Populate a single value with data from the field. The memory location pointed to by to needs to be of the
421 /// fitting type. The fast path is conditioned by the field qualifying as simple, i.e. maps as-is
422 /// to a single column and has no read callback.
424 {
425 if (fIsSimple)
426 return (void)fPrincipalColumn->Read(globalIndex, to);
427
428 if (!fIsArtificial) {
431 else
433 }
434 if (R__unlikely(!fReadCallbacks.empty()))
436 }
437
438 /// Populate a single value with data from the field. The memory location pointed to by to needs to be of the
439 /// fitting type. The fast path is conditioned by the field qualifying as simple, i.e. maps as-is
440 /// to a single column and has no read callback.
442 {
443 if (fIsSimple)
444 return (void)fPrincipalColumn->Read(localIndex, to);
445
446 if (!fIsArtificial) {
449 else
451 }
452 if (R__unlikely(!fReadCallbacks.empty()))
454 }
455
456 /// General implementation of bulk read. Loop over the required range and read values that are required
457 /// and not already present. Derived classes may implement more optimized versions of this method.
458 /// See ReadBulk() for the return value.
459 virtual std::size_t ReadBulkImpl(const RBulkSpec &bulkSpec);
460
461 /// Returns the number of newly available values, that is the number of bools in `bulkSpec.fMaskAvail` that
462 /// flipped from false to true. As a special return value, `kAllSet` can be used if all values are read
463 /// independent from the masks.
464 std::size_t ReadBulk(const RBulkSpec &bulkSpec);
465
466 /// Allow derived classes to call Append() and Read() on other (sub)fields.
467 static std::size_t CallAppendOn(RFieldBase &other, const void *from) { return other.Append(from); }
470 static void *CallCreateObjectRawPtrOn(RFieldBase &other) { return other.CreateObjectRawPtr(); }
471
472 /// Fields may need direct access to the principal column of their subfields, e.g. in RRVecField::ReadBulk()
473 static ROOT::Internal::RColumn *GetPrincipalColumnOf(const RFieldBase &other) { return other.fPrincipalColumn; }
474
475 /// Set a user-defined function to be called after reading a value, giving a chance to inspect and/or modify the
476 /// value object.
477 /// Returns an index that can be used to remove the callback.
478 size_t AddReadCallback(ReadCallback_t func);
479 void RemoveReadCallback(size_t idx);
480
481 // Perform housekeeping tasks for global to cluster-local index translation
482 virtual void CommitClusterImpl() {}
483 // The field can indicate that it needs to register extra type information in the on-disk schema.
484 // In this case, a callback from the page sink to the field will be registered on connect, so that the
485 // extra type information can be collected when the dataset gets committed.
486 virtual bool HasExtraTypeInfo() const { return false; }
487 // The page sink's callback when the data set gets committed will call this method to get the field's extra
488 // type information. This has to happen at the end of writing because the type information may change depending
489 // on the data that's written, e.g. for polymorphic types in the streamer field.
491
492 /// Add a new subfield to the list of nested fields
493 void Attach(std::unique_ptr<RFieldBase> child);
494
495 /// Called by ConnectPageSource() before connecting; derived classes may override this as appropriate
497
498 /// Called by ConnectPageSource() once connected; derived classes may override this as appropriate
499 virtual void AfterConnectPageSource() {}
500
501 /// Factory method to resurrect a field from the stored on-disk type information. This overload takes an already
502 /// normalized type name and type alias.
503 /// `desc` and `fieldId` must be passed if `options.fEmulateUnknownTypes` is true, otherwise they can be left blank.
505 Create(const std::string &fieldName, const std::string &typeName, const ROOT::RCreateFieldOptions &options,
507
508public:
509 template <bool IsConstT>
510 class RSchemaIteratorTemplate;
513
514 // This is used in CreateObject() and is specialized for void
515 template <typename T>
517 using deleter = std::default_delete<T>;
518 };
519
520 /// Used in the return value of the Check() method
522 std::string fFieldName; ///< Qualified field name causing the error
523 std::string fTypeName; ///< Type name corresponding to the (sub)field
524 std::string fErrMsg; ///< Cause of the failure, e.g. unsupported type
525 };
526
527 /// The constructor creates the underlying column objects and connects them to either a sink or a source.
528 /// If `isSimple` is `true`, the trait `kTraitMappable` is automatically set on construction. However, the
529 /// field might be demoted to non-simple if a post-read callback is set.
530 RFieldBase(std::string_view name, std::string_view type, ROOT::ENTupleStructure structure, bool isSimple,
531 std::size_t nRepetitions = 0);
532 RFieldBase(const RFieldBase &) = delete;
533 RFieldBase(RFieldBase &&) = default;
534 RFieldBase &operator=(const RFieldBase &) = delete;
536 virtual ~RFieldBase() = default;
537
538 /// Copies the field and its subfields using a possibly new name and a new, unconnected set of columns
539 std::unique_ptr<RFieldBase> Clone(std::string_view newName) const;
540
541 /// Factory method to create a field from a certain type given as string.
542 /// Note that the provided type name must be a valid C++ type name. Template arguments of templated types
543 /// must be type names or integers (e.g., no expressions).
545 Create(const std::string &fieldName, const std::string &typeName);
546
547 /// Checks if the given type is supported by RNTuple. In case of success, the result vector is empty.
548 /// Otherwise there is an error record for each failing subfield (subtype).
549 static std::vector<RCheckResult> Check(const std::string &fieldName, const std::string &typeName);
550
551 /// Generates an object of the field type and allocates new initialized memory according to the type.
552 /// Implemented at the end of this header because the implementation is using RField<T>::TypeName()
553 /// The returned object can be released with `delete`, i.e. it is valid to call:
554 /// ~~~{.cpp}
555 /// auto ptr = field->CreateObject();
556 /// delete ptr.release();
557 /// ~~~
558 ///
559 /// Note that CreateObject<void>() is supported. The returned `unique_ptr` has a custom deleter that reports an error
560 /// if it is called. The intended use of the returned `unique_ptr<void>` is to call `release()`. In this way, the
561 /// transfer of pointer ownership is explicit.
562 template <typename T>
563 std::unique_ptr<T, typename RCreateObjectDeleter<T>::deleter> CreateObject() const;
564 /// Generates an object of the field's type, wraps it in a shared pointer and returns it as an RValue connected to
565 /// the field.
567 /// Creates a new, initially empty bulk.
568 /// RBulkValues::ReadBulk() will construct the array of values. The memory of the value array is managed by the
569 /// RBulkValues class.
571 /// Creates a value from a memory location with an already constructed object
572 RValue BindValue(std::shared_ptr<void> objPtr);
573 /// Creates the list of direct child values given an existing value for this field. E.g. a single value for the
574 /// correct `std::variant` or all the elements of a collection. The default implementation assumes no subvalues
575 /// and returns an empty vector.
576 virtual std::vector<RValue> SplitValue(const RValue &value) const;
577 /// The number of bytes taken by a value of the appropriate type
578 virtual size_t GetValueSize() const = 0;
579 /// As a rule of thumb, the alignment is equal to the size of the type. There are, however, various exceptions
580 /// to this rule depending on OS and CPU architecture. So enforce the alignment to be explicitly spelled out.
581 virtual size_t GetAlignment() const = 0;
582 std::uint32_t GetTraits() const { return fTraits; }
583 bool HasReadCallbacks() const { return !fReadCallbacks.empty(); }
584
585 const std::string &GetFieldName() const { return fName; }
586 /// Returns the field name and parent field names separated by dots (`grandparent.parent.child`)
587 std::string GetQualifiedFieldName() const;
588 const std::string &GetTypeName() const { return fType; }
589 const std::string &GetTypeAlias() const { return fTypeAlias; }
591 std::size_t GetNRepetitions() const { return fNRepetitions; }
592 const RFieldBase *GetParent() const { return fParent; }
593 std::vector<RFieldBase *> GetMutableSubfields();
594 std::vector<const RFieldBase *> GetConstSubfields() const;
595 bool IsSimple() const { return fIsSimple; }
596 bool IsArtificial() const { return fIsArtificial; }
597 /// Get the field's description
598 const std::string &GetDescription() const { return fDescription; }
599 void SetDescription(std::string_view description);
600 EState GetState() const { return fState; }
601
604
605 /// Returns the `fColumnRepresentative` pointee or, if unset (always the case for artificial fields), the field's
606 /// default representative
608 /// Fixes a column representative. This can only be done _before_ connecting the field to a page sink.
609 /// Otherwise, or if the provided representation is not in the list of GetColumnRepresentations(),
610 /// an exception is thrown
612 /// Whether or not an explicit column representative was set
614
615 /// Indicates an evolution of the mapping scheme from C++ type to columns
616 virtual std::uint32_t GetFieldVersion() const { return 0; }
617 /// Indicates an evolution of the C++ type itself
618 virtual std::uint32_t GetTypeVersion() const { return 0; }
619 /// Return the current TClass reported checksum of this class. Only valid if `kTraitTypeChecksum` is set.
620 virtual std::uint32_t GetTypeChecksum() const { return 0; }
621 /// Return the C++ type version stored in the field descriptor; only valid after a call to ConnectPageSource()
622 std::uint32_t GetOnDiskTypeVersion() const { return fOnDiskTypeVersion; }
623 /// Return checksum stored in the field descriptor; only valid after a call to ConnectPageSource(),
624 /// if the field stored a type checksum
625 std::uint32_t GetOnDiskTypeChecksum() const { return fOnDiskTypeChecksum; }
626
633
635}; // class RFieldBase
636
637/// Iterates over the subtree of fields in depth-first search order
638template <bool IsConstT>
640private:
641 struct Position {
642 using FieldPtr_t = std::conditional_t<IsConstT, const RFieldBase *, RFieldBase *>;
643 Position() : fFieldPtr(nullptr), fIdxInParent(-1) {}
647 };
648 /// The stack of nodes visited when walking down the tree of fields
649 std::vector<Position> fStack;
650
651public:
653 using iterator_category = std::forward_iterator_tag;
654 using difference_type = std::ptrdiff_t;
655 using value_type = std::conditional_t<IsConstT, const RFieldBase, RFieldBase>;
656 using pointer = std::conditional_t<IsConstT, const RFieldBase *, RFieldBase *>;
657 using reference = std::conditional_t<IsConstT, const RFieldBase &, RFieldBase &>;
658
662 /// Given that the iterator points to a valid field which is not the end iterator, go to the next field
663 /// in depth-first search order
664 void Advance()
665 {
666 auto itr = fStack.rbegin();
667 if (!itr->fFieldPtr->fSubfields.empty()) {
668 fStack.emplace_back(Position(itr->fFieldPtr->fSubfields[0].get(), 0));
669 return;
670 }
671
672 unsigned int nextIdxInParent = ++(itr->fIdxInParent);
673 while (nextIdxInParent >= itr->fFieldPtr->fParent->fSubfields.size()) {
674 if (fStack.size() == 1) {
675 itr->fFieldPtr = itr->fFieldPtr->fParent;
676 itr->fIdxInParent = -1;
677 return;
678 }
679 fStack.pop_back();
680 itr = fStack.rbegin();
681 nextIdxInParent = ++(itr->fIdxInParent);
682 }
683 itr->fFieldPtr = itr->fFieldPtr->fParent->fSubfields[nextIdxInParent].get();
684 }
685
686 iterator operator++(int) /* postfix */
687 {
688 auto r = *this;
689 Advance();
690 return r;
691 }
692 iterator &operator++() /* prefix */
693 {
694 Advance();
695 return *this;
696 }
697 reference operator*() const { return *fStack.back().fFieldPtr; }
698 pointer operator->() const { return fStack.back().fFieldPtr; }
699 bool operator==(const iterator &rh) const { return fStack.back().fFieldPtr == rh.fStack.back().fFieldPtr; }
700 bool operator!=(const iterator &rh) const { return fStack.back().fFieldPtr != rh.fStack.back().fFieldPtr; }
701};
702
703/// Points to an object with RNTuple I/O support and keeps a pointer to the corresponding field.
704/// Fields can create RValue objects through RFieldBase::CreateValue(), RFieldBase::BindValue()) or
705/// RFieldBase::SplitValue().
707 friend class RFieldBase;
708 friend class ROOT::REntry;
709
710private:
711 RFieldBase *fField = nullptr; ///< The field that created the RValue
712 /// Set by Bind() or by RFieldBase::CreateValue(), RFieldBase::SplitValue() or RFieldBase::BindValue()
713 std::shared_ptr<void> fObjPtr;
714 mutable std::atomic<const std::type_info *> fTypeInfo = nullptr;
715
716 RValue(RFieldBase *field, std::shared_ptr<void> objPtr) : fField(field), fObjPtr(objPtr) {}
717
718public:
721 {
722 fField = other.fField;
723 fObjPtr = other.fObjPtr;
724 // We could copy over the cached type info, or just start with a fresh state...
725 fTypeInfo = nullptr;
726 return *this;
727 }
730 {
731 fField = other.fField;
732 fObjPtr = other.fObjPtr;
733 // We could copy over the cached type info, or just start with a fresh state...
734 fTypeInfo = nullptr;
735 return *this;
736 }
737 ~RValue() = default;
738
739private:
740 template <typename T>
742 {
743 if constexpr (!std::is_void_v<T>) {
744 const std::type_info &ti = typeid(T);
745 // Fast path: if we had a matching type before, try comparing the type_info's. This may still fail in case the
746 // type has a suppressed template argument that may change the typeid.
747 auto *cachedTypeInfo = fTypeInfo.load();
748 if (cachedTypeInfo != nullptr && *cachedTypeInfo == ti) {
749 return;
750 }
753 fTypeInfo.store(&ti);
754 return;
755 }
756 throw RException(R__FAIL("type mismatch for field \"" + fField->GetFieldName() + "\": expected " +
757 fField->GetTypeName() + ", got " + renormalizedTypeName));
758 }
759 }
760
761 std::size_t Append() { return fField->Append(fObjPtr.get()); }
762
763public:
766
767 void Bind(std::shared_ptr<void> objPtr) { fObjPtr = objPtr; }
768 void BindRawPtr(void *rawPtr);
769 /// Replace the current object pointer by a pointer to a new object constructed by the field
770 void EmplaceNew() { fObjPtr = fField->CreateValue().GetPtr<void>(); }
771
772 template <typename T>
773 std::shared_ptr<T> GetPtr() const
774 {
776 return std::static_pointer_cast<T>(fObjPtr);
777 }
778
779 template <typename T>
780 const T &GetRef() const
781 {
783 return *static_cast<T *>(fObjPtr.get());
784 }
785
786 const RFieldBase &GetField() const { return *fField; }
787};
788
789/// Input parameter to RFieldBase::ReadBulk() and RFieldBase::ReadBulkImpl().
790// See the RBulkValues class documentation for more information.
792 /// Possible return value of ReadBulk() and ReadBulkImpl(), which indicates that the full bulk range was read
793 /// independently of the provided masks.
794 static const std::size_t kAllSet = std::size_t(-1);
795
796 RNTupleLocalIndex fFirstIndex; ///< Start of the bulk range
797 std::size_t fCount = 0; ///< Size of the bulk range
798 /// A bool array of size fCount, indicating the required values in the requested range
799 const bool *fMaskReq = nullptr;
800 bool *fMaskAvail = nullptr; ///< A bool array of size `fCount`, indicating the valid values in fValues
801 /// The destination area, which has to be an array of valid objects of the correct type large enough to hold the bulk
802 /// range.
803 void *fValues = nullptr;
804 /// Reference to memory owned by the RBulkValues class. The field implementing BulkReadImpl() may use `fAuxData` as
805 /// memory that stays persistent between calls.
806 std::vector<unsigned char> *fAuxData = nullptr;
807};
808
809// clang-format off
810/**
811\class ROOT::RFieldBase::RBulkValues
812\ingroup NTuple
813\brief Points to an array of objects with RNTuple I/O support, used for bulk reading.
814
815Similar to RValue, but manages an array of consecutive values. Bulks have to come from the same cluster.
816Bulk I/O works with two bit masks: the mask of all the available entries in the current bulk and the mask
817of the required entries in a bulk read. The idea is that a single bulk may serve multiple read operations
818on the same range, where in each read operation a different subset of values is required.
819The memory of the value array is managed by the RBulkValues class.
820*/
821// clang-format on
823private:
824 friend class RFieldBase;
825
826 RFieldBase *fField = nullptr; ///< The field that created the array of values
827 std::unique_ptr<RFieldBase::RDeleter> fDeleter; /// Cached deleter of fField
828 void *fValues = nullptr; ///< Pointer to the start of the array
829 std::size_t fValueSize = 0; ///< Cached copy of RFieldBase::GetValueSize()
830 std::size_t fCapacity = 0; ///< The size of the array memory block in number of values
831 std::size_t fSize = 0; ///< The number of available values in the array (provided their mask is set)
832 bool fIsAdopted = false; ///< True if the user provides the memory buffer for fValues
833 std::unique_ptr<bool[]> fMaskAvail; ///< Masks invalid values in the array
834 std::size_t fNValidValues = 0; ///< The sum of non-zero elements in the fMask
835 RNTupleLocalIndex fFirstIndex; ///< Index of the first value of the array
836 /// Reading arrays of complex values may require additional memory, for instance for the elements of
837 /// arrays of vectors. A pointer to the `fAuxData` array is passed to the field's BulkRead method.
838 /// The RBulkValues class does not modify the array in-between calls to the field's BulkRead method.
839 std::vector<unsigned char> fAuxData;
840
841 void ReleaseValues();
842 /// Sets a new range for the bulk. If there is enough capacity, the `fValues` array will be reused.
843 /// Otherwise a new array is allocated. After reset, fMaskAvail is false for all values.
844 void Reset(RNTupleLocalIndex firstIndex, std::size_t size);
845 void CountValidValues();
846
848 {
849 if (firstIndex.GetClusterId() != fFirstIndex.GetClusterId())
850 return false;
851 return (firstIndex.GetIndexInCluster() >= fFirstIndex.GetIndexInCluster()) &&
852 ((firstIndex.GetIndexInCluster() + size) <= (fFirstIndex.GetIndexInCluster() + fSize));
853 }
854
855 void *GetValuePtrAt(std::size_t idx) const { return reinterpret_cast<unsigned char *>(fValues) + idx * fValueSize; }
856
861
862public:
863 ~RBulkValues();
864 RBulkValues(const RBulkValues &) = delete;
868
869 // Sets `fValues` and `fSize`/`fCapacity` to the given values. The capacity is specified in number of values.
870 // Once a buffer is adopted, an attempt to read more values then available throws an exception.
871 void AdoptBuffer(void *buf, std::size_t capacity);
872
873 /// Reads `size` values from the associated field, starting from `firstIndex`. Note that the index is given
874 /// relative to a certain cluster. The return value points to the array of read objects.
875 /// The `maskReq` parameter is a bool array of at least `size` elements. Only objects for which the mask is
876 /// true are guaranteed to be read in the returned value array. A `nullptr` means to read all elements.
877 void *ReadBulk(RNTupleLocalIndex firstIndex, const bool *maskReq, std::size_t size)
878 {
881
882 // We may read a subrange of the currently available range
883 auto offset = firstIndex.GetIndexInCluster() - fFirstIndex.GetIndexInCluster();
884
885 if (fNValidValues == fSize)
886 return GetValuePtrAt(offset);
887
889 bulkSpec.fFirstIndex = firstIndex;
890 bulkSpec.fCount = size;
891 bulkSpec.fMaskReq = maskReq;
892 bulkSpec.fMaskAvail = &fMaskAvail[offset];
893 bulkSpec.fValues = GetValuePtrAt(offset);
894 bulkSpec.fAuxData = &fAuxData;
895 auto nRead = fField->ReadBulk(bulkSpec);
896 if (nRead == RBulkSpec::kAllSet) {
897 if ((offset == 0) && (size == fSize)) {
899 } else {
901 }
902 } else {
904 }
905 return GetValuePtrAt(offset);
906 }
907
908 /// Overload to read all elements in the given cluster range.
909 void *ReadBulk(ROOT::RNTupleLocalRange range) { return ReadBulk(*range.begin(), nullptr, range.size()); }
910};
911
912namespace Internal {
913// At some point, RFieldBase::OnClusterCommit() may allow for a user-defined callback to change the
914// column representation. For now, we inject this for testing and internal use only.
917 {
918 R__ASSERT(newRepresentationIdx < field.fColumnRepresentatives.size());
919 const auto N = field.fColumnRepresentatives[0].get().size();
920 R__ASSERT(N >= 1 && N <= 2);
921 R__ASSERT(field.fPrincipalColumn);
922 field.fPrincipalColumn = field.fAvailableColumns[newRepresentationIdx * N].get();
923 if (field.fAuxiliaryColumn) {
924 R__ASSERT(N == 2);
925 field.fAuxiliaryColumn = field.fAvailableColumns[newRepresentationIdx * N + 1].get();
926 }
927 }
928};
929} // namespace Internal
930} // namespace ROOT
931
932#endif
#define R__unlikely(expr)
Definition RConfig.hxx:594
#define R__FAIL(msg)
Short-hand to return an RResult<T> in an error state; the RError is implicitly converted into RResult...
Definition RError.hxx:300
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.
#define R__ASSERT(e)
Checks condition e and reports a fatal error if it's false.
Definition TError.h:125
#define N
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 offset
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 target
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 Int_t Int_t Window_t child
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
Abstract base class for classes implementing the visitor design pattern.
A container of const raw pointers, corresponding to a row in the data set.
A column is a storage-backed array of a simple, fixed-size type, from which pages can be mapped into ...
Definition RColumn.hxx:38
void Read(const ROOT::NTupleSize_t globalIndex, void *to)
Definition RColumn.hxx:160
Abstract interface to write data into an ntuple.
Abstract interface to read data from an ntuple.
The field for a class with dictionary.
Definition RField.hxx:113
The REntry is a collection of values in an RNTuple corresponding to a complete row in the data set.
Definition REntry.hxx:54
Base class for all ROOT issued exceptions.
Definition RError.hxx:79
Field specific extra type information from the header / extenstion header.
Points to an array of objects with RNTuple I/O support, used for bulk reading.
std::unique_ptr< bool[]> fMaskAvail
Masks invalid values in the array.
std::unique_ptr< RFieldBase::RDeleter > fDeleter
void * ReadBulk(RNTupleLocalIndex firstIndex, const bool *maskReq, std::size_t size)
Reads size values from the associated field, starting from firstIndex.
void * GetValuePtrAt(std::size_t idx) const
bool ContainsRange(RNTupleLocalIndex firstIndex, std::size_t size) const
std::size_t fNValidValues
The sum of non-zero elements in the fMask.
bool fIsAdopted
True if the user provides the memory buffer for fValues.
void Reset(RNTupleLocalIndex firstIndex, std::size_t size)
Sets a new range for the bulk.
void * fValues
Cached deleter of fField.
std::size_t fCapacity
The size of the array memory block in number of values.
void * ReadBulk(ROOT::RNTupleLocalRange range)
Overload to read all elements in the given cluster range.
std::size_t fValueSize
Cached copy of RFieldBase::GetValueSize()
RFieldBase * fField
The field that created the array of values.
RBulkValues & operator=(const RBulkValues &)=delete
RBulkValues(RFieldBase *field)
std::size_t fSize
The number of available values in the array (provided their mask is set)
void AdoptBuffer(void *buf, std::size_t capacity)
std::vector< unsigned char > fAuxData
Reading arrays of complex values may require additional memory, for instance for the elements of arra...
RNTupleLocalIndex fFirstIndex
Index of the first value of the array.
RBulkValues(const RBulkValues &)=delete
The list of column representations a field can have.
const Selection_t & GetSerializationTypes() const
const Selection_t & GetDeserializationTypes() const
const ColumnRepresentation_t & GetSerializationDefault() const
The first column list from fSerializationTypes is the default for writing.
std::vector< ColumnRepresentation_t > Selection_t
A list of column representations.
Selection_t fDeserializationTypes
The union of the serialization types and the deserialization extra types passed during construction.
A functor to release the memory acquired by CreateValue() (memory and constructor).
virtual void operator()(void *objPtr, bool dtorOnly)
virtual ~RDeleter()=default
Iterates over the subtree of fields in depth-first search order.
std::vector< Position > fStack
The stack of nodes visited when walking down the tree of fields.
bool operator==(const iterator &rh) const
std::conditional_t< IsConstT, const RFieldBase &, RFieldBase & > reference
std::conditional_t< IsConstT, const RFieldBase *, RFieldBase * > pointer
std::conditional_t< IsConstT, const RFieldBase, RFieldBase > value_type
std::forward_iterator_tag iterator_category
void Advance()
Given that the iterator points to a valid field which is not the end iterator, go to the next field i...
bool operator!=(const iterator &rh) const
RSchemaIteratorTemplate(pointer val, int idxInParent)
A deleter for templated RFieldBase descendents where the value type is known.
void operator()(void *objPtr, bool dtorOnly) final
Points to an object with RNTuple I/O support and keeps a pointer to the corresponding field.
std::shared_ptr< void > fObjPtr
Set by Bind() or by RFieldBase::CreateValue(), RFieldBase::SplitValue() or RFieldBase::BindValue()
RValue & operator=(const RValue &other)
void Read(ROOT::NTupleSize_t globalIndex)
void EmplaceNew()
Replace the current object pointer by a pointer to a new object constructed by the field.
void EnsureMatchingType() const
void Bind(std::shared_ptr< void > objPtr)
void Read(RNTupleLocalIndex localIndex)
RValue(const RValue &other)
RValue & operator=(RValue &&other)
const RFieldBase & GetField() const
std::atomic< const std::type_info * > fTypeInfo
std::shared_ptr< T > GetPtr() const
RFieldBase * fField
The field that created the RValue.
RValue(RFieldBase *field, std::shared_ptr< void > objPtr)
void BindRawPtr(void *rawPtr)
const T & GetRef() const
A field translates read and write calls from/to underlying columns to/from tree values.
ROOT::DescriptorId_t fOnDiskId
When the columns are connected to a page source or page sink, the field represents a field id in the ...
ROOT::ENTupleStructure GetStructure() const
virtual size_t GetValueSize() const =0
The number of bytes taken by a value of the appropriate type.
static constexpr std::uint32_t kInvalidTypeVersion
RSchemaIterator end()
void SetColumnRepresentatives(const RColumnRepresentations::Selection_t &representatives)
Fixes a column representative.
void InvokeReadCallbacks(void *target)
ROOT::Internal::RColumn * fPrincipalColumn
All fields that have columns have a distinct main column.
virtual size_t GetAlignment() const =0
As a rule of thumb, the alignment is equal to the size of the type.
virtual std::unique_ptr< RDeleter > GetDeleter() const
ROOT::NTupleSize_t EntryToColumnElementIndex(ROOT::NTupleSize_t globalIndex) const
Translate an entry index to a column element index of the principal column and vice versa.
void Attach(std::unique_ptr< RFieldBase > child)
Add a new subfield to the list of nested fields.
virtual void AcceptVisitor(ROOT::Detail::RFieldVisitor &visitor) const
void FlushColumns()
Flushes data from active columns.
virtual void ReadGlobalImpl(ROOT::NTupleSize_t globalIndex, void *to)
std::vector< std::unique_ptr< RFieldBase > > fSubfields
Collections and classes own subfields.
std::uint32_t GetOnDiskTypeVersion() const
Return the C++ type version stored in the field descriptor; only valid after a call to ConnectPageSou...
virtual const RColumnRepresentations & GetColumnRepresentations() const
Implementations in derived classes should return a static RColumnRepresentations object.
EState
During its lifetime, a field undergoes the following possible state transitions:
bool fIsSimple
A field qualifies as simple if it is mappable (which implies it has a single principal column),...
RConstSchemaIterator cbegin() const
std::unique_ptr< T, typename RCreateObjectDeleter< T >::deleter > CreateObject() const
Generates an object of the field type and allocates new initialized memory according to the type.
Definition RField.hxx:519
RFieldBase & operator=(const RFieldBase &)=delete
virtual void AfterConnectPageSource()
Called by ConnectPageSource() once connected; derived classes may override this as appropriate.
virtual void GenerateColumns(const ROOT::RNTupleDescriptor &)
Implementations in derived classes should create the backing columns corresponding to the field type ...
void AutoAdjustColumnTypes(const ROOT::RNTupleWriteOptions &options)
When connecting a field to a page sink, the field's default column representation is subject to adjus...
virtual void ConstructValue(void *where) const =0
Constructs value in a given location of size at least GetValueSize(). Called by the base class' Creat...
std::vector< const RFieldBase * > GetConstSubfields() const
void SetOnDiskId(ROOT::DescriptorId_t id)
void RemoveReadCallback(size_t idx)
void GenerateColumnsImpl(const ROOT::RNTupleDescriptor &desc)
For reading, use the on-disk column list.
virtual void GenerateColumns()
Implementations in derived classes should create the backing columns corresponding to the field type ...
void Read(RNTupleLocalIndex localIndex, void *to)
Populate a single value with data from the field.
const RFieldBase * GetParent() const
std::vector< RFieldBase * > GetMutableSubfields()
std::string fDescription
Free text set by the user.
static std::unique_ptr< RDeleter > GetDeleterOf(const RFieldBase &other)
static ROOT::Internal::RColumn * GetPrincipalColumnOf(const RFieldBase &other)
Fields may need direct access to the principal column of their subfields, e.g. in RRVecField::ReadBul...
static std::vector< RCheckResult > Check(const std::string &fieldName, const std::string &typeName)
Checks if the given type is supported by RNTuple.
RSchemaIterator begin()
ROOT::Internal::RColumn * fAuxiliaryColumn
Some fields have a second column in its column representation.
size_t AddReadCallback(ReadCallback_t func)
Set a user-defined function to be called after reading a value, giving a chance to inspect and/or mod...
RConstSchemaIterator cend() const
std::size_t fNRepetitions
For fixed sized arrays, the array length.
std::function< void(void *)> ReadCallback_t
virtual void BeforeConnectPageSource(ROOT::Internal::RPageSource &)
Called by ConnectPageSource() before connecting; derived classes may override this as appropriate.
std::size_t Append(const void *from)
Write the given value into columns.
RValue CreateValue()
Generates an object of the field's type, wraps it in a shared pointer and returns it as an RValue con...
RSchemaIteratorTemplate< false > RSchemaIterator
const ColumnRepresentation_t & EnsureCompatibleColumnTypes(const ROOT::RNTupleDescriptor &desc, std::uint16_t representationIndex) const
Returns the on-disk column types found in the provided descriptor for fOnDiskId and the given represe...
RFieldBase(RFieldBase &&)=default
virtual std::vector< RValue > SplitValue(const RValue &value) const
Creates the list of direct child values given an existing value for this field.
virtual std::unique_ptr< RFieldBase > CloneImpl(std::string_view newName) const =0
Called by Clone(), which additionally copies the on-disk ID.
std::string GetQualifiedFieldName() const
Returns the field name and parent field names separated by dots (grandparent.parent....
RBulkValues CreateBulk()
Creates a new, initially empty bulk.
const std::string & GetFieldName() const
void ConnectPageSink(ROOT::Internal::RPageSink &pageSink, ROOT::NTupleSize_t firstEntry=0)
Fields and their columns live in the void until connected to a physical page storage.
std::size_t ReadBulk(const RBulkSpec &bulkSpec)
Returns the number of newly available values, that is the number of bools in bulkSpec....
std::vector< ROOT::ENTupleColumnType > ColumnRepresentation_t
std::vector< ReadCallback_t > fReadCallbacks
List of functions to be called after reading a value.
RFieldBase & operator=(RFieldBase &&)=default
const std::string & GetTypeAlias() const
static void CallReadOn(RFieldBase &other, ROOT::NTupleSize_t globalIndex, void *to)
virtual ~RFieldBase()=default
static std::size_t CallAppendOn(RFieldBase &other, const void *from)
Allow derived classes to call Append() and Read() on other (sub)fields.
virtual void ReadInClusterImpl(RNTupleLocalIndex localIndex, void *to)
virtual void CommitClusterImpl()
std::vector< std::reference_wrapper< const ColumnRepresentation_t > > fColumnRepresentatives
Pointers into the static vector returned by RColumnRepresentations::GetSerializationTypes() when SetC...
std::uint32_t fTraits
Properties of the type that allow for optimizations of collections of that type.
friend struct ROOT::Internal::RFieldCallbackInjector
virtual std::size_t AppendImpl(const void *from)
Operations on values of complex types, e.g.
RFieldBase * fParent
Subfields point to their mother field.
std::vector< std::unique_ptr< ROOT::Internal::RColumn > > fAvailableColumns
The columns are connected either to a sink or to a source (not to both); they are owned by the field.
RFieldBase(std::string_view name, std::string_view type, ROOT::ENTupleStructure structure, bool isSimple, std::size_t nRepetitions=0)
The constructor creates the underlying column objects and connects them to either a sink or a source.
EState fState
Changed by ConnectTo[Sink,Source], reset by Clone()
static void * CallCreateObjectRawPtrOn(RFieldBase &other)
bool IsArtificial() const
static RResult< std::unique_ptr< RFieldBase > > Create(const std::string &fieldName, const std::string &typeName, const ROOT::RCreateFieldOptions &options, const ROOT::RNTupleDescriptor *desc, ROOT::DescriptorId_t fieldId)
Factory method to resurrect a field from the stored on-disk type information.
const std::string & GetDescription() const
Get the field's description.
bool HasReadCallbacks() const
std::string fTypeAlias
A typedef or using name that was used when creating the field.
virtual std::uint32_t GetFieldVersion() const
Indicates an evolution of the mapping scheme from C++ type to columns.
std::string fType
The C++ type captured by this field.
RColumnRepresentations::Selection_t GetColumnRepresentatives() const
Returns the fColumnRepresentative pointee or, if unset (always the case for artificial fields),...
RSchemaIteratorTemplate< true > RConstSchemaIterator
virtual std::uint32_t GetTypeChecksum() const
Return the current TClass reported checksum of this class. Only valid if kTraitTypeChecksum is set.
bool IsSimple() const
std::uint32_t GetTraits() const
std::size_t GetNRepetitions() const
std::uint32_t fOnDiskTypeChecksum
TClass checksum cached from the descriptor after a call to ConnectPageSource().
const std::string & GetTypeName() const
@ kTraitEmulatedField
This field is a user defined type that was missing dictionaries and was reconstructed from the on-dis...
@ kTraitTrivialType
Shorthand for types that are both trivially constructible and destructible.
@ kTraitTriviallyDestructible
The type is cleaned up just by freeing its memory. I.e. the destructor performs a no-op.
@ kTraitTriviallyConstructible
No constructor needs to be called, i.e.
@ kTraitMappable
A field of a fundamental type that can be directly mapped via RField<T>::Map(), i....
@ kTraitInvalidField
This field is an instance of RInvalidField and can be safely static_cast to it.
@ kTraitTypeChecksum
The TClass checksum is set and valid.
ROOT::ENTupleStructure fStructure
The role of this field in the data model structure.
void GenerateColumnsImpl(const ColumnRepresentation_t &representation, std::uint16_t representationIndex)
Helpers for generating columns.
RValue BindValue(std::shared_ptr< void > objPtr)
Creates a value from a memory location with an already constructed object.
void SetDescription(std::string_view description)
static void CallReadOn(RFieldBase &other, RNTupleLocalIndex localIndex, void *to)
ROOT::DescriptorId_t GetOnDiskId() const
std::uint32_t fOnDiskTypeVersion
C++ type version cached from the descriptor after a call to ConnectPageSource()
std::unique_ptr< RFieldBase > Clone(std::string_view newName) const
Copies the field and its subfields using a possibly new name and a new, unconnected set of columns.
std::string fName
The field name relative to its parent field.
void CommitCluster()
Flushes data from active columns to disk and calls CommitClusterImpl()
void ConnectPageSource(ROOT::Internal::RPageSource &pageSource)
Connects the field and its subfield tree to the given page source.
static void CallConstructValueOn(const RFieldBase &other, void *where)
Allow derived classes to call ConstructValue(void *) and GetDeleter() on other (sub)fields.
EState GetState() const
void GenerateColumnsImpl()
For writing, use the currently set column representative.
virtual ROOT::RExtraTypeInfoDescriptor GetExtraTypeInfo() const
virtual std::uint32_t GetTypeVersion() const
Indicates an evolution of the C++ type itself.
void * CreateObjectRawPtr() const
Factory method for the field's type. The caller owns the returned pointer.
void Read(ROOT::NTupleSize_t globalIndex, void *to)
Populate a single value with data from the field.
std::uint32_t GetOnDiskTypeChecksum() const
Return checksum stored in the field descriptor; only valid after a call to ConnectPageSource(),...
RFieldBase(const RFieldBase &)=delete
virtual bool HasExtraTypeInfo() const
bool fIsArtificial
A field that is not backed on disk but computed, e.g.
virtual std::size_t ReadBulkImpl(const RBulkSpec &bulkSpec)
General implementation of bulk read.
bool HasDefaultColumnRepresentative() const
Whether or not an explicit column representative was set.
The on-storage metadata of an RNTuple.
Addresses a column element or field item relative to a particular cluster, instead of a global NTuple...
ROOT::NTupleSize_t GetIndexInCluster() const
ROOT::DescriptorId_t GetClusterId() const
Used to loop over entries of collections in a single cluster.
Common user-tunable settings for storing RNTuples.
const_iterator begin() const
The class is used as a return type for operations that can fail; wraps a value of type T or an RError...
Definition RError.hxx:198
void CallCommitClusterOnField(RFieldBase &)
void CallConnectPageSourceOnField(RFieldBase &, ROOT::Internal::RPageSource &)
ROOT::RResult< std::unique_ptr< ROOT::RFieldBase > > CallFieldBaseCreate(const std::string &fieldName, const std::string &typeName, const ROOT::RCreateFieldOptions &options, const ROOT::RNTupleDescriptor *desc, ROOT::DescriptorId_t fieldId)
void CallFlushColumnsOnField(RFieldBase &)
bool IsMatchingFieldType(const std::string &actualTypeName)
Helper to check if a given type name is the one expected of Field<T>.
Definition RField.hxx:511
std::string GetRenormalizedTypeName(const std::string &metaNormalizedName)
Given a type name normalized by ROOT meta, renormalize it for RNTuple. E.g., insert std::prefix.
void CallConnectPageSinkOnField(RFieldBase &, ROOT::Internal::RPageSink &, ROOT::NTupleSize_t firstEntry=0)
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.
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...
static void SetPrimaryColumnRepresentation(RFieldBase &field, std::uint16_t newRepresentationIdx)
Input parameter to RFieldBase::ReadBulk() and RFieldBase::ReadBulkImpl().
static const std::size_t kAllSet
Possible return value of ReadBulk() and ReadBulkImpl(), which indicates that the full bulk range was ...
RNTupleLocalIndex fFirstIndex
Start of the bulk range.
void * fValues
The destination area, which has to be an array of valid objects of the correct type large enough to h...
std::size_t fCount
Size of the bulk range.
bool * fMaskAvail
A bool array of size fCount, indicating the valid values in fValues.
const bool * fMaskReq
A bool array of size fCount, indicating the required values in the requested range.
std::vector< unsigned char > * fAuxData
Reference to memory owned by the RBulkValues class.
Used in the return value of the Check() method.
std::string fFieldName
Qualified field name causing the error.
std::string fTypeName
Type name corresponding to the (sub)field.
std::string fErrMsg
Cause of the failure, e.g. unsupported type.
Position(FieldPtr_t fieldPtr, int idxInParent)
std::conditional_t< IsConstT, const RFieldBase *, RFieldBase * > FieldPtr_t
RSharedPtrDeleter(std::unique_ptr< RFieldBase::RDeleter > deleter)
std::unique_ptr< RFieldBase::RDeleter > fDeleter