RCRegion Class Reference

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

#include <RCRegion.h>

---

Detailed Description

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

Definition at line 61 of file RCRegion.h.

List of all members.

Classes
struct	Identifier
	contains all information needed to attach this region from a different process More...
Public Types
enum	ConflictResolutionStrategy { RENAME, REPLACE, EXIT }
	Different methods of handling regions with conflicting keys. More...
typedef std::map< key_t, 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)
	RCRegion (const std::string &, size_t sz)
	constructor, name isn't used for sysv-style shared memory (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 Identifier &	ID () 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 RCRegion *	attach (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
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
void	init (size_t sz, key_t sug_key, 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 Thread::Lock &	getStaticLock ()
	intializes and returns staticLock
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::RENAME
	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 Thread::Lock *	staticLock = 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 = 1024
	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
RCRegion &	operator= (const RCRegion &r)
	don't call

---

Member Typedef Documentation

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

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

Definition at line 148 of file RCRegion.h.

---

Member Enumeration Documentation

enum RCRegion::ConflictResolutionStrategy

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 171 of file RCRegion.h.

---

Constructor & Destructor Documentation

RCRegion::RCRegion

(

size_t

sz

)

[explicit]

constructor (OPEN-R compatability)

Definition at line 102 of file RCRegion.h.

Referenced by attach().

RCRegion::RCRegion	(	const std::string &	,
		size_t	sz
	)

constructor, name isn't used for sysv-style shared memory (not OPEN-R compatable)

could hash the name to generate key...?

Definition at line 107 of file RCRegion.h.

RCRegion::RCRegion

(

const Identifier &

rid

)

[protected]

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

Definition at line 186 of file RCRegion.h.

RCRegion::~RCRegion

(

)

[protected]

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

Definition at line 278 of file RCRegion.cc.

RCRegion::RCRegion

(

const RCRegion &

r

)

[private]

don't call

---

Member Function Documentation

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 199 of file RCRegion.cc.

void RCRegion::AddReference

(

)

adds a reference from the current process

Definition at line 77 of file RCRegion.cc.

Referenced by init(), BehaviorBase::MonitorMotion::monitor(), 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 170 of file RCRegion.cc.

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

RCRegion * RCRegion::attach

(

const Identifier &

rid

)

[static]

requests that a specified RCRegion be loaded into the current process's memory space

Definition at line 65 of file RCRegion.cc.

Referenced by MessageQueue< MAX_UNREAD, MAX_RECEIVERS, MAX_SENDERS >::markRead(), RegionRegistry< MAX_REGIONS, NAME_LEN >::operator[](), MessageQueue< MAX_UNREAD, MAX_RECEIVERS, MAX_SENDERS >::peekMessage(), MessageQueue< MAX_UNREAD, MAX_RECEIVERS, MAX_SENDERS >::readMessage(), RegionRegistry< MAX_REGIONS, NAME_LEN >::registerRegion(), MessageQueue< MAX_UNREAD, MAX_RECEIVERS, MAX_SENDERS >::removeReceiver(), MessageQueue< MAX_UNREAD, MAX_RECEIVERS, MAX_SENDERS >::sendMessage(), and MessageQueue< MAX_UNREAD, MAX_RECEIVERS, MAX_SENDERS >::~MessageQueue().

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 269 of file RCRegion.cc.

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 258 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 266 of file RCRegion.cc.

char* RCRegion::Base

(

)

const

the pointer to the shared memory region

Definition at line 130 of file RCRegion.h.

Referenced by IPCEventTranslator::bufferRequest(), SharedObjectBase::data(), SoundManager::loadBuffer(), SoundManager::play(), IPCEventTranslator::post(), SoundManager::ProcessMsg(), MotionManager::processMsg(), SoundManager::release(), SoundManager::resumePlay(), and SharedObject< UPennWalkMC >::SharedObject().

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 286 of file RCRegion.cc.

Referenced by init(), and RemoveReference().

void RCRegion::faultShutdown

(

)

[static]

try to unload all regions in a clean manner

Definition at line 220 of file RCRegion.cc.

static ConflictResolutionStrategy RCRegion::getConflictResolution

(

)

[static]

returns conflictStrategy

Definition at line 178 of file RCRegion.h.

static bool RCRegion::getMultiprocess

(

)

[static]

returns multiprocess

Definition at line 181 of file RCRegion.h.

static key_t RCRegion::getNextKey

(

)

[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 133 of file RCRegion.h.

Thread::Lock & RCRegion::getStaticLock

(

)

[static, protected]

intializes and returns staticLock

Definition at line 295 of file RCRegion.cc.

Referenced by aboutToFork(), AddReference(), AddSharedReference(), attach(), attachedAdvance(), attachedBegin(), faultShutdown(), init(), RemoveReference(), RemoveSharedReference(), and ~RCRegion().

const Identifier& RCRegion::ID

(

)

const

returns the identifier of this region

Definition at line 134 of file RCRegion.h.

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

void RCRegion::init	(	size_t	sz,
		key_t	sug_key,
		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 303 of file RCRegion.cc.

Referenced by RCRegion().

static unsigned int RCRegion::NumberOfAttach

(

)

[static]

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

Definition at line 153 of file RCRegion.h.

int RCRegion::NumberOfLocalReference

(

)

const

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

Definition at line 137 of file RCRegion.h.

int RCRegion::NumberOfReference

(

)

const

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

Definition at line 136 of file RCRegion.h.

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

RCRegion& RCRegion::operator=

(

const RCRegion &

r

)

[private]

don't call

void RCRegion::RemoveReference

(

)

removes a reference from the current process

Definition at line 88 of file RCRegion.cc.

Referenced by SoundManager::loadBuffer(), MessageQueue< MAX_UNREAD, MAX_RECEIVERS, MAX_SENDERS >::markRead(), SoundManager::play(), IPCEventTranslator::post(), BehaviorBase::MonitorMotion::processEvent(), SoundManager::ProcessMsg(), MessageReceiver::processNextMessage(), SoundManager::release(), MessageQueue< MAX_UNREAD, MAX_RECEIVERS, MAX_SENDERS >::removeReceiver(), SharedObject< UPennWalkMC >::removeRef(), SoundManager::resumePlay(), MessageQueue< MAX_UNREAD, MAX_RECEIVERS, MAX_SENDERS >::sendMessage(), MessageQueue< MAX_UNREAD, MAX_RECEIVERS, MAX_SENDERS >::~MessageQueue(), and BehaviorBase::MonitorMotion::~MonitorMotion().

void RCRegion::RemoveSharedReference

(

)

removes a reference which is held by another shared memory region

Definition at line 180 of file RCRegion.cc.

Referenced by MessageQueue< MAX_UNREAD, MAX_RECEIVERS, MAX_SENDERS >::markRead(), MessageQueue< MAX_UNREAD, MAX_RECEIVERS, MAX_SENDERS >::readMessage(), MessageQueue< MAX_UNREAD, MAX_RECEIVERS, MAX_SENDERS >::removeReceiver(), MessageQueue< MAX_UNREAD, MAX_RECEIVERS, MAX_SENDERS >::sendMessage(), and MessageQueue< MAX_UNREAD, MAX_RECEIVERS, MAX_SENDERS >::~MessageQueue().

static void RCRegion::setConflictResolution

(

ConflictResolutionStrategy

crs

)

[static]

sets conflictStrategy

Definition at line 177 of file RCRegion.h.

static void RCRegion::setMultiprocess

(

bool

mp

)

[static]

sets multiprocess

Definition at line 180 of file RCRegion.h.

static void RCRegion::setNextKey

(

key_t

k

)

[static]

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

Definition at line 132 of file RCRegion.h.

size_t RCRegion::Size

(

)

const

the size of the shared memory region

Definition at line 131 of file RCRegion.h.

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

---

Member Data Documentation

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 193 of file RCRegion.h.

Referenced by calcRealSize().

RCRegion::attachedRegions_t RCRegion::attachedRegions [static, protected]

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

Definition at line 231 of file RCRegion.h.

Referenced by aboutToFork(), attach(), attachedAdvance(), attachedBegin(), attachedEnd(), faultShutdown(), init(), NumberOfAttach(), RemoveReference(), and ~RCRegion().

char* RCRegion::base [protected]

pointer to the region's user data

Definition at line 234 of file RCRegion.h.

Referenced by Base(), init(), RemoveReference(), and ~RCRegion().

RCRegion::ConflictResolutionStrategy RCRegion::conflictStrategy = RCRegion::RENAME [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 222 of file RCRegion.h.

Referenced by getConflictResolution(), init(), and setConflictResolution().

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 195 of file RCRegion.h.

Referenced by calcRealSize(), and init().

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 233 of file RCRegion.h.

Referenced by ID().

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 224 of file RCRegion.h.

Referenced by faultShutdown(), and 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 226 of file RCRegion.h.

Referenced by getMultiprocess(), RemoveReference(), and setMultiprocess().

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

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

Definition at line 230 of file RCRegion.h.

Referenced by getNextKey(), init(), RCRegion(), and setNextKey().

unsigned int* RCRegion::references [protected]

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

Definition at line 235 of file RCRegion.h.

Referenced by AddReference(), AddSharedReference(), init(), NumberOfLocalReference(), NumberOfReference(), RemoveReference(), RemoveSharedReference(), and ~RCRegion().

Thread::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 228 of file RCRegion.h.

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

---

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

• RCRegion.h
• RCRegion.cc