Logo ROOT   6.30.04
Reference Guide
 All Namespaces Files Pages
TFile.h
Go to the documentation of this file.
1 // @(#)root/io:$Id$
2 // Author: Rene Brun 28/11/94
3 
4 /*************************************************************************
5  * Copyright (C) 1995-2000, Rene Brun and Fons Rademakers. *
6  * All rights reserved. *
7  * *
8  * For the licensing terms see $ROOTSYS/LICENSE. *
9  * For the list of contributors see $ROOTSYS/README/CREDITS. *
10  *************************************************************************/
11 
12 #ifndef ROOT_TFile
13 #define ROOT_TFile
14 
15 
16 //////////////////////////////////////////////////////////////////////////
17 // //
18 // TFile //
19 // //
20 // ROOT file. //
21 // //
22 //////////////////////////////////////////////////////////////////////////
23 
24 #include <atomic>
25 
26 #include "Compression.h"
27 #include "TDirectoryFile.h"
28 #include "TMap.h"
29 #include "TUrl.h"
30 #include "ROOT/RConcurrentHashColl.hxx"
31 
32 #ifdef R__USE_IMT
33 #include "ROOT/TRWSpinLock.hxx"
34 #include <mutex>
35 #endif
36 
37 
38 class TFree;
39 class TArrayC;
40 class TArchiveFile;
41 class TFileOpenHandle;
42 class TFileCacheRead;
43 class TFileCacheWrite;
44 class TProcessID;
45 class TStopwatch;
46 class TFilePrefetch;
47 
48 class TFile : public TDirectoryFile {
49  friend class TDirectoryFile;
50  friend class TFilePrefetch;
51 // TODO: We need to make sure only one TBasket is being written at a time
52 // if we are writing multiple baskets in parallel.
53 #ifdef R__USE_IMT
54  friend class TBasket;
55 #endif
56 
57 public:
58  /// Asynchronous open request status
59  enum EAsyncOpenStatus { kAOSNotAsync = -1, kAOSFailure = 0,
60  kAOSInProgress = 1, kAOSSuccess = 2 };
61  /// Open timeout constants
62  enum EOpenTimeOut { kInstantTimeout = 0, kEternalTimeout = 999999999 };
63 
64  /// TTreeCache flushing semantics
65  enum ECacheAction { kDisconnect = 0, kDoNotDisconnect = 1 };
66 
67 protected:
68  Double_t fSumBuffer{0}; ///<Sum of buffer sizes of objects written so far
69  Double_t fSum2Buffer{0}; ///<Sum of squares of buffer sizes of objects written so far
70  Long64_t fBytesWrite{0}; ///<Number of bytes written to this file
71  Long64_t fBytesRead{0}; ///<Number of bytes read from this file
72  Long64_t fBytesReadExtra{0}; ///<Number of extra bytes (overhead) read by the readahead buffer
73  Long64_t fBEGIN{0}; ///<First used byte in file
74  Long64_t fEND{0}; ///<Last used byte in file
75  Long64_t fSeekFree{0}; ///<Location on disk of free segments structure
76  Long64_t fSeekInfo{0}; ///<Location on disk of StreamerInfo record
77  Int_t fD{-1}; ///<File descriptor
78  Int_t fVersion{0}; ///<File format version
79  Int_t fCompress{0}; ///<Compression level and algorithm
80  Int_t fNbytesFree{0}; ///<Number of bytes for free segments structure
81  Int_t fNbytesInfo{0}; ///<Number of bytes for StreamerInfo record
82  Int_t fWritten{0}; ///<Number of objects written so far
83  Int_t fNProcessIDs{0}; ///<Number of TProcessID written to this file
84  Int_t fReadCalls{0}; ///<Number of read calls ( not counting the cache calls )
85  TString fRealName; ///<Effective real file name (not original url)
86  TString fOption; ///<File options
87  Char_t fUnits{0}; ///<Number of bytes for file pointers
88  TList *fFree{nullptr}; ///<Free segments linked list table
89  TArrayC *fClassIndex{nullptr}; ///<!Index of TStreamerInfo classes written to this file
90  TObjArray *fProcessIDs{nullptr}; ///<!Array of pointers to TProcessIDs
91  Long64_t fOffset{0}; ///<!Seek offset cache
92  TArchiveFile *fArchive{nullptr}; ///<!Archive file from which we read this file
93  TFileCacheRead *fCacheRead{nullptr}; ///<!Pointer to the read cache (if any)
94  TMap *fCacheReadMap{nullptr}; ///<!Pointer to the read cache (if any)
95  TFileCacheWrite *fCacheWrite{nullptr}; ///<!Pointer to the write cache (if any)
96  Long64_t fArchiveOffset{0}; ///<!Offset at which file starts in archive
97  Bool_t fIsArchive{kFALSE}; ///<!True if this is a pure archive file
98  Bool_t fNoAnchorInName{kFALSE}; ///<!True if we don't want to force the anchor to be appended to the file name
99  Bool_t fIsRootFile{kTRUE}; ///<!True is this is a ROOT file, raw file otherwise
100  Bool_t fInitDone{kFALSE}; ///<!True if the file has been initialized
101  Bool_t fMustFlush{kTRUE}; ///<!True if the file buffers must be flushed
102  Bool_t fIsPcmFile{kFALSE}; ///<!True if the file is a ROOT pcm file.
103  TFileOpenHandle *fAsyncHandle{nullptr}; ///<!For proper automatic cleanup
104  EAsyncOpenStatus fAsyncOpenStatus{kAOSNotAsync}; ///<!Status of an asynchronous open request
105  TUrl fUrl; ///<!URL of file
106 
107  TList *fInfoCache{nullptr}; ///<!Cached list of the streamer infos in this file
108  TList *fOpenPhases{nullptr}; ///<!Time info about open phases
109 
110 #ifdef R__USE_IMT
111  static ROOT::TRWSpinLock fgRwLock; ///<!Read-write lock to protect global PID list
112  std::mutex fWriteMutex; ///<!Lock for writing baskets / keys into the file.
113  static ROOT::Internal::RConcurrentHashColl fgTsSIHashes; ///<!TS Set of hashes built from read streamer infos
114 #endif
115 
116  static TList *fgAsyncOpenRequests; //List of handles for pending open requests
117 
118  static TString fgCacheFileDir; ///<Directory where to locally stage files
119  static Bool_t fgCacheFileDisconnected; ///<Indicates, we trust in the files in the cache dir without stat on the cached file
120  static Bool_t fgCacheFileForce; ///<Indicates, to force all READ to CACHEREAD
121  static UInt_t fgOpenTimeout; ///<Timeout for open operations in ms - 0 corresponds to blocking i/o
122  static Bool_t fgOnlyStaged ; ///<Before the file is opened, it is checked, that the file is staged, if not, the open fails
123 
124  static std::atomic<Long64_t> fgBytesWrite; ///<Number of bytes written by all TFile objects
125  static std::atomic<Long64_t> fgBytesRead; ///<Number of bytes read by all TFile objects
126  static std::atomic<Long64_t> fgFileCounter; ///<Counter for all opened files
127  static std::atomic<Int_t> fgReadCalls; ///<Number of bytes read from all TFile objects
128  static Int_t fgReadaheadSize; ///<Readahead buffer size
129  static Bool_t fgReadInfo; ///<if true (default) ReadStreamerInfo is called when opening a file
130 
131  virtual EAsyncOpenStatus GetAsyncOpenStatus() { return fAsyncOpenStatus; }
132  virtual void Init(Bool_t create);
133  Bool_t FlushWriteCache();
134  Int_t ReadBufferViaCache(char *buf, Int_t len);
135  Int_t WriteBufferViaCache(const char *buf, Int_t len);
136 
137  ////////////////////////////////////////////////////////////////////////////////
138  /// \brief Simple struct of the return value of GetStreamerInfoListImpl
139  struct InfoListRet {
140  TList *fList;
141  Int_t fReturnCode;
142  ROOT::Internal::RConcurrentHashColl::HashValue fHash;
143  };
144 
145  virtual InfoListRet GetStreamerInfoListImpl(bool lookupSICache);
146 
147  // Creating projects
148  Int_t MakeProjectParMake(const char *packname, const char *filename);
149  Int_t MakeProjectParProofInf(const char *packname, const char *proofinfdir);
150 
151  // Interface to basic system I/O routines
152  virtual Int_t SysOpen(const char *pathname, Int_t flags, UInt_t mode);
153  virtual Int_t SysClose(Int_t fd);
154  virtual Int_t SysRead(Int_t fd, void *buf, Int_t len);
155  virtual Int_t SysWrite(Int_t fd, const void *buf, Int_t len);
156  virtual Long64_t SysSeek(Int_t fd, Long64_t offset, Int_t whence);
157  virtual Int_t SysStat(Int_t fd, Long_t *id, Long64_t *size, Long_t *flags, Long_t *modtime);
158  virtual Int_t SysSync(Int_t fd);
159 
160  // Interface for text-based TDirectory I/O
161  virtual Long64_t DirCreateEntry(TDirectory*) { return 0; }
162  virtual Int_t DirReadKeys(TDirectory*) { return 0; }
163  virtual void DirWriteKeys(TDirectory*) {}
164  virtual void DirWriteHeader(TDirectory*) {}
165 
166 private:
167  TFile(const TFile &) = delete; //Files cannot be copied
168  void operator=(const TFile &) = delete;
169 
170  static void CpProgress(Long64_t bytesread, Long64_t size, TStopwatch &watch);
171  static TFile *OpenFromCache(const char *name, Option_t * = "",
172  const char *ftitle = "", Int_t compress = ROOT::RCompressionSetting::EDefaults::kUseCompiledDefault,
173  Int_t netopt = 0);
174 
175 public:
176  /// TFile status bits. BIT(13) is taken up by TObject
177  enum EStatusBits {
178  kRecovered = BIT(10),
179  kHasReferences = BIT(11),
180  kDevNull = BIT(12),
181  kWriteError = BIT(14),
182  kBinaryFile = BIT(15),
183  kRedirected = BIT(16),
184  kReproducible = BIT(17)
185  };
186  enum ERelativeTo { kBeg = 0, kCur = 1, kEnd = 2 };
187  enum { kStartBigFile = 2000000000 };
188  /// File type
189  enum EFileType { kDefault = 0, kLocal = 1, kNet = 2, kWeb = 3, kFile = 4, kMerge = 5 };
190 
191  TFile();
192  TFile(const char *fname, Option_t *option="", const char *ftitle="", Int_t compress = ROOT::RCompressionSetting::EDefaults::kUseCompiledDefault);
193  virtual ~TFile();
194 
195  void Close(Option_t *option="") override; // *MENU*
196  void Copy(TObject &) const override { MayNotUse("Copy(TObject &)"); }
197  virtual Bool_t Cp(const char *dst, Bool_t progressbar = kTRUE,UInt_t buffersize = 1000000);
198  virtual TKey* CreateKey(TDirectory* mother, const TObject* obj, const char* name, Int_t bufsize);
199  virtual TKey* CreateKey(TDirectory* mother, const void* obj, const TClass* cl,
200  const char* name, Int_t bufsize);
201  static TFile *&CurrentFile(); // Return the current file for this thread.
202  void Delete(const char *namecycle="") override;
203  void Draw(Option_t *option="") override;
204  virtual void DrawMap(const char *keys="*",Option_t *option=""); // *MENU*
205  void FillBuffer(char *&buffer) override;
206  virtual void Flush();
207  TArchiveFile *GetArchive() const { return fArchive; }
208  Long64_t GetArchiveOffset() const { return fArchiveOffset; }
209  Int_t GetBestBuffer() const;
210  virtual Int_t GetBytesToPrefetch() const;
211  TFileCacheRead *GetCacheRead(const TObject* tree = nullptr) const;
212  TFileCacheWrite *GetCacheWrite() const;
213  TArrayC *GetClassIndex() const { return fClassIndex; }
214  Int_t GetCompressionAlgorithm() const;
215  Int_t GetCompressionLevel() const;
216  Int_t GetCompressionSettings() const;
217  Float_t GetCompressionFactor();
218  virtual Long64_t GetEND() const { return fEND; }
219  virtual Int_t GetErrno() const;
220  virtual void ResetErrno() const;
221  Int_t GetFd() const { return fD; }
222  virtual const TUrl *GetEndpointUrl() const { return &fUrl; }
223  TObjArray *GetListOfProcessIDs() const {return fProcessIDs;}
224  TList *GetListOfFree() const { return fFree; }
225  virtual Int_t GetNfree() const { return fFree->GetSize(); }
226  virtual Int_t GetNProcessIDs() const { return fNProcessIDs; }
227  Option_t *GetOption() const override { return fOption.Data(); }
228  virtual Long64_t GetBytesRead() const { return fBytesRead; }
229  virtual Long64_t GetBytesReadExtra() const { return fBytesReadExtra; }
230  virtual Long64_t GetBytesWritten() const;
231  virtual Int_t GetReadCalls() const { return fReadCalls; }
232  Int_t GetVersion() const { return fVersion; }
233  Int_t GetRecordHeader(char *buf, Long64_t first, Int_t maxbytes,
234  Int_t &nbytes, Int_t &objlen, Int_t &keylen);
235  virtual Int_t GetNbytesInfo() const {return fNbytesInfo;}
236  virtual Int_t GetNbytesFree() const {return fNbytesFree;}
237  virtual TString GetNewUrl() { return ""; }
238  Long64_t GetRelOffset() const { return fOffset - fArchiveOffset; }
239  virtual Long64_t GetSeekFree() const {return fSeekFree;}
240  virtual Long64_t GetSeekInfo() const {return fSeekInfo;}
241  virtual Long64_t GetSize() const;
242  virtual TList *GetStreamerInfoList() final; // Note: to override behavior, please override GetStreamerInfoListImpl
243  const TList *GetStreamerInfoCache();
244  virtual void IncrementProcessIDs() { fNProcessIDs++; }
245  virtual Bool_t IsArchive() const { return fIsArchive; }
246  Bool_t IsBinary() const { return TestBit(kBinaryFile); }
247  Bool_t IsRaw() const { return !fIsRootFile; }
248  virtual Bool_t IsOpen() const;
249  void ls(Option_t *option="") const override;
250  virtual void MakeFree(Long64_t first, Long64_t last);
251  virtual void MakeProject(const char *dirname, const char *classes="*",
252  Option_t *option="new"); // *MENU*
253  virtual void Map(Option_t *opt); // *MENU*
254  virtual void Map() { Map(""); }; // *MENU*
255  virtual Bool_t Matches(const char *name);
256  virtual Bool_t MustFlush() const {return fMustFlush;}
257  void Paint(Option_t *option="") override;
258  void Print(Option_t *option="") const override;
259  virtual Bool_t ReadBufferAsync(Long64_t offs, Int_t len);
260  virtual Bool_t ReadBuffer(char *buf, Int_t len);
261  virtual Bool_t ReadBuffer(char *buf, Long64_t pos, Int_t len);
262  virtual Bool_t ReadBuffers(char *buf, Long64_t *pos, Int_t *len, Int_t nbuf);
263  virtual void ReadFree();
264  virtual TProcessID *ReadProcessID(UShort_t pidf);
265  virtual void ReadStreamerInfo();
266  virtual Int_t Recover();
267  virtual Int_t ReOpen(Option_t *mode);
268  virtual void Seek(Long64_t offset, ERelativeTo pos = kBeg);
269  virtual void SetCacheRead(TFileCacheRead *cache, TObject* tree = 0, ECacheAction action = kDisconnect);
270  virtual void SetCacheWrite(TFileCacheWrite *cache);
271  virtual void SetCompressionAlgorithm(Int_t algorithm = ROOT::RCompressionSetting::EAlgorithm::kUseGlobal);
272  virtual void SetCompressionLevel(Int_t level = ROOT::RCompressionSetting::ELevel::kUseMin);
273  virtual void SetCompressionSettings(Int_t settings = ROOT::RCompressionSetting::EDefaults::kUseCompiledDefault);
274  virtual void SetEND(Long64_t last) { fEND = last; }
275  virtual void SetOffset(Long64_t offset, ERelativeTo pos = kBeg);
276  virtual void SetOption(Option_t *option=">") { fOption = option; }
277  virtual void SetReadCalls(Int_t readcalls = 0) { fReadCalls = readcalls; }
278  virtual void ShowStreamerInfo();
279  Int_t Sizeof() const override;
280  void SumBuffer(Int_t bufsize);
281  virtual Bool_t WriteBuffer(const char *buf, Int_t len);
282  Int_t Write(const char *name=nullptr, Int_t opt=0, Int_t bufsiz=0) override;
283  Int_t Write(const char *name=nullptr, Int_t opt=0, Int_t bufsiz=0) const override;
284  virtual void WriteFree();
285  virtual void WriteHeader();
286  virtual UShort_t WriteProcessID(TProcessID *pid);
287  virtual void WriteStreamerInfo();
288 
289  static TFileOpenHandle
290  *AsyncOpen(const char *name, Option_t *option = "",
291  const char *ftitle = "", Int_t compress = ROOT::RCompressionSetting::EDefaults::kUseCompiledDefault,
292  Int_t netopt = 0);
293  static TFile *Open(const char *name, Option_t *option = "",
294  const char *ftitle = "", Int_t compress = ROOT::RCompressionSetting::EDefaults::kUseCompiledDefault,
295  Int_t netopt = 0);
296  static TFile *Open(TFileOpenHandle *handle);
297 
298  static EFileType GetType(const char *name, Option_t *option = "", TString *prefix = nullptr);
299 
300  static EAsyncOpenStatus GetAsyncOpenStatus(const char *name);
301  static EAsyncOpenStatus GetAsyncOpenStatus(TFileOpenHandle *handle);
302  static const TUrl *GetEndpointUrl(const char *name);
303 
304  static Long64_t GetFileBytesRead();
305  static Long64_t GetFileBytesWritten();
306  static Int_t GetFileReadCalls();
307  static Int_t GetReadaheadSize();
308 
309  static void SetFileBytesRead(Long64_t bytes = 0);
310  static void SetFileBytesWritten(Long64_t bytes = 0);
311  static void SetFileReadCalls(Int_t readcalls = 0);
312  static void SetReadaheadSize(Int_t bufsize = 256000);
313  static void SetReadStreamerInfo(Bool_t readinfo=kTRUE);
314  static Bool_t GetReadStreamerInfo();
315 
316  static Long64_t GetFileCounter();
317  static void IncrementFileCounter();
318 
319  static Bool_t SetCacheFileDir(ROOT::Internal::TStringView cacheDir, Bool_t operateDisconnected = kTRUE,
320  Bool_t forceCacheread = kFALSE)
321  { return SetCacheFileDir(std::string_view(cacheDir), operateDisconnected, forceCacheread); }
322  static Bool_t SetCacheFileDir(std::string_view cacheDir, Bool_t operateDisconnected = kTRUE,
323  Bool_t forceCacheread = kFALSE);
324  static const char *GetCacheFileDir();
325  static Bool_t ShrinkCacheFileDir(Long64_t shrinkSize, Long_t cleanupInteval = 0);
326  static Bool_t Cp(const char *src, const char *dst, Bool_t progressbar = kTRUE,
327  UInt_t buffersize = 1000000);
328 
329  static UInt_t SetOpenTimeout(UInt_t timeout); // in ms
330  static UInt_t GetOpenTimeout(); // in ms
331  static Bool_t SetOnlyStaged(Bool_t onlystaged);
332  static Bool_t GetOnlyStaged();
333 
334  ClassDefOverride(TFile,8) //ROOT file
335 };
336 
337 #ifndef __CINT__
338 #define gFile (TFile::CurrentFile())
339 
340 #elif defined(__MAKECINT__)
341 // To properly handle the use of gFile in header files (in static declarations)
342 R__EXTERN TFile *gFile;
343 #endif
344 
345 /**
346 \class TFileOpenHandle
347 \ingroup IO
348 Class holding info about the file being opened
349 */
350 class TFileOpenHandle : public TNamed {
351 
352 friend class TFile;
353 friend class TAlienFile;
354 
355 private:
356  TString fOpt; ///< Options
357  Int_t fCompress{0}; ///< Compression level and algorithm
358  Int_t fNetOpt{0}; ///< Network options
359  TFile *fFile{nullptr}; ///< TFile instance of the file being opened
360 
361  TFileOpenHandle(TFile *f) : TNamed("",""), fOpt(""), fCompress(ROOT::RCompressionSetting::EDefaults::kUseCompiledDefault),
362  fNetOpt(0), fFile(f) { }
363  TFileOpenHandle(const char *n, const char *o, const char *t, Int_t cmp,
364  Int_t no) : TNamed(n,t), fOpt(o), fCompress(cmp),
365  fNetOpt(no), fFile(nullptr) { }
366  TFileOpenHandle(const TFileOpenHandle&) = delete;
367  TFileOpenHandle& operator=(const TFileOpenHandle&) = delete;
368 
369  TFile *GetFile() const { return fFile; }
370 
371 public:
372  ~TFileOpenHandle() { }
373 
374  Bool_t Matches(const char *name);
375 
376  const char *GetOpt() const { return fOpt; }
377  Int_t GetCompress() const { return fCompress; }
378  Int_t GetNetOpt() const { return fNetOpt; }
379 };
380 
381 //______________________________________________________________________________
382 inline Int_t TFile::GetCompressionAlgorithm() const
383 {
384  return (fCompress < 0) ? -1 : fCompress / 100;
385 }
386 
387 //______________________________________________________________________________
388 inline Int_t TFile::GetCompressionLevel() const
389 {
390  return (fCompress < 0) ? -1 : fCompress % 100;
391 }
392 
393 //______________________________________________________________________________
394 inline Int_t TFile::GetCompressionSettings() const
395 {
396  return (fCompress < 0) ? -1 : fCompress;
397 }
398 
399 #endif