Logo ROOT   6.12/07
Reference Guide
TFile.hxx
Go to the documentation of this file.
1 /// \file ROOT/TFile.h
2 /// \ingroup Base ROOT7
3 /// \author Axel Naumann <axel@cern.ch>
4 /// \date 2015-07-31
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-2016, 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_TFile
17 #define ROOT7_TFile
18 
19 #include "ROOT/TDirectory.hxx"
20 
21 #include "TClass.h"
22 
23 #include "RStringView.h"
24 #include <memory>
25 #include <typeinfo>
26 
27 namespace ROOT {
28 namespace Experimental {
29 
30 class TFilePtr;
31 
32 namespace Internal {
33 class TFileStorageInterface;
34 class TFileSharedPtrCtor;
35 } // namespace Internal
36 
37 /** \class ROOT::Experimental::TFile
38  A ROOT file.
39 
40  A ROOT file is an object store: it can serialize any
41  object for which ROOT I/O is available (generally: an object which has a
42  dictionary), and it stores the object's data under a key name.
43 
44  */
45 class TFile: public TDirectory {
46 private:
47  std::unique_ptr<Internal::TFileStorageInterface> fStorage; ///< Storage backend.
48 
49  TFile(std::unique_ptr<Internal::TFileStorageInterface> &&storage);
50 
51  /// Serialize the object at address, using the object's TClass.
52  // FIXME: what about `cl` "pointing" to a base class?
53  void WriteMemoryWithType(std::string_view name, const void *address, TClass *cl);
54 
55  friend Internal::TFileSharedPtrCtor;
56 
57 public:
58  /// Options for TFile construction.
59  struct Options_t {
60  /// Default constructor needed for member inits.
61  Options_t() {}
62 
63  /// Whether the file should be opened asynchronously, if available.
64  bool fAsynchronousOpen = false;
65 
66  /// Timeout for asynchronous opening.
67  int fAsyncTimeout = 0;
68 
69  /// Whether the file should be cached before reading. Only available for
70  /// "remote" file protocols. If the download fails, the file will be opened
71  /// remotely.
72  bool fCachedRead = false;
73 
74  /// Where to cache the file. If empty, defaults to TFilePtr::GetCacheDir().
75  std::string fCacheDir;
76  };
77 
78  ///\name Generator functions
79  ///\{
80 
81  /// Open a file with `name` for reading.
82  ///
83  /// \note: Synchronizes multi-threaded accesses through locks.
84  static TFilePtr Open(std::string_view name, const Options_t &opts = Options_t());
85 
86  /// Open an existing file with `name` for reading and writing. If a file with
87  /// that name does not exist, an invalid TFilePtr will be returned.
88  ///
89  /// \note: Synchronizes multi-threaded accesses through locks.
90  static TFilePtr OpenForUpdate(std::string_view name, const Options_t &opts = Options_t());
91 
92  /// Open a file with `name` for reading and writing. Fail (return an invalid
93  /// `TFilePtr`) if a file with this name already exists.
94  ///
95  /// \note: Synchronizes multi-threaded accesses through locks.
96  static TFilePtr Create(std::string_view name, const Options_t &opts = Options_t());
97 
98  /// Open a file with `name` for reading and writing. If a file with this name
99  /// already exists, delete it and create a new one. Else simply create a new file.
100  ///
101  /// \note: Synchronizes multi-threaded accesses through locks.
102  static TFilePtr Recreate(std::string_view name, const Options_t &opts = Options_t());
103 
104  ///\}
105 
106  /// Set the new directory used for cached reads, returns the old directory.
107  ///
108  /// \note: Synchronizes multi-threaded accesses through locks.
109  static std::string SetCacheDir(std::string_view path);
110 
111  /// Get the directory used for cached reads.
112  static std::string GetCacheDir();
113 
114  /// Must not call Write() of all attached objects:
115  /// some might not be needed to be written or writing might be aborted due to
116  /// an exception; require explicit Write().
117  ~TFile();
118 
119  /// Save all objects associated with this directory (including file header) to
120  /// the storage medium.
121  void Flush();
122 
123  /// Flush() and make the file non-writable: close it.
124  void Close();
125 
126  /// Read the object for a key. `T` must be the object's type.
127  /// This will re-read the object for each call, returning a new copy; whether
128  /// the `TDirectory` is managing an object attached to this key or not.
129  /// \returns a `unique_ptr` to the object.
130  /// \throws TDirectoryUnknownKey if no object is stored under this name.
131  /// \throws TDirectoryTypeMismatch if the object stored under this name is of
132  /// a type different from `T`.
133  template <class T>
134  std::unique_ptr<T> Read(std::string_view name)
135  {
136  // FIXME: need separate collections for a TDirectory's key/value and registered objects. Here, we want to emit a
137  // read and must look through the key/values without attaching an object to the TDirectory.
138  // FIXME: do not register read object in TDirectory
139  // FIXME: implement actual read
140  // FIXME: for now, copy out of whatever the TDirectory manages.
141  return std::make_unique<T>(*Get<T>(name));
142  }
143 
144  /// Write an object that is not lifetime managed by this TFileImplBase.
145  template <class T>
146  void Write(std::string_view name, const T &obj)
147  {
148  WriteMemoryWithType(name, &obj, TClass::GetClass(typeid(T)));
149  }
150 
151  /// Write an object that is not lifetime managed by this TFileImplBase.
152  template <class T>
153  void Write(std::string_view name, const T *obj)
154  {
155  WriteMemoryWithType(name, obj, TClass::GetClass(typeid(T)));
156  }
157 
158  /// Write an object that is already lifetime managed by this TFileImplBase.
160  {
161  auto dep = Find(name);
162  WriteMemoryWithType(name, dep.GetPointer().get(), dep.GetType());
163  }
164 
165  /// Hand over lifetime management of an object to this TFileImplBase, and
166  /// write it.
167  template <class T>
168  void Write(std::string_view name, std::shared_ptr<T> &&obj)
169  {
170  Add(name, obj);
171  // FIXME: use an iterator from the insertion to write instead of a second name lookup.
172  Write(name);
173  }
174 };
175 
176 /**
177  \class TFilePtr
178  \brief Points to an object that stores or reads objects in ROOT's binary
179  format.
180 
181  FIXME: implement async open; likely using std::future, possibly removing the
182  Option_t element.
183 
184  */
185 
186 class TFilePtr {
187 private:
188  std::shared_ptr<TFile> fFile;
189 
190  /// Constructed by Open etc.
191  TFilePtr(std::shared_ptr<TFile> &&);
192 
193  friend class TFile;
194 
195 public:
196  /// Dereference the file pointer, giving access to the TFileImplBase object.
197  TFile *operator->() { return fFile.get(); }
198 
199  /// Dereference the file pointer, giving access to the TFileImplBase object.
200  /// const overload.
201  const TFile *operator->() const { return fFile.get(); }
202 
203  /// Check the validity of the file pointer.
204  operator bool() const { return fFile.get(); }
205 };
206 
207 } // namespace Experimental
208 } // namespace ROOT
209 #endif
Options_t()
Default constructor needed for member inits.
Definition: TFile.hxx:61
void Write(std::string_view name, std::shared_ptr< T > &&obj)
Hand over lifetime management of an object to this TFileImplBase, and write it.
Definition: TFile.hxx:168
std::unique_ptr< Internal::TFileStorageInterface > fStorage
Storage backend.
Definition: TFile.hxx:47
basic_string_view< char > string_view
Definition: RStringView.h:35
Namespace for new ROOT classes and functions.
Definition: StringConv.hxx:21
Options for TFile construction.
Definition: TFile.hxx:59
double T(double x)
Definition: ChebyshevPol.h:34
std::unique_ptr< T > Read(std::string_view name)
Read the object for a key.
Definition: TFile.hxx:134
TFile * operator->()
Dereference the file pointer, giving access to the TFileImplBase object.
Definition: TFile.hxx:197
void Write(std::string_view name, const T *obj)
Write an object that is not lifetime managed by this TFileImplBase.
Definition: TFile.hxx:153
const TFile * operator->() const
Dereference the file pointer, giving access to the TFileImplBase object.
Definition: TFile.hxx:201
std::string fCacheDir
Where to cache the file. If empty, defaults to TFilePtr::GetCacheDir().
Definition: TFile.hxx:75
The ROOT global object gROOT contains a list of all defined classes.
Definition: TClass.h:75
std::shared_ptr< TFile > fFile
Definition: TFile.hxx:188
void Add(THist< DIMENSIONS, PRECISION_TO, STAT_TO... > &to, const THist< DIMENSIONS, PRECISION_FROM, STAT_FROM... > &from)
Add two histograms.
Definition: THist.hxx:308
Points to an object that stores or reads objects in ROOT&#39;s binary format.
Definition: TFile.hxx:186
void Write(std::string_view name, const T &obj)
Write an object that is not lifetime managed by this TFileImplBase.
Definition: TFile.hxx:146
static TClass * GetClass(const char *name, Bool_t load=kTRUE, Bool_t silent=kFALSE)
Static method returning pointer to TClass of the specified class name.
Definition: TClass.cxx:2887
UInt_t Find(std::list< std::pair< const Node< T > *, Float_t > > &nlist, const Node< T > *node, const T &event, UInt_t nfind)
Key/value store of objects.
Definition: TDirectory.hxx:70
A ROOT file.
Definition: TFile.hxx:45
char name[80]
Definition: TGX11.cxx:109
void Write(std::string_view name)
Write an object that is already lifetime managed by this TFileImplBase.
Definition: TFile.hxx:159