ROOT logo
ROOT » IO » IO » TMapFile

class TMapFile: public TObject


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).


Function Members (Methods)

public:
virtual~TMapFile()
voidTObject::AbstractMethod(const char* method) const
voidAdd(const TObject* obj, const char* name = "")
virtual voidTObject::AppendPad(Option_t* option = "")
virtual voidBrowse(TBrowser* b)
Bool_tcd(const char* path = 0)
static TClass*Class()
virtual const char*TObject::ClassName() const
virtual voidTObject::Clear(Option_t* = "")
virtual TObject*TObject::Clone(const char* newname = "") const
voidClose(Option_t* option = "")
virtual Int_tTObject::Compare(const TObject* obj) const
virtual voidTObject::Copy(TObject& object) const
static TMapFile*Create(const char* name, Option_t* option = "READ", Int_t size = kDefaultMapSize, const char* title = "")
virtual voidTObject::Delete(Option_t* option = "")MENU
virtual Int_tTObject::DistancetoPrimitive(Int_t px, Int_t py)
virtual voidTObject::Draw(Option_t* option = "")
virtual voidTObject::DrawClass() constMENU
virtual TObject*TObject::DrawClone(Option_t* option = "") constMENU
virtual voidTObject::Dump() constMENU
virtual voidTObject::Error(const char* method, const char* msgfmt) const
virtual voidTObject::Execute(const char* method, const char* params, Int_t* error = 0)
virtual voidTObject::Execute(TMethod* method, TObjArray* params, Int_t* error = 0)
virtual voidTObject::ExecuteEvent(Int_t event, Int_t px, Int_t py)
virtual voidTObject::Fatal(const char* method, const char* msgfmt) const
virtual TObject*TObject::FindObject(const char* name) const
virtual TObject*TObject::FindObject(const TObject* obj) const
TObject*Get(const char* name, TObject* retObj = 0)
void*GetBaseAddr() const
void*GetBreakval() const
TDirectory*GetDirectory() const
virtual Option_t*TObject::GetDrawOption() const
static Long_tTObject::GetDtorOnly()
Int_tGetFd() const
TMapRec*GetFirst() const
virtual const char*TObject::GetIconName() const
TMapRec*GetLast() const
void*GetMmallocDesc() const
virtual const char*GetName() const
virtual char*TObject::GetObjectInfo(Int_t px, Int_t py) const
static Bool_tTObject::GetObjectStat()
virtual const char*GetOption() const
Int_tGetSize() const
virtual const char*GetTitle() const
virtual UInt_tTObject::GetUniqueID() const
virtual Bool_tTObject::HandleTimer(TTimer* timer)
virtual ULong_tTObject::Hash() const
virtual voidTObject::Info(const char* method, const char* msgfmt) const
virtual Bool_tTObject::InheritsFrom(const char* classname) const
virtual Bool_tTObject::InheritsFrom(const TClass* cl) const
virtual voidTObject::Inspect() constMENU
voidTObject::InvertBit(UInt_t f)
virtual TClass*IsA() const
virtual Bool_tTObject::IsEqual(const TObject* obj) const
virtual Bool_tIsFolder() const
Bool_tTObject::IsOnHeap() const
virtual Bool_tTObject::IsSortable() const
Bool_tIsWritable() const
Bool_tTObject::IsZombie() const
virtual voidls(Option_t* option = "") const
voidTObject::MayNotUse(const char* method) const
virtual Bool_tTObject::Notify()
voidTObject::Obsolete(const char* method, const char* asOfVers, const char* removedFromVers) const
static voidoperator delete(void* vp)
static voidTObject::operator delete[](void* ptr)
static voidTObject::operator delete[](void* ptr, void* vp)
void*TObject::operator new(size_t sz)
void*TObject::operator new(size_t sz, void* vp)
void*TObject::operator new[](size_t sz)
void*TObject::operator new[](size_t sz, void* vp)
void*OrgAddress(void* addr) const
virtual voidTObject::Paint(Option_t* option = "")
virtual voidTObject::Pop()
virtual voidPrint(Option_t* option = "") const
virtual Int_tTObject::Read(const char* name)
virtual voidTObject::RecursiveRemove(TObject* obj)
TObject*Remove(TObject* obj)
TObject*Remove(const char* name)
voidRemoveAll()
voidTObject::ResetBit(UInt_t f)
virtual voidTObject::SaveAs(const char* filename = "", Option_t* option = "") constMENU
virtual voidTObject::SavePrimitive(ostream& out, Option_t* option = "")
voidTObject::SetBit(UInt_t f)
voidTObject::SetBit(UInt_t f, Bool_t set)
virtual voidTObject::SetDrawOption(Option_t* option = "")MENU
static voidTObject::SetDtorOnly(void* obj)
static voidSetMapAddress(Long_t addr)
static voidTObject::SetObjectStat(Bool_t stat)
virtual voidTObject::SetUniqueID(UInt_t uid)
virtual voidShowMembers(TMemberInspector&)
virtual voidStreamer(TBuffer&)
voidStreamerNVirtual(TBuffer& ClassDef_StreamerNVirtual_b)
virtual voidTObject::SysError(const char* method, const char* msgfmt) const
Bool_tTObject::TestBit(UInt_t f) const
Int_tTObject::TestBits(UInt_t f) const
voidUpdate(TObject* obj = 0)
virtual voidTObject::UseCurrentStyle()
virtual voidTObject::Warning(const char* method, const char* msgfmt) const
static TMapFile*WhichMapFile(void* addr)
virtual Int_tTObject::Write(const char* name = 0, Int_t option = 0, Int_t bufsize = 0)
virtual Int_tTObject::Write(const char* name = 0, Int_t option = 0, Int_t bufsize = 0) const
protected:
TMapFile()
TMapFile(const TMapFile& f, Long_t offset = 0)
TMapFile(const char* name, const char* title, Option_t* option, Int_t size, TMapFile*& newMapFile)
Int_tAcquireSemaphore()
voidCreateSemaphore(Int_t pid = 0)
voidDeleteSemaphore()
virtual voidTObject::DoError(int level, const char* location, const char* fmt, va_list va) const
TMapFile*FindShadowMapFile()
Int_tGetBestBuffer()
voidInitDirectory()
voidTObject::MakeZombie()
static void*MapToAddress()
voidoperator=(const TMapFile& rhs)
Int_tReleaseSemaphore()
TObject*Remove(TObject* obj, Bool_t lock)
TObject*Remove(const char* name, Bool_t lock)
voidSumBuffer(Int_t bufsize)

Data Members

public:
enum { kDefaultMapSize
};
enum TObject::EStatusBits { kCanDelete
kMustCleanup
kObjInCanvas
kIsReferenced
kHasUUID
kCannotPick
kNoContextMenu
kInvalidObject
};
enum TObject::[unnamed] { kIsOnHeap
kNotDeleted
kZombie
kBitMask
kSingleKey
kOverwrite
kWriteDelete
};
private:
ULong_tfBaseAddrBase address of mapped memory region
TList*fBrowseListList of KeyMapFile objects
TDirectory*fDirectoryPointer to directory associated to this mapfile
Int_tfFdDescriptor of mapped file
TMapRec*fFirstList of streamed objects is shared memory
TObject*fGettingDon't deadlock in update mode, when from Get() Add() is called
TMapRec*fLastLast object in list of shared objects
void*fMmallocDescPointer to mmalloc descriptor
char*fNameName of mapped file
Long_tfOffsetOffset in bytes for region mapped by reader
char*fOptionDirectory creation options
Int_tfSemaphoreModification semaphore (or getpid() for WIN32)
Int_tfSizeOriginal start size of memory mapped region
Double_tfSum2BufferSum of squares of buffer sizes of objects written so far
Double_tfSumBufferSum of buffer sizes of objects written sofar
char*fTitleTitle of mapped file
Int_tfVersionROOT version (or -1 for shadow map file)
Bool_tfWritableTRUE if mapped file opened in RDWR mode
Int_tfWrittenNumber of objects written sofar
static Long_tfgMapAddressMap to this address, set address via SetMapAddress()
static void*fgMmallocDescUsed in Close() and operator delete()
ULong_tfhSemaphoreHANDLE of WIN32 Mutex object to implement semaphore

Class Charts

Inheritance Inherited Members Includes Libraries
Class Charts

Function documentation

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 = 0)
 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 = 0)
 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* retObj = 0)
 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_t pid = 0)
 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* option = "") 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 = 0)
 Cd to associated directory,
void ls(Option_t* option = "") 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 = "READ", Int_t size = kDefaultMapSize, 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.
void operator delete(void* vp)
 Need special "operator delete" in which we close the shared memory.
 This has to be done after the dtor chain has been finished.
void * GetBreakval() const
TMapFile * WhichMapFile(void* addr)
void operator=(const TMapFile& rhs)
TObject * Remove(TObject* obj, Bool_t lock)
TObject * Remove(const char* name, Bool_t lock)
void * GetBaseAddr() const
{ return (void *)fBaseAddr; }
TDirectory * GetDirectory() const
{return fDirectory;}
Int_t GetFd() const
{ return fFd; }
void * GetMmallocDesc() const
{ return fMmallocDesc; }
const char * GetName() const
{ return fName; }
Int_t GetSize() const
{ return fSize; }
const char * GetOption() const
{ return fOption; }
const char * GetTitle() const
{ return fTitle; }
TMapRec * GetFirst() const
{ return (TMapRec*)((Long_t) fFirst + fOffset); }
TMapRec * GetLast() const
{ return (TMapRec*)((Long_t) fLast + fOffset); }
Bool_t IsWritable() const
{ return fWritable; }
void * OrgAddress(void* addr) const
{ return (void *)((Long_t)addr - fOffset); }