Logo ROOT  
Reference Guide
RMiniFile.hxx
Go to the documentation of this file.
1/// \file ROOT/RMiniFile.hxx
2/// \ingroup NTuple ROOT7
3/// \author Jakob Blomer <jblomer@cern.ch>
4/// \date 2019-12-22
5/// \warning This is part of the ROOT 7 prototype! It will change without notice. It might trigger earthquakes. Feedback
6/// is welcome!
7
8/*************************************************************************
9 * Copyright (C) 1995-2019, Rene Brun and Fons Rademakers. *
10 * All rights reserved. *
11 * *
12 * For the licensing terms see $ROOTSYS/LICENSE. *
13 * For the list of contributors see $ROOTSYS/README/CREDITS. *
14 *************************************************************************/
15
16#ifndef ROOT7_RMiniFile
17#define ROOT7_RMiniFile
18
19#include <ROOT/RError.hxx>
21#include <ROOT/RStringView.hxx>
22
23#include <cstdint>
24#include <cstdio>
25#include <memory>
26#include <string>
27
28class TCollection;
29class TFile;
30class TFileMergeInfo;
31
32namespace ROOT {
33
34namespace Internal {
35class RRawFile;
36}
37
38namespace Experimental {
39
40namespace Internal {
41
42// clang-format off
43/**
44\class ROOT::Experimental::Internal::RFileNTupleAnchor
45\ingroup NTuple
46\brief Entry point for an RNTuple in a ROOT file
47
48The class points to the header and footer keys, which in turn have the references to the pages.
49Only the RNTuple key will be listed in the list of keys. Like TBaskets, the pages are "invisible" keys.
50Byte offset references in the RNTuple header and footer reference directly the data part of page records,
51skipping the TFile key part.
52
53In the list of keys, this object appears as "ROOT::Experimental::RNTuple".
54
55The RNTuple object is the user-facing representation of an RNTuple data set in a ROOT file.
56The RFileNTupleAnchor is the low-level entry point of an RNTuple in a ROOT file used by the page storage layer.
57
58The ROOT::Experimental::RNTuple object has the same on-disk layout as the RFileNTupleAnchor.
59It only adds methods and transient members. Reading and writing RNTuple anchors with TFile and the minifile writer
60is thus fully interoperable (same on-disk information).
61TODO(jblomer): Remove unneeded fChecksum, fVersion, fSize, fReserved once ROOT::Experimental::RNTuple moves out of
62the experimental namespace.
63*/
64// clang-format on
66 /// The ROOT streamer info checksum. Older RNTuple versions used class version 0 and a serialized checksum,
67 /// now we use class version 3 and "promote" the checksum as a class member
68 std::int32_t fChecksum = 0;
69 /// Allows for evolving the struct in future versions
70 std::uint32_t fVersion = 0;
71 /// Allows for skipping the struct
72 std::uint32_t fSize = sizeof(RFileNTupleAnchor);
73 /// The file offset of the header excluding the TKey part
74 std::uint64_t fSeekHeader = 0;
75 /// The size of the compressed ntuple header
76 std::uint32_t fNBytesHeader = 0;
77 /// The size of the uncompressed ntuple header
78 std::uint32_t fLenHeader = 0;
79 /// The file offset of the footer excluding the TKey part
80 std::uint64_t fSeekFooter = 0;
81 /// The size of the compressed ntuple footer
82 std::uint32_t fNBytesFooter = 0;
83 /// The size of the uncompressed ntuple footer
84 std::uint32_t fLenFooter = 0;
85 /// Currently unused, reserved for later use
86 std::uint64_t fReserved = 0;
87};
88
89/// Holds status information of an open ROOT file during writing
91
92// clang-format off
93/**
94\class ROOT::Experimental::Internal::RMiniFileReader
95\ingroup NTuple
96\brief Read RNTuple data blocks from a TFile container, provided by a RRawFile
97
98A RRawFile is used for the byte access. The class implements a minimal subset of TFile, enough to extract
99RNTuple data keys.
100*/
101// clang-format on
103private:
104 /// The raw file used to read byte ranges
106 /// Indicates whether the file is a TFile container or an RNTuple bare file
107 bool fIsBare = false;
108 /// Used when the file container turns out to be a bare file
110 /// Used when the file turns out to be a TFile container
112
113public:
114 RMiniFileReader() = default;
115 /// Uses the given raw file to read byte ranges
116 explicit RMiniFileReader(ROOT::Internal::RRawFile *rawFile);
117 /// Extracts header and footer location for the RNTuple identified by ntupleName
119 /// Reads a given byte range from the file into the provided memory buffer
120 void ReadBuffer(void *buffer, size_t nbytes, std::uint64_t offset);
121};
122
123
124// clang-format off
125/**
126\class ROOT::Experimental::Internal::RNTupleFileWriter
127\ingroup NTuple
128\brief Write RNTuple data blocks in a TFile or a bare file container
129
130The writer can create a new TFile container for an RNTuple or add an RNTuple to an existing TFile.
131Creating a single RNTuple in a new TFile container can be done with a C file stream without a TFile class.
132Updating an existing TFile requires a proper TFile object. Also, writing a remote file requires a proper TFile object.
133A stand-alone version of RNTuple can remove the TFile based writer.
134*/
135// clang-format on
137private:
138 struct RFileProper {
139 TFile *fFile = nullptr;
140 /// Low-level writing using a TFile
141 void Write(const void *buffer, size_t nbytes, std::int64_t offset);
142 /// Writes an RBlob opaque key with the provided buffer as data record and returns the offset of the record
143 std::uint64_t WriteKey(const void *buffer, size_t nbytes, size_t len);
144 operator bool() const { return fFile; }
145 };
146
147 struct RFileSimple {
148 /// For the simplest cases, a C file stream can be used for writing
149 FILE *fFile = nullptr;
150 /// Keeps track of the seek offset
151 std::uint64_t fFilePos = 0;
152 /// Keeps track of TFile control structures, which need to be updated on committing the data set
153 std::unique_ptr<ROOT::Experimental::Internal::RTFileControlBlock> fControlBlock;
154
155 RFileSimple() = default;
156 RFileSimple(const RFileSimple &other) = delete;
157 RFileSimple(RFileSimple &&other) = delete;
158 RFileSimple &operator =(const RFileSimple &other) = delete;
160 ~RFileSimple();
161
162 /// Writes bytes in the open stream, either at fFilePos or at the given offset
163 void Write(const void *buffer, size_t nbytes, std::int64_t offset = -1);
164 /// Writes a TKey including the data record, given by buffer, into fFile; returns the file offset to the payload.
165 /// The payload is already compressed
166 std::uint64_t WriteKey(const void *buffer, std::size_t nbytes, std::size_t len, std::int64_t offset = -1,
167 std::uint64_t directoryOffset = 100,
168 const std::string &className = "",
169 const std::string &objectName = "",
170 const std::string &title = "");
171 operator bool() const { return fFile; }
172 };
173
174 // TODO(jblomer): wrap in an std::variant with C++17
175 /// For updating existing files and for storing more than just an RNTuple in the file
177 /// For simple use cases, survives without libRIO dependency
179 /// A simple file can either be written as TFile container or as NTuple bare file
180 bool fIsBare = false;
181 /// The identifier of the RNTuple; A single writer object can only write a single RNTuple but multiple
182 /// writers can operate on the same file if (and only if) they use a proper TFile object for writing.
183 std::string fNTupleName;
184 /// The file name without parent directory; only required when writing with a C file stream
185 std::string fFileName;
186 /// Header and footer location of the ntuple, written on Commit()
188
190
191 /// For a TFile container written by a C file stream, write the header and TFile object
192 void WriteTFileSkeleton(int defaultCompression);
193 /// The only key that will be visible in file->ls()
194 void WriteTFileNTupleKey();
195 /// Write the TList with the RNTuple key
196 void WriteTFileKeysList();
197 /// Write the compressed streamer info record with the description of the RNTuple class
199 /// Last record in the file
200 void WriteTFileFreeList();
201 /// For a bare file, which is necessarily written by a C file stream, write file header
202 void WriteBareFileSkeleton(int defaultCompression);
203
204public:
205 /// Create or truncate the local file given by path with the new empty RNTuple identified by ntupleName.
206 /// Uses a C stream for writing
207 static RNTupleFileWriter *Recreate(std::string_view ntupleName, std::string_view path, int defaultCompression,
208 ENTupleContainerFormat containerFormat);
209 /// Create or truncate the local or remote file given by path with the new empty RNTuple identified by ntupleName.
210 /// Creates a new TFile object for writing and hands over ownership of the object to the user.
212 std::unique_ptr<TFile> &file);
213 /// Add a new RNTuple identified by ntupleName to the existing TFile.
214 static RNTupleFileWriter *Append(std::string_view ntupleName, TFile &file);
215
216 RNTupleFileWriter(const RNTupleFileWriter &other) = delete;
221
222 /// Writes the compressed header and registeres its location; lenHeader is the size of the uncompressed header.
223 std::uint64_t WriteNTupleHeader(const void *data, size_t nbytes, size_t lenHeader);
224 /// Writes the compressed footer and registeres its location; lenFooter is the size of the uncompressed footer.
225 std::uint64_t WriteNTupleFooter(const void *data, size_t nbytes, size_t lenFooter);
226 /// Writes a new record as an RBlob key into the file
227 std::uint64_t WriteBlob(const void *data, size_t nbytes, size_t len);
228 /// Writes the RNTuple key to the file so that the header and footer keys can be found
229 void Commit();
230};
231
232} // namespace Internal
233} // namespace Experimental
234} // namespace ROOT
235
236#endif
Option_t Option_t TPoint TPoint const char GetTextMagnitude GetFillStyle GetLineColor GetLineWidth GetMarkerStyle GetTextAlign GetTextColor GetTextSize void data
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 Atom_t Time_t UChar_t len
char name[80]
Definition: TGX11.cxx:110
Read RNTuple data blocks from a TFile container, provided by a RRawFile.
Definition: RMiniFile.hxx:102
RResult< RFileNTupleAnchor > GetNTupleProper(std::string_view ntupleName)
Used when the file turns out to be a TFile container.
Definition: RMiniFile.cxx:995
bool fIsBare
Indicates whether the file is a TFile container or an RNTuple bare file.
Definition: RMiniFile.hxx:107
RResult< RFileNTupleAnchor > GetNTuple(std::string_view ntupleName)
Extracts header and footer location for the RNTuple identified by ntupleName.
Definition: RMiniFile.cxx:984
ROOT::Internal::RRawFile * fRawFile
The raw file used to read byte ranges.
Definition: RMiniFile.hxx:105
void ReadBuffer(void *buffer, size_t nbytes, std::uint64_t offset)
Reads a given byte range from the file into the provided memory buffer.
Definition: RMiniFile.cxx:1080
RResult< RFileNTupleAnchor > GetNTupleBare(std::string_view ntupleName)
Used when the file container turns out to be a bare file.
Definition: RMiniFile.cxx:1058
Write RNTuple data blocks in a TFile or a bare file container.
Definition: RMiniFile.hxx:136
std::uint64_t WriteBlob(const void *data, size_t nbytes, size_t len)
Writes a new record as an RBlob key into the file.
Definition: RMiniFile.cxx:1292
std::string fNTupleName
The identifier of the RNTuple; A single writer object can only write a single RNTuple but multiple wr...
Definition: RMiniFile.hxx:183
std::string fFileName
The file name without parent directory; only required when writing with a C file stream.
Definition: RMiniFile.hxx:185
std::uint64_t WriteNTupleFooter(const void *data, size_t nbytes, size_t lenFooter)
Writes the compressed footer and registeres its location; lenFooter is the size of the uncompressed f...
Definition: RMiniFile.cxx:1320
void WriteTFileKeysList()
Write the TList with the RNTuple key.
Definition: RMiniFile.cxx:1376
void Commit()
Writes the RNTuple key to the file so that the header and footer keys can be found.
Definition: RMiniFile.cxx:1259
RFileProper fFileProper
For updating existing files and for storing more than just an RNTuple in the file.
Definition: RMiniFile.hxx:176
RFileSimple fFileSimple
For simple use cases, survives without libRIO dependency.
Definition: RMiniFile.hxx:178
RNTupleFileWriter(const RNTupleFileWriter &other)=delete
static RNTupleFileWriter * Append(std::string_view ntupleName, TFile &file)
Add a new RNTuple identified by ntupleName to the existing TFile.
Definition: RMiniFile.cxx:1250
void WriteTFileNTupleKey()
The only key that will be visible in file->ls()
Definition: RMiniFile.cxx:1420
void WriteTFileFreeList()
Last record in the file.
Definition: RMiniFile.cxx:1403
static RNTupleFileWriter * Recreate(std::string_view ntupleName, std::string_view path, int defaultCompression, ENTupleContainerFormat containerFormat)
Create or truncate the local file given by path with the new empty RNTuple identified by ntupleName.
Definition: RMiniFile.cxx:1203
RNTupleFileWriter & operator=(const RNTupleFileWriter &other)=delete
bool fIsBare
A simple file can either be written as TFile container or as NTuple bare file.
Definition: RMiniFile.hxx:180
void WriteTFileSkeleton(int defaultCompression)
For a TFile container written by a C file stream, write the header and TFile object.
Definition: RMiniFile.cxx:1432
void WriteBareFileSkeleton(int defaultCompression)
For a bare file, which is necessarily written by a C file stream, write file header.
Definition: RMiniFile.cxx:1331
void WriteTFileStreamerInfo()
Write the compressed streamer info record with the description of the RNTuple class.
Definition: RMiniFile.cxx:1345
std::uint64_t WriteNTupleHeader(const void *data, size_t nbytes, size_t lenHeader)
Writes the compressed header and registeres its location; lenHeader is the size of the uncompressed h...
Definition: RMiniFile.cxx:1309
RFileNTupleAnchor fNTupleAnchor
Header and footer location of the ntuple, written on Commit()
Definition: RMiniFile.hxx:187
RNTupleFileWriter(RNTupleFileWriter &&other)=delete
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:195
The RRawFile provides read-only access to local and remote files.
Definition: RRawFile.hxx:43
Collection abstract base class.
Definition: TCollection.h:65
A ROOT file is a suite of consecutive data records (TKey instances) with a well defined format.
Definition: TFile.h:54
basic_string_view< char > string_view
This file contains a specialised ROOT message handler to test for diagnostic in unit tests.
Definition: file.py:1
Entry point for an RNTuple in a ROOT file.
Definition: RMiniFile.hxx:65
std::uint32_t fNBytesFooter
The size of the compressed ntuple footer.
Definition: RMiniFile.hxx:82
std::int32_t fChecksum
The ROOT streamer info checksum.
Definition: RMiniFile.hxx:68
std::uint64_t fSeekFooter
The file offset of the footer excluding the TKey part.
Definition: RMiniFile.hxx:80
std::uint32_t fSize
Allows for skipping the struct.
Definition: RMiniFile.hxx:72
std::uint32_t fNBytesHeader
The size of the compressed ntuple header.
Definition: RMiniFile.hxx:76
std::uint32_t fLenFooter
The size of the uncompressed ntuple footer.
Definition: RMiniFile.hxx:84
std::uint64_t fSeekHeader
The file offset of the header excluding the TKey part.
Definition: RMiniFile.hxx:74
std::uint32_t fLenHeader
The size of the uncompressed ntuple header.
Definition: RMiniFile.hxx:78
std::uint64_t fReserved
Currently unused, reserved for later use.
Definition: RMiniFile.hxx:86
std::uint32_t fVersion
Allows for evolving the struct in future versions.
Definition: RMiniFile.hxx:70
void Write(const void *buffer, size_t nbytes, std::int64_t offset)
Low-level writing using a TFile.
Definition: RMiniFile.cxx:1146
std::uint64_t WriteKey(const void *buffer, size_t nbytes, size_t len)
Writes an RBlob opaque key with the provided buffer as data record and returns the offset of the reco...
Definition: RMiniFile.cxx:1156
std::unique_ptr< ROOT::Experimental::Internal::RTFileControlBlock > fControlBlock
Keeps track of TFile control structures, which need to be updated on committing the data set.
Definition: RMiniFile.hxx:153
FILE * fFile
For the simplest cases, a C file stream can be used for writing.
Definition: RMiniFile.hxx:149
RFileSimple & operator=(const RFileSimple &other)=delete
void Write(const void *buffer, size_t nbytes, std::int64_t offset=-1)
Writes bytes in the open stream, either at fFilePos or at the given offset.
Definition: RMiniFile.cxx:1097
std::uint64_t fFilePos
Keeps track of the seek offset.
Definition: RMiniFile.hxx:151
std::uint64_t WriteKey(const void *buffer, std::size_t nbytes, std::size_t len, std::int64_t offset=-1, std::uint64_t directoryOffset=100, const std::string &className="", const std::string &objectName="", const std::string &title="")
Writes a TKey including the data record, given by buffer, into fFile; returns the file offset to the ...
Definition: RMiniFile.cxx:1117
If a TFile container is written by a C stream (simple file), on dataset commit, the file header and t...
Definition: RMiniFile.cxx:967