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