The RNTupleModel encapulates the schema of an RNTuple.
The RNTupleModel comprises a collection of hierarchically organized fields. From a model, "entries" can be extracted or created. For convenience, the RNTupleModel provides a default entry unless it is created as a "bare model". Models have a unique model identifier that facilitates checking whether entries are compatible with it (i.e.: have been extracted from that model).
A model is subject to state transitions during its lifetime: it starts in a building state, in which fields can be added and modified. Once the schema is finalized, the model gets frozen. Only frozen models can create entries. From frozen, models move into an expired state. In this state, the model is only partially usable: it can be cloned and queried, but it can't be unfrozen anymore and no new entries can be created. This state is used for models that were used for writing and are no longer connected to a page sink.
Definition at line 141 of file RNTupleModel.hxx.
Classes | |
class | RUpdater |
A model is usually immutable after passing it to an RNTupleWriter . More... | |
Public Types | |
using | FieldMappingFunc_t = std::function<std::string(const std::string &)> |
User-provided function that describes the mapping of existing source fields to projected fields in terms of fully qualified field names. | |
Public Member Functions | |
RNTupleModel (const RNTupleModel &)=delete | |
~RNTupleModel ()=default | |
void | AddField (std::unique_ptr< ROOT::RFieldBase > field) |
Adds a field whose type is not known at compile time. | |
RResult< void > | AddProjectedField (std::unique_ptr< ROOT::RFieldBase > field, FieldMappingFunc_t mapping) |
Adds a top-level field based on existing fields. | |
std::unique_ptr< RNTupleModel > | Clone () const |
std::unique_ptr< REntry > | CreateBareEntry () const |
Creates a "bare entry", i.e. | |
ROOT::RFieldBase::RBulk | CreateBulk (std::string_view fieldName) const |
Calls the given field's CreateBulk() method. Throws an RException if no field with the given name exists. | |
std::unique_ptr< REntry > | CreateEntry () const |
Creates a new entry with default values for each field. | |
std::unique_ptr< Experimental::Detail::RRawPtrWriteEntry > | CreateRawPtrWriteEntry () const |
std::size_t | EstimateWriteMemoryUsage (const ROOT::RNTupleWriteOptions &options=ROOT::RNTupleWriteOptions()) const |
Estimate the memory usage for this model during writing. | |
void | Expire () |
Transitions an RNTupleModel from the frozen state to the expired state, invalidating all previously created entries, disabling creating new entries from it and disabling further state transitions. | |
void | Freeze () |
Transitions an RNTupleModel from the building state to the frozen state, disabling adding additional fields and enabling creating entries from it. | |
const ROOT::RFieldBase & | GetConstField (std::string_view fieldName) const |
const ROOT::RFieldZero & | GetConstFieldZero () const |
Retrieves the field zero of this model, i.e. the root of the field hierarchy. | |
REntry & | GetDefaultEntry () |
Retrieves the default entry of this model. | |
const REntry & | GetDefaultEntry () const |
const std::string & | GetDescription () const |
const std::unordered_set< std::string > & | GetFieldNames () const |
Get the names of the fields currently present in the model, including projected fields. | |
std::uint64_t | GetModelId () const |
ROOT::RFieldBase & | GetMutableField (std::string_view fieldName) |
Retrieves the field with fully-qualified name fieldName . | |
ROOT::RFieldZero & | GetMutableFieldZero () |
Retrieves the field zero of this model, i.e. | |
const std::unordered_set< std::string > & | GetRegisteredSubfieldNames () const |
Get the (qualified) names of subfields that have been registered (via RegisterSubfield()) to be included in entries from this model. | |
std::uint64_t | GetSchemaId () const |
ROOT::RFieldToken | GetToken (std::string_view fieldName) const |
Creates a token to be used in REntry methods to address a field present in the entry. | |
bool | IsBare () const |
bool | IsExpired () const |
bool | IsFrozen () const |
template<typename T > | |
std::shared_ptr< T > | MakeField (std::string_view name, std::string_view description="") |
Creates a new field given a name or {name, description} pair and a corresponding, default-constructed value that is managed by a shared pointer. | |
RNTupleModel & | operator= (const RNTupleModel &)=delete |
void | RegisterSubfield (std::string_view qualifiedFieldName) |
Register a subfield so it can be accessed directly from entries belonging to the model. | |
void | SetDescription (std::string_view description) |
void | Unfreeze () |
Transitions an RNTupleModel from the frozen state back to the building state, invalidating all previously created entries, re-enabling adding additional fields and disabling creating entries from it. | |
Static Public Member Functions | |
static std::unique_ptr< RNTupleModel > | Create () |
static std::unique_ptr< RNTupleModel > | Create (std::unique_ptr< ROOT::RFieldZero > fieldZero) |
static std::unique_ptr< RNTupleModel > | CreateBare () |
Creates a "bare model", i.e. an RNTupleModel with no default entry. | |
static std::unique_ptr< RNTupleModel > | CreateBare (std::unique_ptr< ROOT::RFieldZero > fieldZero) |
Creates a "bare model", i.e. an RNTupleModel with no default entry, with the given field zero. | |
Private Types | |
enum class | EState { kBuilding , kFrozen , kExpired } |
The states a model can be in. More... | |
Private Member Functions | |
RNTupleModel (std::unique_ptr< ROOT::RFieldZero > fieldZero) | |
void | AddSubfield (std::string_view fieldName, ROOT::REntry &entry, bool initializeValue=true) const |
Add a subfield to the provided entry. | |
void | EnsureNotBare () const |
Throws an RException if fDefaultEntry is nullptr. | |
void | EnsureNotFrozen () const |
Throws an RException if fFrozen is true. | |
void | EnsureValidFieldName (std::string_view fieldName) |
Checks that user-provided field names are valid in the context of this RNTupleModel. | |
ROOT::RFieldBase * | FindField (std::string_view fieldName) const |
The field name can be a top-level field or a nested field. Returns nullptr if the field is not in the model. | |
Private Attributes | |
std::unique_ptr< ROOT::REntry > | fDefaultEntry |
Contains field values corresponding to the created top-level fields, as well as registered subfields. | |
std::string | fDescription |
Free text set by the user. | |
std::unordered_set< std::string > | fFieldNames |
Keeps track of which field names are taken, including projected field names. | |
std::unique_ptr< ROOT::RFieldZero > | fFieldZero |
Hierarchy of fields consisting of simple types and collections (sub trees) | |
std::uint64_t | fModelId = 0 |
Every model has a unique ID to distinguish it from other models. | |
EState | fModelState = EState::kBuilding |
Changed by Freeze() / Unfreeze() and by the RUpdater. | |
std::unique_ptr< Internal::RProjectedFields > | fProjectedFields |
The set of projected top-level fields. | |
std::unordered_set< std::string > | fRegisteredSubfields |
Keeps track of which subfields have been registered to be included in entries belonging to this model. | |
std::uint64_t | fSchemaId = 0 |
Models have a separate schema ID to remember that the clone of a frozen model still has the same schema. | |
Friends | |
ROOT::RFieldZero & | Internal::GetFieldZeroOfModel (RNTupleModel &) |
Internal::RProjectedFields & | Internal::GetProjectedFieldsOfModel (RNTupleModel &) |
#include <ROOT/RNTupleModel.hxx>
using ROOT::RNTupleModel::FieldMappingFunc_t = std::function<std::string(const std::string &)> |
User-provided function that describes the mapping of existing source fields to projected fields in terms of fully qualified field names.
The mapping function is called with the qualified field names of the provided field and the subfields. It should return the qualified field names used as a mapping source. See AddProjectedFields() for more details.
Definition at line 150 of file RNTupleModel.hxx.
|
strongprivate |
The states a model can be in.
Possible transitions are between kBuilding and kFrozen and from kFrozen to kExpired. See RNTupleModel for the state transition graph.
Enumerator | |
---|---|
kBuilding | |
kFrozen | |
kExpired |
Definition at line 158 of file RNTupleModel.hxx.
|
private |
Definition at line 265 of file RNTupleModel.cxx.
|
delete |
|
default |
void ROOT::RNTupleModel::AddField | ( | std::unique_ptr< ROOT::RFieldBase > | field | ) |
Adds a field whose type is not known at compile time.
No shared pointer is returned in this case: pointers should be retrieved or bound via REntry.
Throws an RException if the field is null.
Definition at line 345 of file RNTupleModel.cxx.
ROOT::RResult< void > ROOT::RNTupleModel::AddProjectedField | ( | std::unique_ptr< ROOT::RFieldBase > | field, |
FieldMappingFunc_t | mapping ) |
Adds a top-level field based on existing fields.
The mapping function takes one argument, which is a string containing the name of the projected field. The return value of the mapping function should be the name of the (existing) field onto which the projection is made. Example
Adding projections for collection fields is also possible, as long as they follow the same schema structure. For example, a projection of a collection of structs onto a collection of scalars is possible, but a projection of a collection of a collection of scalars onto a collection of scalars is not.
In the case of projections for nested fields, the mapping function must provide a mapping for every nesting level. Example
Creating projections for fields containing std::variant
or fixed-size arrays is unsupported.
Definition at line 404 of file RNTupleModel.cxx.
|
private |
Add a subfield to the provided entry.
If initializeValue
is false, a nullptr will be bound to the entry value (used in bare models).
Definition at line 358 of file RNTupleModel.cxx.
std::unique_ptr< ROOT::RNTupleModel > ROOT::RNTupleModel::Clone | ( | ) | const |
Definition at line 294 of file RNTupleModel.cxx.
|
static |
Definition at line 282 of file RNTupleModel.cxx.
|
static |
Definition at line 287 of file RNTupleModel.cxx.
|
static |
Creates a "bare model", i.e. an RNTupleModel with no default entry.
Definition at line 270 of file RNTupleModel.cxx.
|
static |
Creates a "bare model", i.e. an RNTupleModel with no default entry, with the given field zero.
Definition at line 275 of file RNTupleModel.cxx.
std::unique_ptr< ROOT::REntry > ROOT::RNTupleModel::CreateBareEntry | ( | ) | const |
Creates a "bare entry", i.e.
a entry with all null values. The user needs to explicitly call BindValue() or BindRawPtr() to set memory addresses before serializing / deserializing the entry.
Definition at line 491 of file RNTupleModel.cxx.
ROOT::RFieldBase::RBulk ROOT::RNTupleModel::CreateBulk | ( | std::string_view | fieldName | ) | const |
Calls the given field's CreateBulk() method. Throws an RException if no field with the given name exists.
Definition at line 538 of file RNTupleModel.cxx.
std::unique_ptr< ROOT::REntry > ROOT::RNTupleModel::CreateEntry | ( | ) | const |
Creates a new entry with default values for each field.
Definition at line 473 of file RNTupleModel.cxx.
std::unique_ptr< ROOT::Experimental::Detail::RRawPtrWriteEntry > ROOT::RNTupleModel::CreateRawPtrWriteEntry | ( | ) | const |
Definition at line 509 of file RNTupleModel.cxx.
|
private |
Throws an RException if fDefaultEntry is nullptr.
Definition at line 259 of file RNTupleModel.cxx.
|
private |
Throws an RException if fFrozen is true.
Definition at line 253 of file RNTupleModel.cxx.
|
private |
Checks that user-provided field names are valid in the context of this RNTupleModel.
Throws an RException for invalid names, empty names (which is reserved for the zero field) and duplicate field names.
Definition at line 239 of file RNTupleModel.cxx.
std::size_t ROOT::RNTupleModel::EstimateWriteMemoryUsage | ( | const ROOT::RNTupleWriteOptions & | options = ROOT::RNTupleWriteOptions() | ) | const |
Estimate the memory usage for this model during writing.
This will return an estimate in bytes for the internal page and compression buffers. The value should be understood per sequential RNTupleWriter or per RNTupleFillContext created for an RNTupleParallelWriter constructed with this model.
Definition at line 596 of file RNTupleModel.cxx.
void ROOT::RNTupleModel::Expire | ( | ) |
Transitions an RNTupleModel from the frozen state to the expired state, invalidating all previously created entries, disabling creating new entries from it and disabling further state transitions.
Expiring a model that is already expired is a no-op. Throws an RException if the model is in the building state. See RNTupleModel for a more detailed explanation on the state transitions.
Definition at line 552 of file RNTupleModel.cxx.
|
private |
The field name can be a top-level field or a nested field. Returns nullptr if the field is not in the model.
Definition at line 324 of file RNTupleModel.cxx.
void ROOT::RNTupleModel::Freeze | ( | ) |
Transitions an RNTupleModel from the building state to the frozen state, disabling adding additional fields and enabling creating entries from it.
Freezing an already-frozen model is a no-op. Throws an RException if the model is in the expired state. See RNTupleModel for more detailed explanation on the state transitions.
Definition at line 582 of file RNTupleModel.cxx.
const ROOT::RFieldBase & ROOT::RNTupleModel::GetConstField | ( | std::string_view | fieldName | ) | const |
Definition at line 450 of file RNTupleModel.cxx.
|
inline |
Retrieves the field zero of this model, i.e. the root of the field hierarchy.
Definition at line 364 of file RNTupleModel.hxx.
ROOT::REntry & ROOT::RNTupleModel::GetDefaultEntry | ( | ) |
Retrieves the default entry of this model.
Throws an RException if this is a bare model (i.e. if it was created with CreateBare()).
Definition at line 459 of file RNTupleModel.cxx.
const ROOT::REntry & ROOT::RNTupleModel::GetDefaultEntry | ( | ) | const |
Definition at line 465 of file RNTupleModel.cxx.
|
inline |
Definition at line 373 of file RNTupleModel.hxx.
|
inline |
Get the names of the fields currently present in the model, including projected fields.
Registered subfields are not included, use GetRegisteredSubfieldnames() for this.
Definition at line 378 of file RNTupleModel.hxx.
|
inline |
Definition at line 340 of file RNTupleModel.hxx.
ROOT::RFieldBase & ROOT::RNTupleModel::GetMutableField | ( | std::string_view | fieldName | ) |
Retrieves the field with fully-qualified name fieldName
.
Dot-separated names are used to walk down the field hierarchy: e.g. "parent.child"
should be used to retrieve a field with name "child"
whose parent is the top-level field with name "parent"
. Throws an RException if no field is found with the given name.
Definition at line 439 of file RNTupleModel.cxx.
ROOT::RFieldZero & ROOT::RNTupleModel::GetMutableFieldZero | ( | ) |
Retrieves the field zero of this model, i.e.
the root of the field hierarchy. This may be used to make adjustments on the field hierarchy before the model is frozen.
Definition at line 432 of file RNTupleModel.cxx.
|
inline |
Get the (qualified) names of subfields that have been registered (via RegisterSubfield()) to be included in entries from this model.
Definition at line 381 of file RNTupleModel.hxx.
|
inline |
Definition at line 341 of file RNTupleModel.hxx.
ROOT::RFieldToken ROOT::RNTupleModel::GetToken | ( | std::string_view | fieldName | ) | const |
Creates a token to be used in REntry methods to address a field present in the entry.
Definition at line 526 of file RNTupleModel.cxx.
|
inline |
Definition at line 339 of file RNTupleModel.hxx.
|
inline |
Definition at line 335 of file RNTupleModel.hxx.
|
inline |
Definition at line 337 of file RNTupleModel.hxx.
|
inline |
Creates a new field given a name
or {name, description}
pair and a corresponding, default-constructed value that is managed by a shared pointer.
Example: create some fields and fill an RNTuple
Example: create a field with a description
Definition at line 253 of file RNTupleModel.hxx.
|
delete |
void ROOT::RNTupleModel::RegisterSubfield | ( | std::string_view | qualifiedFieldName | ) |
Register a subfield so it can be accessed directly from entries belonging to the model.
Because registering a subfield does not fundamentally change the model, previously created entries will not be invalidated, nor modified in any way; a registered subfield is merely an accessor added to the default entry (if present) and any entries created afterwards. Note that previously created entries won't have this subfield added to them.
Using models with registered subfields for writing is not allowed. Attempting to do so will result in an exception.
Throws an RException if the provided subfield could not be found in the model.
Definition at line 368 of file RNTupleModel.cxx.
void ROOT::RNTupleModel::SetDescription | ( | std::string_view | description | ) |
Definition at line 590 of file RNTupleModel.cxx.
void ROOT::RNTupleModel::Unfreeze | ( | ) |
Transitions an RNTupleModel from the frozen state back to the building state, invalidating all previously created entries, re-enabling adding additional fields and disabling creating entries from it.
Unfreezing a model that is already in the building state is a no-op. Throws an RException if the model is in the expired state. See RNTupleModel for a more detailed explanation on the state transitions.
Definition at line 565 of file RNTupleModel.cxx.
|
friend |
|
private |
Contains field values corresponding to the created top-level fields, as well as registered subfields.
Definition at line 167 of file RNTupleModel.hxx.
|
private |
Free text set by the user.
Definition at line 171 of file RNTupleModel.hxx.
|
private |
Keeps track of which field names are taken, including projected field names.
Definition at line 169 of file RNTupleModel.hxx.
|
private |
Hierarchy of fields consisting of simple types and collections (sub trees)
Definition at line 165 of file RNTupleModel.hxx.
|
private |
Every model has a unique ID to distinguish it from other models.
Entries are linked to models via the ID. Cloned models get a new model ID. Expired models are cloned into frozen models.
Definition at line 178 of file RNTupleModel.hxx.
|
private |
Changed by Freeze() / Unfreeze() and by the RUpdater.
Definition at line 182 of file RNTupleModel.hxx.
|
private |
The set of projected top-level fields.
Definition at line 173 of file RNTupleModel.hxx.
|
private |
Keeps track of which subfields have been registered to be included in entries belonging to this model.
Definition at line 175 of file RNTupleModel.hxx.
|
private |
Models have a separate schema ID to remember that the clone of a frozen model still has the same schema.
Definition at line 180 of file RNTupleModel.hxx.