library: libCore #include "TCache.h"

# TCache

class description - source file - inheritance tree (.pdf)

## class TCache : public TObject

| Inheritance Chart:
`TObject`
| <- | `TCache` |

        private:

                   Int_t FlushList(TList* list)
                   Int_t FlushNew()
                   Int_t Free(ULong_t upto)
          TCache::TPage* ReadPage(Long64_t offset)
                    void SetPageSize(Int_t size)
                   Int_t WritePage(TCache::TPage* page)

        public:

                          TCache(Int_t maxCacheSize, TFile* file, Int_t pageSize = kDfltPageSize)
                          TCache(const TCache&)
                  virtual ~TCache()
           static TClass* Class()
                    Int_t Flush()
                    Int_t GetActiveCacheSize() const
                    Int_t GetLowLevel() const
                    Int_t GetMaxCacheSize() const
                    Int_t GetPageSize() const
          virtual TClass* IsA() const
                  TCache& operator=(const TCache&)
                    Int_t ReadBuffer(Long64_t offset, char* buf, Int_t len)
                    Int_t Resize(Int_t maxCacheSize)
                     void SetLowLevel(Int_t percentOfHigh)
             virtual void ShowMembers(TMemberInspector& insp, char* parent)
             virtual void Streamer(TBuffer& b)
                     void StreamerNVirtual(TBuffer& b)
                    Int_t WriteBuffer(Long64_t offset, const char* buf, Int_t len)

### Data Members

        private:

          TCache::TCacheList* fCache      hash list containing cached pages
                 TSortedList* fNew        list constaining new pages that have to be written to disk
                       TList* fFree       list containing unused pages
                       TFile* fFile       file for which pages are being cached
                     Long64_t fEOF        end of file
                      ULong_t fHighWater  high water mark (i.e. maximum cache size in bytes)
                      ULong_t fLowWater   low water mark (free pages till low water mark is reached)
                        Int_t fPageSize   size of cached pages
                        Int_t fLowLevel   low water mark is at low level percent of high
                        Int_t fDiv        page size divider
                       Bool_t fRecursive  true to prevent recusively calling ReadBuffer()

        public:

          static const enum TCache:: kDfltPageSize
          static const enum TCache:: kDfltLowLevel

## Class Description

     TCache

     A caching system to speed up network I/O, i.e. when there is
     no operating system caching support (like the buffer cache for
     local disk I/O). The cache makes sure that every I/O is done with
     a (large) fixed length buffer thereby avoiding many small I/O's.
     The default page size is 512KB. The cache size is not very important
     when writing sequentially a file, since the pages will not be
     reused. In that case use a small cache containing 10 to 20 pages.
     In case a file is used for random-access the cache size should be
     taken much larger to avoid re-reading pages over the network.
     Notice that the TTree's have their own caching mechanism (see
     TTree::SetMaxVirtualSize()), so when using mainly TTree's with large
     basket buffers the cache can be kept quite small.
     Currently the TCache system is used by the classes TNetFile,
     TRFIOFile and TWebFile.

     Extra improvement would be to run the Free() process in a separate
     thread. Possible flush parameters:
     nfract  25   fraction of dirty buffers above which the flush process
                  is activated
     ndirty  500  maximum number of buffer block which may be written
                  during a flush

TCache(Int_t maxCacheSize, TFile *file, Int_t pageSize)

     Create a file cache. Mainly useful for remote files like TNetFile,
     TWebFile and TRFIOFile where the local OS is not doing any caching.
     The maxCacheSize is in MBytes and the pageSize is in bytes (default
     being kDfltPageSize).

~TCache()

     Clean up cache.

void SetPageSize(Int_t size)

     Make sure the page size is a power of two, with a minimum of 4096.

Int_t ReadBuffer(Long64_t offset, char *buf, Int_t len)

     Return in buf len bytes starting at offset. Returns < 0 in
     case of error, 0 in case ReadBuffer() was recursively called
     via ReadPage() and 1 in case of success.

Int_t WritePage(TPage *page)

     Write dirty page to file. Returns -1 in case of error.

Int_t WriteBuffer(Long64_t offset, const char *buf, Int_t len)

     Write a buffer to the cache. Returns < 0 in case of error, 0 in
     case WriteBuffer() was recursively called via WritePage() and 1
     in case of success.

Int_t Free(ULong_t upto)

     Free pages so that specified number of bytes remains in the cache.
     Dirty pages are written to file. Returns < 0 in case of error
     (typically when there was an error writing a dirty page).

Int_t FlushList(TList *list)

     Flush all dirty pages in the specified list to file. Return < 0 in
     case of error (typically when there was an error writing a dirty page).

Int_t Flush()

     Flush all dirty pages to file. Return < 0 in case of error
     (typically when there was an error writing a dirty page).

Int_t FlushNew()

     Flush all new pages to file. New pages are pages in the fNew list.
     When a page is in this list it means that this page extends the file
     (i.e. is adds new pages to the file). The issue with new pages is that
     they need to be flushed in the right order. One can not write at an
     offset past the EOF. Therefore the new pages are put in a sorted
     list and then written in ascending fOffset order.

Int_t Resize(Int_t maxCacheSize)

     Resize the cache (either increase or decrease the size). Returns the
     previous cache size or -1 in case of error. Input and output is in MB's.
     Minimum cache size is 1 MB.

Int_t GetActiveCacheSize() const

     Get size of all allocated cache pages (in use and free pages).

void SetLowLevel(Int_t percentOfHigh)

     Set the low water level. This is in percent of the maxCacheSize.
     When the cache is full it will be freed up to percentOfHigh. The
     default is kDfltLowLevel=70%.

### Inline Functions

            TCache::TPage* ReadPage(Long64_t offset)
                     Int_t GetMaxCacheSize() const
                     Int_t GetPageSize() const
                     Int_t GetLowLevel() const
                   TClass* Class()
                   TClass* IsA() const
                      void ShowMembers(TMemberInspector& insp, char* parent)
                      void Streamer(TBuffer& b)
                      void StreamerNVirtual(TBuffer& b)
                    TCache TCache(const TCache&)
                   TCache& operator=(const TCache&)

Author: Fons Rademakers 13/01/2001
Last update: root/net:$Name: $:$Id: TCache.cxx,v 1.7 2004/01/19 18:31:13 rdm Exp $
Copyright (C) 1995-2001, Rene Brun and Fons Rademakers. *