class TTreeCache: public TFileCacheRead

TTreeCache

A specialized TFileCacheRead object for a TTree
This class acts as a file cache, registering automatically the
baskets from the branches being processed (TTree::Draw or
TTree::Process and TSelectors) when in the learning phase.
The learning phase is by default 100 entries.
It can be changed via TTreeCache::SetLearnEntries.

This cache speeds-up considerably the performance, in particular
when the Tree is accessed remotely via a high latency network.

The default cache size (10 Mbytes) may be changed via the function
TTreeCache::SetCacheSize

Only the baskets for the requested entry range are put in the cache

For each Tree being processed a TTreeCache object is created.
This object is automatically deleted when the Tree is deleted or
when the file is deleted.

-Special case of a TChain
Once the training is done on the first Tree, the list of branches
in the cache is kept for the following files.

-Special case of a TEventlist
if the Tree or TChain has a TEventlist, only the buffers
referenced by the list are put in the cache.

  The learning period is started or restarted when:
     - TTree automatically creates a cache. This feature can be
       controlled with an env. variable or the TTreeCache.Size option.
     - TTree::SetCacheSize is called with a non-zero size and a cache
       did not previously exist
     - TTreeCache::StartLearningPhase is called.
     - TTree[Cache]::SetEntryRange is called
          * and the learning is not yet finished
          * and has not been set to manual
          * and the new minimun entry is different.

  The learning period is stopped (and prefetching is actually started) when:
     - TTree[Cache]::StopLearningPhase is called.
     - An entry outside the 'learning' range is requested
       The 'learning range is from fEntryMin (default to 0) to
       fEntryMin + fgLearnEntries (default to 100).
     - A 'cached' TChain switches over to a new file.

     WHY DO WE NEED the TreeCache when doing data analysis?


  When writing a TTree, the branch buffers are kept in memory.
  A typical branch buffersize (before compression) is typically 32 KBytes.
  After compression, the zipped buffer may be just a few Kbytes.
  The branch buffers cannot be much larger in case of Trees with several
  hundred or thousand branches.
  When writing, this does not generate a performance problem because branch
  buffers are always written sequentially and the OS is in general clever enough
  to flush the data to the output file when a few MBytes of data have to be written.
  When reading at the contrary, one may hit a performance problem when reading
  across a network (LAN or WAN) and the network latency is high.
  For example in a WAN with 10ms latency, reading 1000 buffers of 10 KBytes each
  with no cache will imply 10s penalty where a local read of the 10 MBytes would
  take about 1 second.
  The TreeCache will try to prefetch all the buffers for the selected branches
  such that instead of transfering 1000 buffers of 10 Kbytes, it will be able
  to transfer one single large buffer of 10 Mbytes in one single transaction.
  Not only the TreeCache minimizes the number of transfers, but in addition
  it can sort the blocks to be read in increasing order such that the file
  is read sequentially.
  Systems like xrootd, dCache or httpd take advantage of the TreeCache in
  reading ahead as much data as they can and return to the application
  the maximum data specified in the cache and have the next chunk of data ready
  when the next request comes.


     HOW TO USE the TreeCache


  A few use cases are discussed below. A cache may be created with automatic sizing
  when a TTree is used:

  Caches are created and automatically sized for TTrees when TTreeCache.Size or
  the environment variable ROOT_TTREECACHE_SIZE is set to a sizing factor.

  But there are many possible configurations where manual control may be wanted.
  In some applications you know a priori the list of branches to read. In other
  applications the analysis loop calls several layers of user functions where it
  is impossible to predict a priori which branches will be used. This
  is probably the most frequent case. In this case ROOT I/O will flag used
  branches automatically when a branch buffer is read during the learning phase.
  The TreeCache interface provides functions to instruct the cache about the used
  branches if they are known a priori. In the examples below, portions of analysis
  code are shown. The few statements involving the TreeCache are marked with //<<<


  1- with TTree::Draw

  the TreeCache is automatically used by TTree::Draw. The function knows
  which branches are used in the query and it puts automatically these branches
  in the cache. The entry range is also known automatically.


  2- with TTree::Process and TSelectors

  You must enable the cache and tell the system which branches to cache
  and also specify the entry range. It is important to specify the entry range
  in case you process only a subset of the events, otherwise you run the risk
  to store in the cache entries that you do not need.

      --example 2a
--
   TTree *T = (TTree*)f->Get("mytree");
   Long64_t nentries = T->GetEntries();
   Int_t cachesize = 10000000; //10 MBytes
   T->SetCacheSize(cachesize); //<<<
   T->AddBranchToCache("*",kTRUE);    //<<< add all branches to the cache
   T->Process('myselector.C+");
   //in the TSelector::Process function we read all branches
   T->GetEntry(i);
--      ... here you process your entry


      --example 2b
  in the Process function we read a subset of the branches.
  Only the branches used in the first entry will be put in the cache
--
   TTree *T = (TTree*)f->Get("mytree");
   //we want to process only the 200 first entries
   Long64_t nentries=200;
   int efirst= 0;
   int elast = efirst+nentries;
   Int_t cachesize = 10000000; //10 MBytes
   TTreeCache::SetLearnEntries(1);  //<<< we can take the decision after 1 entry
   T->SetCacheSize(cachesize);      //<<<
   T->SetCacheEntryRange(efirst,elast); //<<<
   T->Process('myselector.C+","",nentries,efirst);
   // in the TSelector::Process we read only 2 branches
   TBranch *b1 = T->GetBranch("branch1");
   b1->GetEntry(i);
   if (somecondition) return;
   TBranch *b2 = T->GetBranch("branch2");
   b2->GetEntry(i);
      ... here you process your entry
--

  3- with your own event loop

    --example 3a
      in your analysis loop, you always use 2 branches. You want to prefetch
      the branch buffers for these 2 branches only.
--
   TTree *T = (TTree*)f->Get("mytree");
   TBranch *b1 = T->GetBranch("branch1");
   TBranch *b2 = T->GetBranch("branch2");
   Long64_t nentries = T->GetEntries();
   Int_t cachesize = 10000000; //10 MBytes
   T->SetCacheSize(cachesize);     //<<<
   T->AddBranchToCache(b1,kTRUE);  //<<<add branch1 and branch2 to the cache
   T->AddBranchToCache(b2,kTRUE);  //<<<
   T->StopCacheLearningPhase();    //<<<
   for (Long64_t i=0;i<nentries;i++) {
      T->LoadTree(i); //<<< important call when calling TBranch::GetEntry after
      b1->GetEntry(i);
      if (some condition not met) continue;
      b2->GetEntry(i);
      if (some condition not met) continue;
      //here we read the full event only in some rare cases.
      //there is no point in caching the other branches as it might be
      //more economical to read only the branch buffers really used.
      T->GetEntry(i);
      .. process the rare but interesting cases.
      ... here you process your entry
   }
--
   --example 3b
      in your analysis loop, you always use 2 branches in the main loop.
      you also call some analysis functions where a few more branches will be read.
      but you do not know a priori which ones. There is no point in prefetching
      branches that will be used very rarely.
--
   TTree *T = (TTree*)f->Get("mytree");
   Long64_t nentries = T->GetEntries();
   Int_t cachesize = 10000000;   //10 MBytes
   T->SetCacheSize(cachesize);   //<<<
   T->SetCacheLearnEntries(5);   //<<< we can take the decision after 5 entries
   TBranch *b1 = T->GetBranch("branch1");
   TBranch *b2 = T->GetBranch("branch2");
   for (Long64_t i=0;i<nentries;i++) {
      T->LoadTree(i);
      b1->GetEntry(i);
      if (some condition not met) continue;
      b2->GetEntry(i);
      //at this point we may call a user function where a few more branches
      //will be read conditionally. These branches will be put in the cache
      //if they have been used in the first 10 entries
      if (some condition not met) continue;
      //here we read the full event only in some rare cases.
      //there is no point in caching the other branches as it might be
      //more economical to read only the branch buffers really used.
      T->GetEntry(i);
      .. process the rare but interesting cases.
      ... here you process your entry
   }
--


     SPECIAL CASES WHERE TreeCache should not be activated


   When reading only a small fraction of all entries such that not all branch
   buffers are read, it might be faster to run without a cache.


   HOW TO VERIFY That the TreeCache has been used and check its performance


  Once your analysis loop has terminated, you can access/print the number
  of effective system reads for a given file with a code like
  (where TFile* f is a pointer to your file)

   printf("Reading %lld bytes in %d transactions\n",f->GetBytesRead(),  f->GetReadCalls());