Tekkotsu Homepage
Demos
Overview
Downloads
Dev. Resources
Reference
Credits

RCRegion Class Reference

#include <RCRegion.h>

List of all members.


Detailed Description

provides compatability with the OPEN-R type of the same name

Definition at line 60 of file RCRegion.h.


Public Types

enum  ConflictResolutionStrategy { RENAME, REPLACE, EXIT }
 Different methods of handling regions with conflicting keys. More...
typedef std::map< std::string,
RCRegion * > 
attachedRegions_t
 a map from the shared memory key type to the actual region structure

Public Member Functions

 RCRegion (size_t sz)
 constructor (OPEN-R compatability, name is autogenerated)
 RCRegion (const std::string &name, size_t sz)
 constructor, specify your own name for better debugging accountability (not OPEN-R compatable)
char * Base () const
 the pointer to the shared memory region
size_t Size () const
 the size of the shared memory region
const IdentifierID () const
 returns the identifier of this region
int NumberOfReference () const
 number of total references to this region, total of all processes
int NumberOfLocalReference () const
 number of references to the region from the current process (in the ProcessID threadgroup sense, not necessarily system-process)
void AddReference ()
 adds a reference from the current process
void RemoveReference ()
 removes a reference from the current process
void AddSharedReference ()
 adds a reference which is held by another shared memory region
void RemoveSharedReference ()
 removes a reference which is held by another shared memory region

Static Public Member Functions

static RCRegionattach (const Identifier &rid)
 requests that a specified RCRegion be loaded into the current process's memory space
static void setNextKey (key_t k)
 sets the next key to be used for automatic assignment to new regions
static key_t getNextKey ()
 return the next region serial number -- doesn't actually increment it though, repeated calls will return the same value until the value is actually used
static void aboutToFork (ProcessID::ProcessID_t newID)
 does housekeeping to mark the region as attached and the same number of references in the new process as well
static void faultShutdown ()
 try to unload all regions in a clean manner
static unsigned int NumberOfAttach ()
 returns the number of regions which are currently attached in the process
static
attachedRegions_t::const_iterator 
attachedBegin (bool threadSafe)
 Returns an iterator to the beginning of the attached regions mapping -- it->first is the key, it->second is the RCRegion*.
static
attachedRegions_t::const_iterator 
attachedEnd ()
 Returns an iterator to the end of the attached regions -- it->first is the key, it->second is the RCRegion*.
static void attachedAdvance (attachedRegions_t::const_iterator &it, int x=1)
 Increments the attached region iterator in a thread-safe way -- only use this if you previously passed 'true' to begin(), or are decrementing from end().
static void setConflictResolution (ConflictResolutionStrategy crs)
 sets conflictStrategy
static ConflictResolutionStrategy getConflictResolution ()
 returns conflictStrategy
static void setMultiprocess (bool mp)
 sets multiprocess
static bool getMultiprocess ()
 returns multiprocess

Static Public Attributes

static const unsigned int MAX_NAME_LEN = 64
 maximum guaranteed length for users' region names (might have a little leeway depending on process ID prefix or tmp path prefix)
static plist::Primitive
< std::string > 
shmRoot
 determines location of the file backing within file system
static plist::Primitive< bool > useUniqueMemoryRegions
 if true, prefixes region names with rootPID
static pid_t rootPID
 this is the pid of the original process, used for unique names of memory regions; pid_t is from sys/types.h

Protected Member Functions

 RCRegion (const Identifier &rid)
 this protected constructor is used for attaching regions previously created by another process (see attach())
 ~RCRegion ()
 prevents stack allocation -- needs to be heap allocated and reference counted
std::string getQualifiedName () const
 returns the qualified version of this region's key (see getQualifiedName(const std::string& key) )
int openRegion (int mode) const
 opens a region either in "pure" shared memory, or in file-backed shared memory, based on whether USE_UNBACKED_SHM is defined
bool unlinkRegion () const
 unlinks a region either in "pure" shared memory, or in file-backed shared memory, based on whether USE_UNBACKED_SHM is defined
void init (size_t sz, const std::string &name, bool create)
 initializes the region's information, either creating a new shared memory region or attempting to connect to a pre-existing one

Static Protected Member Functions

static unsigned int calcRealSize (unsigned int size)
 returns the size of the region to be allocated, given the size requested by the client
static ThreadNS::LockgetStaticLock ()
 intializes and returns staticLock
static std::string getQualifiedName (const std::string &key)
 wraps the region's key with a root path prefix and optionally a PID suffix (see useUniqueMemoryRegions and shmRoot)

Protected Attributes

Identifier id
 key values for the region, namely the system key type (either an integer or string depending on TEKKOTSU_SHM_STYLE) and the size of the region
char * base
 pointer to the region's user data
unsigned int * references
 pointer to the per-process reference counts (stored within the shared region!)

Static Protected Attributes

static const unsigned int align = sizeof(unsigned int)
 the alignment multiple of the extra space at the end of the region
static const unsigned int extra = sizeof(unsigned int)*(ProcessID::NumProcesses+1)
 the amount of space to leave at the end of the region for housekeeping (reference counts)
static ConflictResolutionStrategy conflictStrategy = RCRegion::REPLACE
 controls what to do about creating a region with a conflicting key (i.e. another region already exists with the same key)
static bool isFaultShutdown = false
 set to true if we are shutting down because of an error, and trying to unload shared regions to avoid leaking beyond program scope
static bool multiprocess = true
 set to false if the different "processes" are just threads (and thus the last process reference shouldn't actually trigger unlinking a region
static ThreadNS::LockstaticLock = NULL
 a lock over all static RCRegion members for the current process, must be obtained before changing reference counts or attaching/detaching regions
static key_t nextKey = 0
 serial number of next key -- starts at 1024 for TEKKOTSU_SHM_STYLE==SYSV_SHM, 0 for POSIX_SHM
static attachedRegions_t attachedRegions
 a mapping of key values to RCRegion pointers of the attached region

Private Member Functions

 RCRegion (const RCRegion &r)
 don't call
RCRegionoperator= (const RCRegion &r)
 don't call

Classes

struct  Identifier
 contains all information needed to attach this region from a different process More...

Member Typedef Documentation

typedef std::map<std::string,RCRegion*> RCRegion::attachedRegions_t

a map from the shared memory key type to the actual region structure

Definition at line 150 of file RCRegion.h.


Member Enumeration Documentation

Different methods of handling regions with conflicting keys.

Enumerator:
RENAME  try another key until we find one that works (better for SYSV, maybe not so smart for POSIX)
REPLACE  delete the other region and try again (better for POSIX, maybe not so smart for SYSV)
EXIT  go home and cry about it

Definition at line 170 of file RCRegion.h.


Constructor & Destructor Documentation

RCRegion::RCRegion ( size_t  sz  )  [inline, explicit]

constructor (OPEN-R compatability, name is autogenerated)

Definition at line 112 of file RCRegion.h.

Referenced by attach().

RCRegion::RCRegion ( const std::string &  name,
size_t  sz 
) [inline]

constructor, specify your own name for better debugging accountability (not OPEN-R compatable)

Definition at line 121 of file RCRegion.h.

RCRegion::RCRegion ( const Identifier rid  )  [inline, protected]

this protected constructor is used for attaching regions previously created by another process (see attach())

Definition at line 185 of file RCRegion.h.

RCRegion::~RCRegion (  )  [protected]

prevents stack allocation -- needs to be heap allocated and reference counted

Definition at line 275 of file RCRegion.cc.

RCRegion::RCRegion ( const RCRegion r  )  [private]

don't call


Member Function Documentation

size_t RCRegion::Size (  )  const [inline]

the size of the shared memory region

Definition at line 130 of file RCRegion.h.

Referenced by WorldStatePool::isUnread(), and SharedObject< UPennWalkMC >::SharedObject().

static void RCRegion::setNextKey ( key_t  k  )  [inline, static]

sets the next key to be used for automatic assignment to new regions

Definition at line 131 of file RCRegion.h.

static key_t RCRegion::getNextKey (  )  [inline, static]

return the next region serial number -- doesn't actually increment it though, repeated calls will return the same value until the value is actually used

Definition at line 132 of file RCRegion.h.

const Identifier& RCRegion::ID (  )  const [inline]

returns the identifier of this region

Definition at line 133 of file RCRegion.h.

Referenced by MessageQueue< MAX_UNREAD, MAX_RECEIVERS, MAX_SENDERS >::sendMessage(), and SharedObject< UPennWalkMC >::SharedObject().

int RCRegion::NumberOfReference (  )  const [inline]

number of total references to this region, total of all processes

Definition at line 135 of file RCRegion.h.

Referenced by SharedObject< UPennWalkMC >::removeRef().

int RCRegion::NumberOfLocalReference (  )  const [inline]

number of references to the region from the current process (in the ProcessID threadgroup sense, not necessarily system-process)

Definition at line 136 of file RCRegion.h.

void RCRegion::AddReference (  ) 

adds a reference from the current process

Definition at line 75 of file RCRegion.cc.

Referenced by SharedObjectBase::operator=(), SoundManager::ProcessMsg(), MotionManager::processMsg(), and SharedObjectBase::SharedObjectBase().

void RCRegion::AddSharedReference (  ) 

adds a reference which is held by another shared memory region

Definition at line 167 of file RCRegion.cc.

Referenced by MessageQueue< MAX_UNREAD, MAX_RECEIVERS, MAX_SENDERS >::sendMessage().

void RCRegion::aboutToFork ( ProcessID::ProcessID_t  newID  )  [static]

does housekeeping to mark the region as attached and the same number of references in the new process as well

Definition at line 196 of file RCRegion.cc.

void RCRegion::faultShutdown (  )  [static]

try to unload all regions in a clean manner

Definition at line 217 of file RCRegion.cc.

static unsigned int RCRegion::NumberOfAttach (  )  [inline, static]

returns the number of regions which are currently attached in the process

Definition at line 152 of file RCRegion.h.

RCRegion::attachedRegions_t::const_iterator RCRegion::attachedBegin ( bool  threadSafe  )  [static]

Returns an iterator to the beginning of the attached regions mapping -- it->first is the key, it->second is the RCRegion*.

If you need thread-safety (i.e. another thread may attach/detach while you are iterating), pass true, and be sure to use attachedAdvance() to increment the iterator! This doesn't prevent other threads from attaching/detaching regions, it only prevents detaching the one you're on. When you're done with a thread-safe iterator, either attachedAdvance() it off the end, or manually call RemoveReference() on the iterator's final region

Definition at line 255 of file RCRegion.cc.

RCRegion::attachedRegions_t::const_iterator RCRegion::attachedEnd (  )  [static]

Returns an iterator to the end of the attached regions -- it->first is the key, it->second is the RCRegion*.

If you need thread-safety (i.e. another thread may attach/detach while you are iterating), be sure to use attachedAdvance() to decrement the iterator! This doesn't prevent other threads from attaching/detaching regions, it only prevents detaching the one you're on.

Definition at line 263 of file RCRegion.cc.

void RCRegion::attachedAdvance ( attachedRegions_t::const_iterator &  it,
int  x = 1 
) [static]

Increments the attached region iterator in a thread-safe way -- only use this if you previously passed 'true' to begin(), or are decrementing from end().

If you are using an iterator obtained without thread-safety, just increment it normally -- don't switch to this or it will screw up reference counting. If you insist on switching back and forth between thread-safe advance (this function) and normal iterator advancing, you will need to add a reference to the current iterator's region before calling this. When you're done, either advance off the end, or manually call RemoveReference() on the iterator's final region

Definition at line 266 of file RCRegion.cc.

static void RCRegion::setConflictResolution ( ConflictResolutionStrategy  crs  )  [inline, static]

sets conflictStrategy

Definition at line 176 of file RCRegion.h.

static ConflictResolutionStrategy RCRegion::getConflictResolution (  )  [inline, static]

returns conflictStrategy

Definition at line 177 of file RCRegion.h.

static void RCRegion::setMultiprocess ( bool  mp  )  [inline, static]

sets multiprocess

Definition at line 179 of file RCRegion.h.

static bool RCRegion::getMultiprocess (  )  [inline, static]

returns multiprocess

Definition at line 180 of file RCRegion.h.

unsigned int RCRegion::calcRealSize ( unsigned int  size  )  [static, protected]

returns the size of the region to be allocated, given the size requested by the client

Definition at line 283 of file RCRegion.cc.

Referenced by RemoveReference().

ThreadNS::Lock & RCRegion::getStaticLock (  )  [static, protected]

intializes and returns staticLock

Definition at line 292 of file RCRegion.cc.

Referenced by aboutToFork(), AddReference(), attach(), and RemoveReference().

std::string RCRegion::getQualifiedName (  )  const [inline, protected]

returns the qualified version of this region's key (see getQualifiedName(const std::string& key) )

Definition at line 206 of file RCRegion.h.

std::string RCRegion::getQualifiedName ( const std::string &  key  )  [static, protected]

wraps the region's key with a root path prefix and optionally a PID suffix (see useUniqueMemoryRegions and shmRoot)

Definition at line 380 of file RCRegion.cc.

int RCRegion::openRegion ( int  mode  )  const [protected]

opens a region either in "pure" shared memory, or in file-backed shared memory, based on whether USE_UNBACKED_SHM is defined

Definition at line 394 of file RCRegion.cc.

bool RCRegion::unlinkRegion (  )  const [protected]

unlinks a region either in "pure" shared memory, or in file-backed shared memory, based on whether USE_UNBACKED_SHM is defined

Definition at line 401 of file RCRegion.cc.

Referenced by RemoveReference().

void RCRegion::init ( size_t  sz,
const std::string &  name,
bool  create 
) [protected]

initializes the region's information, either creating a new shared memory region or attempting to connect to a pre-existing one

Definition at line 408 of file RCRegion.cc.

RCRegion& RCRegion::operator= ( const RCRegion r  )  [private]

don't call


Member Data Documentation

const unsigned int RCRegion::MAX_NAME_LEN = 64 [static]

maximum guaranteed length for users' region names (might have a little leeway depending on process ID prefix or tmp path prefix)

Definition at line 76 of file RCRegion.h.

Referenced by SharedObject< UPennWalkMC >::createRCRegion(), SoundManager::initRegion(), and RCRegion().

plist::Primitive< std::string > RCRegion::shmRoot [static]

determines location of the file backing within file system

Definition at line 87 of file RCRegion.h.

Referenced by getQualifiedName().

if true, prefixes region names with rootPID

Definition at line 89 of file RCRegion.h.

Referenced by getQualifiedName().

pid_t RCRegion::rootPID [static]

this is the pid of the original process, used for unique names of memory regions; pid_t is from sys/types.h

Definition at line 90 of file RCRegion.h.

Referenced by getQualifiedName().

const unsigned int RCRegion::align = sizeof(unsigned int) [static, protected]

the alignment multiple of the extra space at the end of the region

Definition at line 192 of file RCRegion.h.

const unsigned int RCRegion::extra = sizeof(unsigned int)*(ProcessID::NumProcesses+1) [static, protected]

the amount of space to leave at the end of the region for housekeeping (reference counts)

Definition at line 194 of file RCRegion.h.

RCRegion::ConflictResolutionStrategy RCRegion::conflictStrategy = RCRegion::REPLACE [static, protected]

controls what to do about creating a region with a conflicting key (i.e. another region already exists with the same key)

Definition at line 220 of file RCRegion.h.

bool RCRegion::isFaultShutdown = false [static, protected]

set to true if we are shutting down because of an error, and trying to unload shared regions to avoid leaking beyond program scope

Definition at line 222 of file RCRegion.h.

Referenced by RemoveReference().

bool RCRegion::multiprocess = true [static, protected]

set to false if the different "processes" are just threads (and thus the last process reference shouldn't actually trigger unlinking a region

Definition at line 224 of file RCRegion.h.

Referenced by RemoveReference().

ThreadNS::Lock * RCRegion::staticLock = NULL [static, protected]

a lock over all static RCRegion members for the current process, must be obtained before changing reference counts or attaching/detaching regions

Definition at line 226 of file RCRegion.h.

Referenced by aboutToFork(), getStaticLock(), and RemoveReference().

key_t RCRegion::nextKey = 0 [static, protected]

serial number of next key -- starts at 1024 for TEKKOTSU_SHM_STYLE==SYSV_SHM, 0 for POSIX_SHM

Definition at line 228 of file RCRegion.h.

a mapping of key values to RCRegion pointers of the attached region

Definition at line 229 of file RCRegion.h.

Referenced by aboutToFork(), attach(), and RemoveReference().

Identifier RCRegion::id [protected]

key values for the region, namely the system key type (either an integer or string depending on TEKKOTSU_SHM_STYLE) and the size of the region

Definition at line 231 of file RCRegion.h.

char* RCRegion::base [protected]

pointer to the region's user data

Definition at line 232 of file RCRegion.h.

Referenced by RemoveReference().

unsigned int* RCRegion::references [protected]

pointer to the per-process reference counts (stored within the shared region!)

Definition at line 233 of file RCRegion.h.

Referenced by AddReference(), and RemoveReference().


The documentation for this class was generated from the following files:

Tekkotsu v4.0
Generated Thu Nov 22 00:58:37 2007 by Doxygen 1.5.4