library: libCore #include "TMapFile.h"

# TMapFile

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

## class TMapFile : public TObject

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

        protected:

                       TMapFile()
                       TMapFile(const char* name, const char* title, Option_t* option, Int_t size, TMapFile*& newMapFile)
                       TMapFile(const TMapFile& f, Long_t offset = 0)
                 Int_t AcquireSemaphore()
                  void CreateSemaphore(Int_t pid = 0)
                  void DeleteSemaphore()
             TMapFile* FindShadowMapFile()
                 Int_t GetBestBuffer()
                  void InitDirectory()
          static void* MapToAddress()
                  void operator=(const TMapFile& rhs)
                 Int_t ReleaseSemaphore()
              TObject* Remove(TObject* obj, Bool_t lock)
              TObject* Remove(const char* name, Bool_t lock)
                  void SumBuffer(Int_t bufsize)

        public:

                      virtual ~TMapFile()
                         void Add(const TObject* obj, const char* name = "")
                 virtual void Browse(TBrowser* b)
                       Bool_t cd(const char* path = "0")
               static TClass* Class()
                         void Close(Option_t* option = "")
             static TMapFile* Create(const char* name, Option_t* option = "READ", Int_t size = kDefaultMapSize, const char* title = "")
                     TObject* Get(const char* name, TObject* retObj = 0)
                        void* GetBaseAddr() const
                        void* GetBreakval() const
                  TDirectory* GetDirectory() const
                        Int_t GetFd() const
                     TMapRec* GetFirst() const
                     TMapRec* GetLast() const
                        void* GetMmallocDesc() const
          virtual const char* GetName() const
          virtual const char* GetOption() const
                        Int_t GetSize() const
          virtual const char* GetTitle() const
              virtual TClass* IsA() const
               virtual Bool_t IsFolder() const
                       Bool_t IsWritable() const
                 virtual void ls(Option_t* option = "") const
                  static void operator delete(void* vp)
                        void* OrgAddress(void* addr) const
                 virtual void Print(Option_t* option = "") const
                     TObject* Remove(TObject* obj)
                     TObject* Remove(const char* name)
                         void RemoveAll()
                  static void SetMapAddress(Long_t addr)
                 virtual void ShowMembers(TMemberInspector& insp, char* parent)
                 virtual void Streamer(TBuffer& b)
                         void StreamerNVirtual(TBuffer& b)
                         void Update(TObject* obj = 0)
             static TMapFile* WhichMapFile(void* addr)

### Data Members

        private:

                  Int_t fFd            Descriptor of mapped file
                  Int_t fVersion       ROOT version (or -1 for shadow map file)
                  char* fName          Name of mapped file
                  char* fTitle         Title of mapped file
                  char* fOption        Directory creation options
                  void* fMmallocDesc   Pointer to mmalloc descriptor
                ULong_t fBaseAddr      Base address of mapped memory region
                  Int_t fSize          Original start size of memory mapped region
               TMapRec* fFirst         List of streamed objects is shared memory
               TMapRec* fLast          Last object in list of shared objects
                 Long_t fOffset        Offset in bytes for region mapped by reader
            TDirectory* fDirectory     Pointer to directory associated to this mapfile
                 TList* fBrowseList    List of KeyMapFile objects
                 Bool_t fWritable      TRUE if mapped file opened in RDWR mode
                  Int_t fSemaphore     Modification semaphore (or getpid() for WIN32)
                ULong_t fhSemaphore    HANDLE of WIN32 Mutex object to implement semaphore
               TObject* fGetting       Don't deadlock in update mode, when from Get() Add() is called
                  Int_t fWritten       Number of objects written sofar
               Double_t fSumBuffer     Sum of buffer sizes of objects written sofar
               Double_t fSum2Buffer    Sum of squares of buffer sizes of objects written so far
          static Long_t fgMapAddress   Map to this address, set address via SetMapAddress()
           static void* fgMmallocDesc  Used in Close() and operator delete()

        public:

          static const enum TMapFile:: kDefaultMapSize

## Class Description

     TMapFile

     This class implements a shared memory region mapped to a file.
     Objects can be placed into this shared memory area using the Add()
     member function. To actually place a copy of the object is shared
     memory call Update() also whenever the mapped object(s) change(s)
     call Update() to put a fresh copy in the shared memory. This extra
     step is necessary since it is not possible to share objects with
     virtual pointers between processes (the vtbl ptr points to the
     originators unique address space and can not be used by the
     consumer process(es)). Consumer processes can map the memory region
     from this file and access the objects stored in it via the Get()
     method (which returns a copy of the object stored in the shared
     memory with correct vtbl ptr set). Only objects of classes with a
     Streamer() member function defined can be shared.

     I know the current implementation is not ideal (you need to copy to
     and from the shared memory file) but the main problem is with the
     class' virtual_table pointer. This pointer points to a table unique
     for every process. Therefore, different options are:
       1) One could allocate an object directly in shared memory in the
          producer, but the consumer still has to copy the object from
          shared memory into a local object which has the correct vtbl
          pointer for that process (copy ctor's can be used for creating
          the local copy).
       2) Another possibility is to only allow objects without virtual
          functions in shared memory (like simple C structs), or to
          forbid (how?) the consumer from calling any virtual functions
          of the objects in shared memory.
       3) A last option is to copy the object internals to shared memory
          and copy them again from there. This is what is done in the
          TMapFile (using the object Streamer() to make a deep copy).
     Option 1) saves one copy, but requires solid copy ctor's (along the
     full inheritance chain) to rebuild the object in the consumer. Most
     classes don't provide these copy ctor's, especially not when objects
     contain collections, etc. 2) is too limiting or dangerous (calling
     accidentally a virtual function will segv). So since we have a
     robust Streamer mechanism I opted for 3).

TMapFile()

     Default ctor. Does not much except setting some basic values.

TMapFile(const char *name, const char *title, Option_t *option, Int_t size, TMapFile *&newMapFile)

     Create a memory mapped file. This opens a file (to which the
     memory will be mapped) and attaches a memory region to it.
     Option can be either: "NEW", "CREATE", "RECREATE", "UPDATE" or
     "READ" (see TFile). The default open mode is "READ". The size
     argument specifies the maximum size of shared memory file in bytes.
     This protected ctor is called via the static Create() method.

TMapFile(const TMapFile &f, Long_t offset) : TObject(f)

     Private copy ctor. Used by the the ctor to create a new version
     of TMapFile in the memory mapped heap. It's main purpose is to
     correctly create the string data members.

~TMapFile()

     TMapFiles may not be deleted, since we want to keep the complete
     TMapFile object in the mapped file for later re-use. To enforce this
     the delete operator has been made private. Use Close() to properly
     terminate a TMapFile (also done via the TROOT dtor).

void InitDirectory()

     Create the directory associated to this mapfile

void Add(const TObject *obj, const char *name)

     Add an object to the list of objects to be stored in shared memory.
     To place the object actually into shared memory call Update().

void Update(TObject *obj)

     Update an object (or all objects, if obj == 0) in shared memory.

TObject* Remove(TObject *obj, Bool_t lock)

     Remove object from shared memory. Returns pointer to removed
     object if successful, 0 otherwise.

TObject* Remove(const char *name, Bool_t lock)

     Remove object by name from shared memory. Returns pointer to removed
     object if successful, 0 otherwise.

void RemoveAll()

     Remove all objects from shared memory.

TObject* Get(const char *name, TObject *delObj)

     Return pointer to object retrieved from shared memory. The object must
     be deleted after use. If delObj is a pointer to a previously allocated
     object it will be deleted. Returns 0 in case object with the given
     name does not exist.

void CreateSemaphore(int) #else void TMapFile::CreateSemaphore(int pid) #endif

     Create semaphore used for synchronizing access to shared memory.

void DeleteSemaphore()

     Delete the semaphore.

Int_t AcquireSemaphore()

     Acquire semaphore. Returns 0 if OK, -1 on error.

Int_t ReleaseSemaphore()

     Release semaphore. Returns 0 if OK, -1 on error.

void Close(Option_t *option)

     Close a mapped file. First detach mapped memory then close file.
     No member functions of a TMapFile that was opened in write mode
     may be called after Close() (this includes, of course, "delete" which
     would call the dtors). The option="dtor" is only used when called
     via the ~TMapFile.

TMapFile* FindShadowMapFile()

     Returns shadow map file.

void Print(Option_t *) const

     Print some info about the mapped file.

Bool_t IsFolder() const

     Returns kTRUE in case object is a folder (i.e. contains browsable lists).

void Browse(TBrowser *b)

     Browse contents of TMapFile.

Bool_t cd(const char *path)

     Cd to associated directory,

void ls(Option_t *) const

     List contents of TMapFile.

void SumBuffer(Int_t bufsize)

     Increment statistics for buffer sizes of objects in this file.

Int_t GetBestBuffer()

     Return the best buffer size for objects in this file.

     The best buffer size is estimated based on the current mean value
     and standard deviation of all objects written so far to this file.
     Returns mean value + one standard deviation.

TMapFile* Create(const char *name, Option_t *option, Int_t size, const char *title)

     Create a memory mapped file. This opens a file (to which the
     memory will be mapped) and attaches a memory region to it.
     Option can be either: "NEW", "CREATE", "RECREATE", "UPDATE"
     or "READ" (see TFile). The default open mode is "READ". The size
     argument specifies the maximum size of shared memory file in bytes.
     TMapFile's can only be created via this method. Create() enforces that
     a TMapFile is always on the memory mapped heap (when "NEW", "CREATE"
     or "RECREATE" are used).

void SetMapAddress(Long_t addr)

     Set preferred map address. Find out preferred map address as follows:
     1) Run consumer program to find the preferred map address:
           $ root
           root [0] m = TMapFile::Create("dummy.map", "recreate", 10000000);
           root [1] m.Print()
           Memory mapped file:   dummy.map
           Title:
           Option:               CREATE
           Mapped Memory region: 0x40b4c000 - 0x40d95f00 (2.29 MB)
           Current breakval:     0x40b53000
           root [2] .q
           $ rm dummy.map
        Remember begin of mapped region, i.e. 0x40b4c000

     2) Add to producer program, just before creating the TMapFile:
           TMapFile::SetMapAddress(0x40b4c000);

     Repeat this if more than one map file is being used.

     The above procedure allow programs using, e.g., different number of
     shared libraries (that cause the default mapping address to be
     different) to create shared memory regions in the same location
     without overwriting a shared library. The above assumes the consumer
     program is larger (i.e. has more shared memory occupied) than the
     producer. If this is not true inverse the procedure.

void* MapToAddress()

     Return the base address at which we would like the next TMapFile's
     mapped data to start.

     For now, we let the system decide (start address 0). There are
     a lot of issues to deal with here to make this work reasonably,
     including:

     - Avoid memory collisions with existing mapped address spaces

     - Reclaim address spaces when their mmalloc heaps are unmapped

     - When mmalloc heaps are shared between processes they have to be
       mapped at the same addresses in each

     Once created, a mmalloc heap that is to be mapped back in must be
     mapped at the original address.  I.E. each TMapFile will expect
     to be remapped at it's original address. This becomes a problem if
     the desired address is already in use.

### Inline Functions

                   void operator=(const TMapFile& rhs)
                   void operator delete(void* vp)
                  void* GetBaseAddr() const
                  void* GetBreakval() const
            TDirectory* GetDirectory() const
                  Int_t GetFd() const
                  void* GetMmallocDesc() const
            const char* GetName() const
                  Int_t GetSize() const
            const char* GetOption() const
            const char* GetTitle() const
               TMapRec* GetFirst() const
               TMapRec* GetLast() const
                 Bool_t IsWritable() const
                  void* OrgAddress(void* addr) const
               TObject* Remove(TObject* obj)
               TObject* Remove(const char* name)
              TMapFile* WhichMapFile(void* addr)
                TClass* Class()
                TClass* IsA() const
                   void ShowMembers(TMemberInspector& insp, char* parent)
                   void Streamer(TBuffer& b)
                   void StreamerNVirtual(TBuffer& b)

Author: Fons Rademakers 08/07/97
Last update: root/base:$Name: $:$Id: TMapFile.cxx,v 1.17 2005/06/23 06:24:27 brun Exp $
Copyright (C) 1995-2000, Rene Brun and Fons Rademakers. *