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::Experimental::Detail::RRawPtrWriteEntry; // to call Append()
89 friend struct ROOT::Internal::RFieldCallbackInjector; // used for unit tests
90 friend struct ROOT::Internal::RFieldRepresentationModifier; // used for unit tests
96 Internal::CallFieldBaseCreate(const std::string &fieldName, const std::string &typeName,
97 const ROOT::RCreateFieldOptions &options, const ROOT::RNTupleDescriptor *desc,
99
100 using ReadCallback_t = std::function<void(void *)>;
101
102protected:
103 /// A functor to release the memory acquired by CreateValue() (memory and constructor).
104 /// This implementation works for types with a trivial destructor. More complex fields implement a derived deleter.
105 /// The deleter is operational without the field object and thus can be used to destruct/release a value after
106 /// the field has been destructed.
107 class RDeleter {
108 public:
109 virtual ~RDeleter() = default;
110 virtual void operator()(void *objPtr, bool dtorOnly)
111 {
112 if (!dtorOnly)
113 operator delete(objPtr);
114 }
115 };
116
117 /// A deleter for templated RFieldBase descendents where the value type is known.
118 template <typename T>
119 class RTypedDeleter : public RDeleter {
120 public:
121 void operator()(void *objPtr, bool dtorOnly) final
122 {
123 std::destroy_at(static_cast<T *>(objPtr));
125 }
126 };
127
128 // We cannot directly use RFieldBase::RDeleter as a shared pointer deleter due to splicing. We use this
129 // wrapper class to store a polymorphic pointer to the actual deleter.
131 std::unique_ptr<RFieldBase::RDeleter> fDeleter;
132 void operator()(void *objPtr) { fDeleter->operator()(objPtr, false /* dtorOnly*/); }
133 explicit RSharedPtrDeleter(std::unique_ptr<RFieldBase::RDeleter> deleter) : fDeleter(std::move(deleter)) {}
134 };
135
136public:
137 static constexpr std::uint32_t kInvalidTypeVersion = -1U;
138 enum {
139 /// No constructor needs to be called, i.e. any bit pattern in the allocated memory represents a valid type
140 /// A trivially constructible field has a no-op ConstructValue() implementation
142 /// The type is cleaned up just by freeing its memory. I.e. the destructor performs a no-op.
144 /// A field of a fundamental type that can be directly mapped via RField<T>::Map(), i.e. maps as-is to a single
145 /// column
147 /// The TClass checksum is set and valid
149 /// This field is an instance of RInvalidField and can be safely `static_cast` to it
151 /// This field is a user defined type that was missing dictionaries and was reconstructed from the on-disk
152 /// information
154
155 /// Shorthand for types that are both trivially constructible and destructible
157 };
158
159 using ColumnRepresentation_t = std::vector<ROOT::ENTupleColumnType>;
160
161 /// During its lifetime, a field undergoes the following possible state transitions:
162 ///
163 /// [*] --> Unconnected --> ConnectedToSink ----
164 /// | | |
165 /// | --> ConnectedToSource ---> [*]
166 /// | |
167 /// -------------------------------
168 enum class EState {
172 };
173
174 // clang-format off
175 /**
176 \class ROOT::RFieldBase::RColumnRepresentations
177 \ingroup NTuple
178 \brief The list of column representations a field can have.
179
180 Some fields have multiple possible column representations, e.g. with or without split encoding.
181 All column representations supported for writing also need to be supported for reading. In addition,
182 fields can support extra column representations for reading only, e.g. a 64bit integer reading from a
183 32bit column.
184 The defined column representations must be supported by corresponding column packing/unpacking implementations,
185 i.e. for the example above, the unpacking of 32bit ints to 64bit pages must be implemented in RColumnElement.hxx
186 */
187 // clang-format on
189 public:
190 /// A list of column representations
191 using Selection_t = std::vector<ColumnRepresentation_t>;
192
195
196 /// The first column list from `fSerializationTypes` is the default for writing.
200
201 private:
203 /// The union of the serialization types and the deserialization extra types passed during construction.
204 /// Duplicates the serialization types list but the benefit is that GetDeserializationTypes() does not need to
205 /// compile the list.
207 }; // class RColumnRepresentations
208
209 class RValue;
210 class RBulkValues;
211
212private:
213 /// The field name relative to its parent field
214 std::string fName;
215 /// The C++ type captured by this field
216 std::string fType;
217 /// The role of this field in the data model structure
219 /// For fixed sized arrays, the array length
220 std::size_t fNRepetitions;
221 /// A field qualifies as simple if it is mappable (which implies it has a single principal column),
222 /// and it is not an artificial field and has no post-read callback
224 /// A field that is not backed on disk but computed, e.g. a default-constructed missing field or
225 /// a field whose data is created by I/O customization rules. Subfields of artificial fields are
226 /// artificial, too.
227 bool fIsArtificial = false;
228 /// When the columns are connected to a page source or page sink, the field represents a field id in the
229 /// corresponding RNTuple descriptor. This on-disk ID is set in RPageSink::Create() for writing and by
230 /// RFieldDescriptor::CreateField() when recreating a field / model from the stored descriptor.
232 /// Free text set by the user
233 std::string fDescription;
234 /// Changed by ConnectTo[Sink,Source], reset by Clone()
236
238 {
239 for (const auto &func : fReadCallbacks)
240 func(target);
241 }
242
243 /// Translate an entry index to a column element index of the principal column and vice versa. These functions
244 /// take into account the role and number of repetitions on each level of the field hierarchy as follows:
245 /// - Top level fields: element index == entry index
246 /// - Record fields propagate their principal column index to the principal columns of direct descendant fields
247 /// - Collection and variant fields set the principal column index of their children to 0
248 ///
249 /// The column element index also depends on the number of repetitions of each field in the hierarchy, e.g., given a
250 /// field with type `std::array<std::array<float, 4>, 2>`, this function returns 8 for the innermost field.
252
253 /// Flushes data from active columns
254 void FlushColumns();
255 /// Flushes data from active columns to disk and calls CommitClusterImpl()
256 void CommitCluster();
257 /// Fields and their columns live in the void until connected to a physical page storage. Only once connected, data
258 /// 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.
259 /// \param firstEntry The global index of the first entry with on-disk data for the connected field
261 /// Connects the field and its subfield tree to the given page source. Once connected, data can be read.
262 /// Only unconnected fields may be connected, i.e. the method is not idempotent. The field ID has to be set prior to
263 /// calling this function. For subfields, a field ID may or may not be set. If the field ID is unset, it will be
264 /// determined using the page source descriptor, based on the parent field ID and the subfield name.
266
268 {
269 fIsSimple = false;
270 fIsArtificial = true;
271 for (auto &field : fSubfields) {
272 field->SetArtificial();
273 }
274 }
275
276protected:
277 struct RBulkSpec;
278
279 /// Bits used in CompareOnDisk()
280 enum {
281 /// The in-memory field and the on-disk field differ in the field version
283 /// The in-memory field and the on-disk field differ in the type version
285 /// The in-memory field and the on-disk field differ in their structural roles
287 /// The in-memory field and the on-disk field have different type names
289 /// The in-memory field and the on-disk field have different repetition counts
290 kDiffNRepetitions = 0x10
291 };
292
293 /// Collections and classes own subfields
294 std::vector<std::unique_ptr<RFieldBase>> fSubfields;
295 /// Subfields point to their mother field
297 /// All fields that have columns have a distinct main column. E.g., for simple fields (`float`, `int`, ...), the
298 /// principal column corresponds to the field type. For collection fields except fixed-sized arrays,
299 /// the main column is the offset field. Class fields have no column of their own.
300 /// When reading, points to any column of the column team of the active representation. Usually, this is just
301 /// the first column.
302 /// When writing, points to the first column index of the currently active (not suppressed) column representation.
304 /// Some fields have a second column in its column representation. In this case, `fAuxiliaryColumn` points into
305 /// `fAvailableColumns` to the column that immediately follows the column `fPrincipalColumn` points to.
307 /// The columns are connected either to a sink or to a source (not to both); they are owned by the field.
308 /// Contains all columns of all representations in order of representation and column index.
309 std::vector<std::unique_ptr<ROOT::Internal::RColumn>> fAvailableColumns;
310 /// Properties of the type that allow for optimizations of collections of that type
311 std::uint32_t fTraits = 0;
312 /// A typedef or using name that was used when creating the field
313 std::string fTypeAlias;
314 /// List of functions to be called after reading a value
315 std::vector<ReadCallback_t> fReadCallbacks;
316 /// C++ type version cached from the descriptor after a call to ConnectPageSource()
318 /// TClass checksum cached from the descriptor after a call to ConnectPageSource(). Only set
319 /// for classes with dictionaries.
320 std::uint32_t fOnDiskTypeChecksum = 0;
321 /// Pointers into the static vector returned by RColumnRepresentations::GetSerializationTypes() when
322 /// SetColumnRepresentatives() is called. Otherwise (if empty) GetColumnRepresentatives() returns a vector
323 /// with a single element, the default representation. Always empty for artificial fields.
324 std::vector<std::reference_wrapper<const ColumnRepresentation_t>> fColumnRepresentatives;
325
326 /// Factory method for the field's type. The caller owns the returned pointer
327 void *CreateObjectRawPtr() const;
328
329 /// Helpers for generating columns. We use the fact that most fields have the same C++/memory types
330 /// for all their column representations.
331 /// Where possible, we call the helpers not from the header to reduce compilation time.
332 template <std::uint32_t ColumnIndexT, typename HeadT, typename... TailTs>
334 {
336 auto &column = fAvailableColumns.emplace_back(
337 ROOT::Internal::RColumn::Create<HeadT>(representation[ColumnIndexT], ColumnIndexT, representationIndex));
338
339 // Initially, the first two columns become the active column representation
341 fPrincipalColumn = column.get();
342 } else if (representationIndex == 0 && !fAuxiliaryColumn) {
343 fAuxiliaryColumn = column.get();
344 } else {
345 // We currently have no fields with more than 2 columns in its column representation
347 }
348
349 if constexpr (sizeof...(TailTs))
351 }
352
353 /// For writing, use the currently set column representative
354 template <typename... ColumnCppTs>
356 {
357 if (fColumnRepresentatives.empty()) {
358 fAvailableColumns.reserve(sizeof...(ColumnCppTs));
359 GenerateColumnsImpl<0, ColumnCppTs...>(GetColumnRepresentations().GetSerializationDefault(), 0);
360 } else {
361 const auto N = fColumnRepresentatives.size();
362 fAvailableColumns.reserve(N * sizeof...(ColumnCppTs));
363 for (unsigned i = 0; i < N; ++i) {
365 }
366 }
367 }
368
369 /// For reading, use the on-disk column list
370 template <typename... ColumnCppTs>
372 {
373 std::uint16_t representationIndex = 0;
374 do {
376 if (onDiskTypes.empty())
377 break;
380 if (representationIndex > 0) {
381 for (std::size_t i = 0; i < sizeof...(ColumnCppTs); ++i) {
382 fAvailableColumns[i]->MergeTeams(
383 *fAvailableColumns[representationIndex * sizeof...(ColumnCppTs) + i].get());
384 }
385 }
387 } while (true);
388 }
389
390 /// Implementations in derived classes should return a static RColumnRepresentations object. The default
391 /// implementation does not attach any columns to the field.
392 virtual const RColumnRepresentations &GetColumnRepresentations() const;
393 /// Implementations in derived classes should create the backing columns corresponding to the field type for
394 /// writing. The default implementation does not attach any columns to the field.
395 virtual void GenerateColumns() {}
396 /// Implementations in derived classes should create the backing columns corresponding to the field type for reading.
397 /// The default implementation does not attach any columns to the field. The method should check, using the page
398 /// source and `fOnDiskId`, if the column types match and throw if they don't.
399 virtual void GenerateColumns(const ROOT::RNTupleDescriptor & /*desc*/) {}
400 /// Returns the on-disk column types found in the provided descriptor for `fOnDiskId` and the given
401 /// representation index. If there are no columns for the given representation index, return an empty
402 /// ColumnRepresentation_t list. Otherwise, the returned reference points into the static array returned by
403 /// GetColumnRepresentations().
404 /// Throws an exception if the types on disk don't match any of the deserialization types from
405 /// GetColumnRepresentations().
408 /// When connecting a field to a page sink, the field's default column representation is subject
409 /// to adjustment according to the write options. E.g., if compression is turned off, encoded columns
410 /// are changed to their unencoded counterparts.
412
413 /// Called by Clone(), which additionally copies the on-disk ID
414 virtual std::unique_ptr<RFieldBase> CloneImpl(std::string_view newName) const = 0;
415
416 /// Constructs value in a given location of size at least GetValueSize(). Called by the base class' CreateValue().
417 virtual void ConstructValue(void *where) const = 0;
418 virtual std::unique_ptr<RDeleter> GetDeleter() const { return std::make_unique<RDeleter>(); }
419 /// Allow derived classes to call ConstructValue(void *) and GetDeleter() on other (sub)fields.
420 static void CallConstructValueOn(const RFieldBase &other, void *where) { other.ConstructValue(where); }
421 static std::unique_ptr<RDeleter> GetDeleterOf(const RFieldBase &other) { return other.GetDeleter(); }
422
423 /// Allow parents to mark their childs as artificial fields (used in class and record fields)
424 static void CallSetArtificialOn(RFieldBase &other) { other.SetArtificial(); }
425 /// Allow class fields to adjust the type alias of their members
426 static void SetTypeAliasOf(RFieldBase &other, const std::string &alias) { other.fTypeAlias = alias; }
427
428 /// Operations on values of complex types, e.g. ones that involve multiple columns or for which no direct
429 /// column type exists.
430 virtual std::size_t AppendImpl(const void *from);
431 virtual void ReadGlobalImpl(ROOT::NTupleSize_t globalIndex, void *to);
432 virtual void ReadInClusterImpl(RNTupleLocalIndex localIndex, void *to);
433
434 /// Write the given value into columns. The value object has to be of the same type as the field.
435 /// Returns the number of uncompressed bytes written.
436 std::size_t Append(const void *from);
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(globalIndex, to);
445
446 if (!fIsArtificial) {
449 else
451 }
452 if (R__unlikely(!fReadCallbacks.empty()))
454 }
455
456 /// Populate a single value with data from the field. The memory location pointed to by to needs to be of the
457 /// fitting type. The fast path is conditioned by the field qualifying as simple, i.e. maps as-is
458 /// to a single column and has no read callback.
460 {
461 if (fIsSimple)
462 return (void)fPrincipalColumn->Read(localIndex, to);
463
464 if (!fIsArtificial) {
467 else
469 }
470 if (R__unlikely(!fReadCallbacks.empty()))
472 }
473
474 /// General implementation of bulk read. Loop over the required range and read values that are required
475 /// and not already present. Derived classes may implement more optimized versions of this method.
476 /// See ReadBulk() for the return value.
477 virtual std::size_t ReadBulkImpl(const RBulkSpec &bulkSpec);
478
479 /// Returns the number of newly available values, that is the number of bools in `bulkSpec.fMaskAvail` that
480 /// flipped from false to true. As a special return value, `kAllSet` can be used if all values are read
481 /// independent from the masks.
482 std::size_t ReadBulk(const RBulkSpec &bulkSpec);
483
484 /// Allow derived classes to call Append() and Read() on other (sub)fields.
485 static std::size_t CallAppendOn(RFieldBase &other, const void *from) { return other.Append(from); }
488 static void *CallCreateObjectRawPtrOn(RFieldBase &other) { return other.CreateObjectRawPtr(); }
489
490 /// Fields may need direct access to the principal column of their subfields, e.g. in RRVecField::ReadBulk()
491 static ROOT::Internal::RColumn *GetPrincipalColumnOf(const RFieldBase &other) { return other.fPrincipalColumn; }
492
493 /// Set a user-defined function to be called after reading a value, giving a chance to inspect and/or modify the
494 /// value object.
495 /// Returns an index that can be used to remove the callback.
496 size_t AddReadCallback(ReadCallback_t func);
497 void RemoveReadCallback(size_t idx);
498
499 // Perform housekeeping tasks for global to cluster-local index translation
500 virtual void CommitClusterImpl() {}
501 // The field can indicate that it needs to register extra type information in the on-disk schema.
502 // In this case, a callback from the page sink to the field will be registered on connect, so that the
503 // extra type information can be collected when the dataset gets committed.
504 virtual bool HasExtraTypeInfo() const { return false; }
505 // The page sink's callback when the data set gets committed will call this method to get the field's extra
506 // type information. This has to happen at the end of writing because the type information may change depending
507 // on the data that's written, e.g. for polymorphic types in the streamer field.
509
510 /// Add a new subfield to the list of nested fields
511 void Attach(std::unique_ptr<RFieldBase> child);
512
513 /// Called by ConnectPageSource() before connecting; derived classes may override this as appropriate, e.g.
514 /// for the application of I/O rules. In the process, the field at hand or its subfields may be marked as
515 /// "artifical", i.e. introduced by schema evolution and not backed by on-disk information.
517
518 /// For non-artificial fields, check compatibility of the in-memory field and the on-disk field. In the process,
519 /// the field at hand may change its on-disk ID or perform other tasks related to automatic schema evolution.
520 /// If the on-disk field is incompatible with the in-memory field at hand, an exception is thrown.
521 virtual void ReconcileOnDiskField(const RNTupleDescriptor &desc);
522
523 /// Returns a combination of kDiff... flags, indicating peroperties that are different between the field at hand
524 /// and the given on-disk field
525 std::uint32_t CompareOnDiskField(const RFieldDescriptor &fieldDesc, std::uint32_t ignoreBits) const;
526 /// Compares the field to the provieded on-disk field descriptor. Throws an exception if the fields don't match.
527 /// Optionally, a set of bits can be provided that should be ignored in the comparison.
528 void EnsureMatchingOnDiskField(const RFieldDescriptor &fieldDesc, std::uint32_t ignoreBits = 0) const;
529 /// Many fields accept a range of type prefixes for schema evolution,
530 /// e.g. std::unique_ptr< and std::optional< for nullable fields
531 void EnsureMatchingTypePrefix(const RFieldDescriptor &fieldDesc, const std::vector<std::string> &prefixes) const;
532
533 /// Factory method to resurrect a field from the stored on-disk type information. This overload takes an already
534 /// normalized type name and type alias.
535 /// `desc` and `fieldId` must be passed if `options.fEmulateUnknownTypes` is true, otherwise they can be left blank.
537 Create(const std::string &fieldName, const std::string &typeName, const ROOT::RCreateFieldOptions &options,
539
540public:
541 template <bool IsConstT>
542 class RSchemaIteratorTemplate;
545
546 // This is used in CreateObject() and is specialized for void
547 template <typename T>
549 using deleter = std::default_delete<T>;
550 };
551
552 /// Used in the return value of the Check() method
554 std::string fFieldName; ///< Qualified field name causing the error
555 std::string fTypeName; ///< Type name corresponding to the (sub)field
556 std::string fErrMsg; ///< Cause of the failure, e.g. unsupported type
557 };
558
559 /// The constructor creates the underlying column objects and connects them to either a sink or a source.
560 /// If `isSimple` is `true`, the trait `kTraitMappable` is automatically set on construction. However, the
561 /// field might be demoted to non-simple if a post-read callback is set.
562 RFieldBase(std::string_view name, std::string_view type, ROOT::ENTupleStructure structure, bool isSimple,
563 std::size_t nRepetitions = 0);
564 RFieldBase(const RFieldBase &) = delete;
565 RFieldBase(RFieldBase &&) = default;
566 RFieldBase &operator=(const RFieldBase &) = delete;
568 virtual ~RFieldBase() = default;
569
570 /// Copies the field and its subfields using a possibly new name and a new, unconnected set of columns
571 std::unique_ptr<RFieldBase> Clone(std::string_view newName) const;
572
573 /// Factory method to create a field from a certain type given as string.
574 /// Note that the provided type name must be a valid C++ type name. Template arguments of templated types
575 /// must be type names or integers (e.g., no expressions).
577 Create(const std::string &fieldName, const std::string &typeName);
578
579 /// Checks if the given type is supported by RNTuple. In case of success, the result vector is empty.
580 /// Otherwise there is an error record for each failing subfield (subtype).
581 static std::vector<RCheckResult> Check(const std::string &fieldName, const std::string &typeName);
582
583 /// Generates an object of the field type and allocates new initialized memory according to the type.
584 /// Implemented at the end of this header because the implementation is using RField<T>::TypeName()
585 /// The returned object can be released with `delete`, i.e. it is valid to call:
586 /// ~~~{.cpp}
587 /// auto ptr = field->CreateObject();
588 /// delete ptr.release();
589 /// ~~~
590 ///
591 /// Note that CreateObject<void>() is supported. The returned `unique_ptr` has a custom deleter that reports an error
592 /// if it is called. The intended use of the returned `unique_ptr<void>` is to call `release()`. In this way, the
593 /// transfer of pointer ownership is explicit.
594 template <typename T>
595 std::unique_ptr<T, typename RCreateObjectDeleter<T>::deleter> CreateObject() const;
596 /// Generates an object of the field's type, wraps it in a shared pointer and returns it as an RValue connected to
597 /// the field.
599 /// Creates a new, initially empty bulk.
600 /// RBulkValues::ReadBulk() will construct the array of values. The memory of the value array is managed by the
601 /// RBulkValues class.
603 /// Creates a value from a memory location with an already constructed object
604 RValue BindValue(std::shared_ptr<void> objPtr);
605 /// Creates the list of direct child values given an existing value for this field. E.g. a single value for the
606 /// correct `std::variant` or all the elements of a collection. The default implementation assumes no subvalues
607 /// and returns an empty vector.
608 virtual std::vector<RValue> SplitValue(const RValue &value) const;
609 /// The number of bytes taken by a value of the appropriate type
610 virtual size_t GetValueSize() const = 0;
611 /// As a rule of thumb, the alignment is equal to the size of the type. There are, however, various exceptions
612 /// to this rule depending on OS and CPU architecture. So enforce the alignment to be explicitly spelled out.
613 virtual size_t GetAlignment() const = 0;
614 std::uint32_t GetTraits() const { return fTraits; }
615 bool HasReadCallbacks() const { return !fReadCallbacks.empty(); }
616
617 const std::string &GetFieldName() const { return fName; }
618 /// Returns the field name and parent field names separated by dots (`grandparent.parent.child`)
619 std::string GetQualifiedFieldName() const;
620 const std::string &GetTypeName() const { return fType; }
621 const std::string &GetTypeAlias() const { return fTypeAlias; }
623 std::size_t GetNRepetitions() const { return fNRepetitions; }
624 const RFieldBase *GetParent() const { return fParent; }
625 std::vector<RFieldBase *> GetMutableSubfields();
626 std::vector<const RFieldBase *> GetConstSubfields() const;
627 bool IsSimple() const { return fIsSimple; }
628 bool IsArtificial() const { return fIsArtificial; }
629 /// Get the field's description
630 const std::string &GetDescription() const { return fDescription; }
631 void SetDescription(std::string_view description);
632 EState GetState() const { return fState; }
633
636
637 /// Returns the `fColumnRepresentative` pointee or, if unset (always the case for artificial fields), the field's
638 /// default representative
640 /// Fixes a column representative. This can only be done _before_ connecting the field to a page sink.
641 /// Otherwise, or if the provided representation is not in the list of GetColumnRepresentations(),
642 /// an exception is thrown
644 /// Whether or not an explicit column representative was set
646
647 /// Indicates an evolution of the mapping scheme from C++ type to columns
648 virtual std::uint32_t GetFieldVersion() const { return 0; }
649 /// Indicates an evolution of the C++ type itself
650 virtual std::uint32_t GetTypeVersion() const { return 0; }
651 /// Return the current TClass reported checksum of this class. Only valid if `kTraitTypeChecksum` is set.
652 virtual std::uint32_t GetTypeChecksum() const { return 0; }
653 /// Return the C++ type version stored in the field descriptor; only valid after a call to ConnectPageSource()
654 std::uint32_t GetOnDiskTypeVersion() const { return fOnDiskTypeVersion; }
655 /// Return checksum stored in the field descriptor; only valid after a call to ConnectPageSource(),
656 /// if the field stored a type checksum
657 std::uint32_t GetOnDiskTypeChecksum() const { return fOnDiskTypeChecksum; }
658
665
667}; // class RFieldBase
668
669/// Iterates over the subtree of fields in depth-first search order
670template <bool IsConstT>
672private:
673 struct Position {
674 using FieldPtr_t = std::conditional_t<IsConstT, const RFieldBase *, RFieldBase *>;
675 Position() : fFieldPtr(nullptr), fIdxInParent(-1) {}
679 };
680 /// The stack of nodes visited when walking down the tree of fields
681 std::vector<Position> fStack;
682
683public:
685 using iterator_category = std::forward_iterator_tag;
686 using difference_type = std::ptrdiff_t;
687 using value_type = std::conditional_t<IsConstT, const RFieldBase, RFieldBase>;
688 using pointer = std::conditional_t<IsConstT, const RFieldBase *, RFieldBase *>;
689 using reference = std::conditional_t<IsConstT, const RFieldBase &, RFieldBase &>;
690
694 /// Given that the iterator points to a valid field which is not the end iterator, go to the next field
695 /// in depth-first search order
696 void Advance()
697 {
698 auto itr = fStack.rbegin();
699 if (!itr->fFieldPtr->fSubfields.empty()) {
700 fStack.emplace_back(Position(itr->fFieldPtr->fSubfields[0].get(), 0));
701 return;
702 }
703
704 unsigned int nextIdxInParent = ++(itr->fIdxInParent);
705 while (nextIdxInParent >= itr->fFieldPtr->fParent->fSubfields.size()) {
706 if (fStack.size() == 1) {
707 itr->fFieldPtr = itr->fFieldPtr->fParent;
708 itr->fIdxInParent = -1;
709 return;
710 }
711 fStack.pop_back();
712 itr = fStack.rbegin();
713 nextIdxInParent = ++(itr->fIdxInParent);
714 }
715 itr->fFieldPtr = itr->fFieldPtr->fParent->fSubfields[nextIdxInParent].get();
716 }
717
718 iterator operator++(int) /* postfix */
719 {
720 auto r = *this;
721 Advance();
722 return r;
723 }
724 iterator &operator++() /* prefix */
725 {
726 Advance();
727 return *this;
728 }
729 reference operator*() const { return *fStack.back().fFieldPtr; }
730 pointer operator->() const { return fStack.back().fFieldPtr; }
731 bool operator==(const iterator &rh) const { return fStack.back().fFieldPtr == rh.fStack.back().fFieldPtr; }
732 bool operator!=(const iterator &rh) const { return fStack.back().fFieldPtr != rh.fStack.back().fFieldPtr; }
733};
734
735/// Points to an object with RNTuple I/O support and keeps a pointer to the corresponding field.
736/// Fields can create RValue objects through RFieldBase::CreateValue(), RFieldBase::BindValue()) or
737/// RFieldBase::SplitValue().
739 friend class RFieldBase;
740 friend class ROOT::REntry;
741
742private:
743 RFieldBase *fField = nullptr; ///< The field that created the RValue
744 /// Set by Bind() or by RFieldBase::CreateValue(), RFieldBase::SplitValue() or RFieldBase::BindValue()
745 std::shared_ptr<void> fObjPtr;
746 mutable std::atomic<const std::type_info *> fTypeInfo = nullptr;
747
748 RValue(RFieldBase *field, std::shared_ptr<void> objPtr) : fField(field), fObjPtr(objPtr) {}
749
750public:
753 {
754 fField = other.fField;
755 fObjPtr = other.fObjPtr;
756 // We could copy over the cached type info, or just start with a fresh state...
757 fTypeInfo = nullptr;
758 return *this;
759 }
762 {
763 fField = other.fField;
764 fObjPtr = other.fObjPtr;
765 // We could copy over the cached type info, or just start with a fresh state...
766 fTypeInfo = nullptr;
767 return *this;
768 }
769 ~RValue() = default;
770
771private:
772 template <typename T>
774 {
775 if constexpr (!std::is_void_v<T>) {
776 const std::type_info &ti = typeid(T);
777 // Fast path: if we had a matching type before, try comparing the type_info's. This may still fail in case the
778 // type has a suppressed template argument that may change the typeid.
779 auto *cachedTypeInfo = fTypeInfo.load();
780 if (cachedTypeInfo != nullptr && *cachedTypeInfo == ti) {
781 return;
782 }
785 fTypeInfo.store(&ti);
786 return;
787 }
788 throw RException(R__FAIL("type mismatch for field \"" + fField->GetFieldName() + "\": expected " +
789 fField->GetTypeName() + ", got " + renormalizedTypeName));
790 }
791 }
792
793 std::size_t Append() { return fField->Append(fObjPtr.get()); }
794
795public:
798
799 void Bind(std::shared_ptr<void> objPtr) { fObjPtr = objPtr; }
800 void BindRawPtr(void *rawPtr);
801 /// Replace the current object pointer by a pointer to a new object constructed by the field
802 void EmplaceNew() { fObjPtr = fField->CreateValue().GetPtr<void>(); }
803
804 template <typename T>
805 std::shared_ptr<T> GetPtr() const
806 {
808 return std::static_pointer_cast<T>(fObjPtr);
809 }
810
811 template <typename T>
812 const T &GetRef() const
813 {
815 return *static_cast<T *>(fObjPtr.get());
816 }
817
818 const RFieldBase &GetField() const { return *fField; }
819};
820
821/// Input parameter to RFieldBase::ReadBulk() and RFieldBase::ReadBulkImpl().
822// See the RBulkValues class documentation for more information.
824 /// Possible return value of ReadBulk() and ReadBulkImpl(), which indicates that the full bulk range was read
825 /// independently of the provided masks.
826 static const std::size_t kAllSet = std::size_t(-1);
827
828 RNTupleLocalIndex fFirstIndex; ///< Start of the bulk range
829 std::size_t fCount = 0; ///< Size of the bulk range
830 /// A bool array of size fCount, indicating the required values in the requested range
831 const bool *fMaskReq = nullptr;
832 bool *fMaskAvail = nullptr; ///< A bool array of size `fCount`, indicating the valid values in fValues
833 /// The destination area, which has to be an array of valid objects of the correct type large enough to hold the bulk
834 /// range.
835 void *fValues = nullptr;
836 /// Reference to memory owned by the RBulkValues class. The field implementing BulkReadImpl() may use `fAuxData` as
837 /// memory that stays persistent between calls.
838 std::vector<unsigned char> *fAuxData = nullptr;
839};
840
841// clang-format off
842/**
843\class ROOT::RFieldBase::RBulkValues
844\ingroup NTuple
845\brief Points to an array of objects with RNTuple I/O support, used for bulk reading.
846
847Similar to RValue, but manages an array of consecutive values. Bulks have to come from the same cluster.
848Bulk I/O works with two bit masks: the mask of all the available entries in the current bulk and the mask
849of the required entries in a bulk read. The idea is that a single bulk may serve multiple read operations
850on the same range, where in each read operation a different subset of values is required.
851The memory of the value array is managed by the RBulkValues class.
852*/
853// clang-format on
855private:
856 friend class RFieldBase;
857
858 RFieldBase *fField = nullptr; ///< The field that created the array of values
859 std::unique_ptr<RFieldBase::RDeleter> fDeleter; /// Cached deleter of fField
860 void *fValues = nullptr; ///< Pointer to the start of the array
861 std::size_t fValueSize = 0; ///< Cached copy of RFieldBase::GetValueSize()
862 std::size_t fCapacity = 0; ///< The size of the array memory block in number of values
863 std::size_t fSize = 0; ///< The number of available values in the array (provided their mask is set)
864 bool fIsAdopted = false; ///< True if the user provides the memory buffer for fValues
865 std::unique_ptr<bool[]> fMaskAvail; ///< Masks invalid values in the array
866 std::size_t fNValidValues = 0; ///< The sum of non-zero elements in the fMask
867 RNTupleLocalIndex fFirstIndex; ///< Index of the first value of the array
868 /// Reading arrays of complex values may require additional memory, for instance for the elements of
869 /// arrays of vectors. A pointer to the `fAuxData` array is passed to the field's BulkRead method.
870 /// The RBulkValues class does not modify the array in-between calls to the field's BulkRead method.
871 std::vector<unsigned char> fAuxData;
872
873 void ReleaseValues();
874 /// Sets a new range for the bulk. If there is enough capacity, the `fValues` array will be reused.
875 /// Otherwise a new array is allocated. After reset, fMaskAvail is false for all values.
876 void Reset(RNTupleLocalIndex firstIndex, std::size_t size);
877 void CountValidValues();
878
880 {
881 if (firstIndex.GetClusterId() != fFirstIndex.GetClusterId())
882 return false;
883 return (firstIndex.GetIndexInCluster() >= fFirstIndex.GetIndexInCluster()) &&
884 ((firstIndex.GetIndexInCluster() + size) <= (fFirstIndex.GetIndexInCluster() + fSize));
885 }
886
887 void *GetValuePtrAt(std::size_t idx) const { return reinterpret_cast<unsigned char *>(fValues) + idx * fValueSize; }
888
893
894public:
895 ~RBulkValues();
896 RBulkValues(const RBulkValues &) = delete;
900
901 // Sets `fValues` and `fSize`/`fCapacity` to the given values. The capacity is specified in number of values.
902 // Once a buffer is adopted, an attempt to read more values then available throws an exception.
903 void AdoptBuffer(void *buf, std::size_t capacity);
904
905 /// Reads `size` values from the associated field, starting from `firstIndex`. Note that the index is given
906 /// relative to a certain cluster. The return value points to the array of read objects.
907 /// The `maskReq` parameter is a bool array of at least `size` elements. Only objects for which the mask is
908 /// true are guaranteed to be read in the returned value array. A `nullptr` means to read all elements.
909 void *ReadBulk(RNTupleLocalIndex firstIndex, const bool *maskReq, std::size_t size)
910 {
913
914 // We may read a subrange of the currently available range
915 auto offset = firstIndex.GetIndexInCluster() - fFirstIndex.GetIndexInCluster();
916
917 if (fNValidValues == fSize)
918 return GetValuePtrAt(offset);
919
921 bulkSpec.fFirstIndex = firstIndex;
922 bulkSpec.fCount = size;
923 bulkSpec.fMaskReq = maskReq;
924 bulkSpec.fMaskAvail = &fMaskAvail[offset];
925 bulkSpec.fValues = GetValuePtrAt(offset);
926 bulkSpec.fAuxData = &fAuxData;
927 auto nRead = fField->ReadBulk(bulkSpec);
928 if (nRead == RBulkSpec::kAllSet) {
929 if ((offset == 0) && (size == fSize)) {
931 } else {
933 }
934 } else {
936 }
937 return GetValuePtrAt(offset);
938 }
939
940 /// Overload to read all elements in the given cluster range.
941 void *ReadBulk(ROOT::RNTupleLocalRange range) { return ReadBulk(*range.begin(), nullptr, range.size()); }
942};
943
944namespace Internal {
945// At some point, RFieldBase::OnClusterCommit() may allow for a user-defined callback to change the
946// column representation. For now, we inject this for testing and internal use only.
949 {
950 R__ASSERT(newRepresentationIdx < field.fColumnRepresentatives.size());
951 const auto N = field.fColumnRepresentatives[0].get().size();
952 R__ASSERT(N >= 1 && N <= 2);
953 R__ASSERT(field.fPrincipalColumn);
954 field.fPrincipalColumn = field.fAvailableColumns[newRepresentationIdx * N].get();
955 if (field.fAuxiliaryColumn) {
956 R__ASSERT(N == 2);
957 field.fAuxiliaryColumn = field.fAvailableColumns[newRepresentationIdx * N + 1].get();
958 }
959 }
960};
961} // namespace Internal
962} // namespace ROOT
963
964#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 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.
static void SetTypeAliasOf(RFieldBase &other, const std::string &alias)
Allow class fields to adjust the type alias of their members.
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
virtual void ReconcileOnDiskField(const RNTupleDescriptor &desc)
For non-artificial fields, check compatibility of the in-memory field and the on-disk field.
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:531
RFieldBase & operator=(const RFieldBase &)=delete
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.
static void CallSetArtificialOn(RFieldBase &other)
Allow parents to mark their childs as artificial fields (used in class and record fields)
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.
@ kDiffStructure
The in-memory field and the on-disk field differ in their structural roles.
@ kDiffTypeName
The in-memory field and the on-disk field have different type names.
@ kDiffTypeVersion
The in-memory field and the on-disk field differ in the type version.
@ kDiffFieldVersion
The in-memory field and the on-disk field differ in the field version.
@ kDiffNRepetitions
The in-memory field and the on-disk field have different repetition counts.
EState fState
Changed by ConnectTo[Sink,Source], reset by Clone()
static void * CallCreateObjectRawPtrOn(RFieldBase &other)
bool IsArtificial() const
void EnsureMatchingTypePrefix(const RFieldDescriptor &fieldDesc, const std::vector< std::string > &prefixes) const
Many fields accept a range of type prefixes for schema evolution, e.g.
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::uint32_t CompareOnDiskField(const RFieldDescriptor &fieldDesc, std::uint32_t ignoreBits) const
Returns a combination of kDiff... flags, indicating peroperties that are different between the field ...
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
void EnsureMatchingOnDiskField(const RFieldDescriptor &fieldDesc, std::uint32_t ignoreBits=0) const
Compares the field to the provieded on-disk field descriptor.
@ 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.
Metadata stored for every field of an RNTuple.
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:523
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)
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