[nfc][tree] Clarify prefetch behavior

#16640 (comment)

Author: ferdymercury

config/rootrc.in

@@ -452,6 +452,9 @@ RSA.KeyType:  1
 
 # Control the usage of asynchronous prefetching capabilities irrespective
 # of the TFile implementation. By default it is disabled.
+# In conjunction with a TFileCacheRead (for example the TTreeCache), it
+# will asynchronously grab early the compressed data of the 'next' cluster
+# while the current cluster is being processed (ie is subject of GetEntry)
 #TFile.AsyncPrefetching:   no
 
 # Enable cross-protocol redirects

tree/tree/inc/TTree.h

@@ -687,6 +687,11 @@ class TTree : public TNamed, public TAttLine, public TAttFill, public TAttMarker
    virtual void            SetCacheLearnEntries(Int_t n=10);
    virtual void            SetChainOffset(Long64_t offset = 0) { fChainOffset=offset; }
    virtual void            SetCircular(Long64_t maxEntries);
+   /// Enables (or disables) the early decompression of the baskets of the current cluster
+   /// (whose compressed data is already in memory if used in conjunction with the TTreeCache).
+   /// This affects performance only in conjunction with non-sequential use/load/read of the entries, ie
+   /// within a cluster you can have cheap random access to the entries (instead of having to decompress again and again).
+   /// \note This setting is totally different from SetCacheSize and from TFile.AsyncPrefetching, which save read calls
    virtual void            SetClusterPrefetch(bool enabled) { fCacheDoClusterPrefetch = enabled; }
    virtual void            SetDebug(Int_t level = 1, Long64_t min = 0, Long64_t max = 9999999); // *MENU*
    virtual void            SetDefaultEntryOffsetLen(Int_t newdefault, bool updateExisting = false);

tree/tree/src/TTree.cxx

@@ -5477,7 +5477,7 @@ Int_t TTree::GetBranchStyle()
 ////////////////////////////////////////////////////////////////////////////////
 /// Used for automatic sizing of the cache.
 ///
-/// Estimates a suitable size for the tree cache based on AutoFlush.
+/// Estimates a suitable size in bytes for the tree cache based on AutoFlush.
 /// A cache sizing factor is taken from the configuration. If this yields zero
 /// and withDefault is true the historical algorithm for default size is used.
 
@@ -8876,14 +8876,18 @@ void TTree::SetBranchStyle(Int_t style)
 }
 
 ////////////////////////////////////////////////////////////////////////////////
-/// Set maximum size of the file cache .
+/// Set maximum size of the file cache (TTreeCache) in bytes.
 //
-/// - if cachesize = 0 the existing cache (if any) is deleted.
+/// - if cachesize = 0 the existing cache (if any) is disabled (deleted if any).
+/// - if cachesize > 0, the cache is enabled or extended, if necessary
 /// - if cachesize = -1 (default) it is set to the AutoFlush value when writing
 ///    the Tree (default is 30 MBytes).
 ///
 /// The cacheSize might be clamped, see TFileCacheRead::SetBufferSize
 ///
+/// TTreeCache's 'real' job is to actually prefetch (early grab from disk) the compressed data.
+/// The cachesize controls the size of the read bytes from disk.
+///
 /// Returns:
 /// - 0 size set, cache was created if possible
 /// - -1 on error
@@ -8897,20 +8901,25 @@ Int_t TTree::SetCacheSize(Long64_t cacheSize)
 }
 
 ////////////////////////////////////////////////////////////////////////////////
-/// Set the size of the file cache and create it if possible.
+/// Set the maximum size of the file cache (TTreeCache) in bytes and create it if possible.
 ///
 /// If autocache is true:
 /// this may be an autocreated cache, possibly enlarging an existing
 /// autocreated cache. The size is calculated. The value passed in cacheSize:
-/// - cacheSize =  0  make cache if default cache creation is enabled
+/// - cacheSize =  0  make cache if default cache creation is enabled.
+/// - cachesize >  0  the cache is enabled or extended, if necessary
 /// - cacheSize = -1  make a default sized cache in any case
 ///
 /// If autocache is false:
 /// this is a user requested cache. cacheSize is used to size the cache.
-/// This cache should never be automatically adjusted.
+/// This cache should never be automatically adjusted. If cachesize is
+/// 0, the cache is disabled (deleted if any).
 ///
 /// The cacheSize might be clamped, see TFileCacheRead::SetBufferSize
 ///
+/// TTreeCache's 'real' job is to actually prefetch (early grab from disk) the compressed data.
+/// The cachesize controls the size of the read bytes from disk.
+///
 /// Returns:
 /// - 0 size set, or existing autosized cache almost large enough.
 ///   (cache was created if possible)