Tekkotsu: WorldStatePool Class Reference

Use the AutoGetReadState and AutoGetWriteState to access individual WorldState entries... their constructors and destructors allow WorldStatePool to keep track of which entries are in use.

When a state wants to write, it is given the oldest unused entry to write into. During writing, other accessors can read the newest (complete) entry, or concurrently write into a different entry (in case they don't want to wait for the other process to finish).

A global lock (lock) is used while choosing an entry, and individual locks (writeLocks) are used while writing into entries (to easily allow readers to block on the lock until writing is done)

One point of trickiness is that entries being written are moved to the end of the list when the writing begins, not when it is complete. Readers can always scan backwards in the list to find the newest entries, but writers must check the end to see if newer (or equivalent) frames are already in progress, as well as the beginning to find the oldest unreferenced.

When a writer tries to access an entry, and another writer is already processing that frame, if blocking is set then the writer will given that entry once the original is done with it (so check your frame index when you receive it so you can tell if it was already processed). If blocking is *not* set, then you will get a separate entry with no indication another process is also working on the same frame.

Definition at line 42 of file WorldStatePool.h.


Public Member Functions
	WorldStatePool ()
	constructor
WorldStatePool::UpdateInfo *	isUnread (OSensorFrameVectorData &msg, unsigned int &lastFrameNumber)
	returns true if the process should call WorldState::read (i.e. msg has new or unprocessed data (such as motion needs to supply feedback))
virtual void	useResource (Data &d)
	processes a request, passed as either a ReadRequest or WriteRequest, to access an entry in the pool
virtual void	releaseResource (Data &d)
	completes access to an entry in the pool, you must pass the same request instance here which you originally passed to useResource()
void	doUseResource (Data &d)
	does the actual work of useResource()
void	doReleaseResource (Data &d)
	does the actual work of releaseResource()
void	InitAccess ()
	registers stateLookupMap with WorldState::setWorldStateLookup()
Protected Types
typedef ListMemBuf< unsigned int, NUM_STATES >	order_t
	shorthand for the type of order
Protected Member Functions
unsigned int	getCurrentReadState (WorldState *&tgt, bool block)
	called when access to an entry for reading is requested
void	doneReadingState (unsigned int i)
	called when an read access to an entry is complete
bool	isComplete (unsigned int idx) const
	returns true if the specified element of states has been marked completed
unsigned int	selectWriteState (unsigned int frame, bool block) const
	returns index of buffer in states to use for write request
unsigned int	selectWriteState (unsigned int frame, bool block, order_t::index_t &idx) const
	returns index of buffer in states to use for write request, stores index of corresponding entry of order in idx
unsigned int	getCurrentWriteState (WorldState *&tgt, unsigned int frame, bool block)
	called when access to an entry for writing is requested
void	doneWritingState (unsigned int i, bool completed)
	called when an write access to an entry is complete
Static Protected Member Functions
static bool	isZeroPID (WorldState *s, unsigned int i)
	shorthand to test if all three P, I, and D values are 0 for the specified joint index (relative to 0, not PIDJointOffset)
Protected Attributes
order_t	order
	indicies of entries, in the order they were written (i.e. corresponding value in frames should be monotonically increasing)
WorldState	states [NUM_STATES]
	entries to hand out
unsigned int	frames [NUM_STATES]
	serial numbers of corresponding entries in states, set when writing begins, should be monotonically increasing relative to order (i.e. if you run through order and look at corresponding values in frames, should be monotonically increasing serial numbers)
unsigned int	reading [NUM_STATES]
	flag set when a reader is blocking for writing to finish, until read is satisified
unsigned int	writing [NUM_STATES]
	count of writers in line for access (occurs when a writer is blocking on another writer of the same frame, or no other frames are free)
unsigned int	status [NUM_STATES]
	the status is intended as a bitfield to support communication between writers if they need to cooperatively fill out an entry
MutexLock< ProcessID::NumProcesses >	complete [NUM_STATES]
	this lock indicates/controls whether the state is available for reading
MutexLock< ProcessID::NumProcesses >	writeLocks [NUM_STATES]
	locks to be acquired before handing out corresponding states entry for writing
MutexLock< ProcessID::NumProcesses >	lock
	lock on WorldStatePool's own members
WorldState *	stateLookupMap [ProcessID::NumProcesses]
	the current state in use by each process
Static Protected Attributes
static const unsigned int	NUM_STATES = WORLDSTATEPOOL_NUM_STATES
	number of buffers to set up
Private Member Functions
	WorldStatePool (const WorldStatePool &)
	this shouldn't be called...
WorldStatePool &	operator= (const WorldStatePool &)
	this shouldn't be called...
Classes
class	ReadRequest
	retrieves the current WorldState entry, and through it's destructor, marks the entry available again when it goes out of scope More...
class	Request
class	UpdateInfo
	returned by isUnread containing information parsed from the incoming message More...
class	WriteRequest
	retrieves the current WorldState entry, and through it's destructor, marks the entry available again when it goes out of scope More...

Member Typedef Documentation

typedef ListMemBuf<unsigned int, NUM_STATES> WorldStatePool::order_t [protected]

shorthand for the type of order

Definition at line 205 of file WorldStatePool.h.

Constructor & Destructor Documentation

WorldStatePool::WorldStatePool ( )

constructor

Definition at line 13 of file WorldStatePool.cc.

WorldStatePool::WorldStatePool ( const WorldStatePool & ) [private]

this shouldn't be called...

Member Function Documentation

void WorldStatePool::doneReadingState ( unsigned int i ) [protected]

called when an read access to an entry is complete

Definition at line 319 of file WorldStatePool.cc.

Referenced by doReleaseResource().

void WorldStatePool::doneWritingState	(	unsigned int	i,
		bool	completed
	)			`[protected]`

called when an write access to an entry is complete

Definition at line 411 of file WorldStatePool.cc.

Referenced by doReleaseResource(), and getCurrentWriteState().

void WorldStatePool::doReleaseResource ( Data & d )

does the actual work of releaseResource()

this is split off as a non-virtual function to avoid some process identity issues that occur with virtual functions under Aperios

Definition at line 59 of file WorldStatePool.cc.

void WorldStatePool::doUseResource ( Data & d )

does the actual work of useResource()

this is split off as a non-virtual function to avoid some process identity issues that occur with virtual functions under Aperios

Definition at line 33 of file WorldStatePool.cc.

unsigned int WorldStatePool::getCurrentReadState	(	WorldState *&	tgt,
		bool	block
	)			`[protected]`

called when access to an entry for reading is requested

Definition at line 281 of file WorldStatePool.cc.

Referenced by doUseResource().

unsigned int WorldStatePool::getCurrentWriteState	(	WorldState *&	tgt,
		unsigned int	frame,
		bool	block
	)			`[protected]`

called when access to an entry for writing is requested

Definition at line 370 of file WorldStatePool.cc.

Referenced by doUseResource().

void WorldStatePool::InitAccess ( ) [inline]

registers stateLookupMap with WorldState::setWorldStateLookup()

Definition at line 197 of file WorldStatePool.h.

bool WorldStatePool::isComplete ( unsigned int idx ) const [protected]

returns true if the specified element of states has been marked completed

Definition at line 325 of file WorldStatePool.cc.

Referenced by doneWritingState(), doUseResource(), getCurrentReadState(), and isUnread().

WorldStatePool::UpdateInfo * WorldStatePool::isUnread	(	OSensorFrameVectorData &	msg,
		unsigned int &	lastFrameNumber
	)

returns true if the process should call WorldState::read (i.e. msg has new or unprocessed data (such as motion needs to supply feedback))

only one call to this can be made at a time per process (not threadsafe, but is multi-process safe)

Parameters:

	msg	the incoming sensor data from the system -- should be const, but accessor functions from Sony aren't marked const themselves :-/
`[out]`	lastFrameNumber	if the incoming frame is already complete (no need to read), then the frame's number will be assigned here

Returns:: returns a static UpdateInfo structure (to be passed to read()) if the message is unread, otherwise returns NULL. The structure is static -- DO NOT DELETE IT

Definition at line 93 of file WorldStatePool.cc.

static bool WorldStatePool::isZeroPID	(	WorldState *	s,
		unsigned int	i
	)			`[inline, static, protected]`

shorthand to test if all three P, I, and D values are 0 for the specified joint index (relative to 0, not PIDJointOffset)

Definition at line 210 of file WorldStatePool.h.

WorldStatePool& WorldStatePool::operator= ( const WorldStatePool & ) [private]

this shouldn't be called...

virtual void WorldStatePool::releaseResource ( Data & d ) [inline, virtual]

completes access to an entry in the pool, you must pass the same request instance here which you originally passed to useResource()

Definition at line 184 of file WorldStatePool.h.

Referenced by doReleaseResource().

unsigned int WorldStatePool::selectWriteState	(	unsigned int	frame,
		bool	block,
		order_t::index_t &	idx
	)			const `[protected]`

returns index of buffer in states to use for write request, stores index of corresponding entry of order in idx

Definition at line 333 of file WorldStatePool.cc.

unsigned int WorldStatePool::selectWriteState	(	unsigned int	frame,
		bool	block
	)			const `[inline, protected]`

returns index of buffer in states to use for write request

Definition at line 220 of file WorldStatePool.h.

Referenced by getCurrentWriteState(), and isUnread().

virtual void WorldStatePool::useResource ( Data & d ) [inline, virtual]

processes a request, passed as either a ReadRequest or WriteRequest, to access an entry in the pool

Definition at line 182 of file WorldStatePool.h.

Referenced by doUseResource().

Member Data Documentation

MutexLock<ProcessID::NumProcesses> WorldStatePool::complete[NUM_STATES] [protected]

this lock indicates/controls whether the state is available for reading

The lock is set before handing out to a writer with a new frame number, and released when a writer has marked the entry complete (via the WriteRequest upon releaseResource())

Definition at line 243 of file WorldStatePool.h.

Referenced by doneWritingState(), getCurrentReadState(), getCurrentWriteState(), isComplete(), and WorldStatePool().

unsigned int WorldStatePool::frames[NUM_STATES] [protected]

serial numbers of corresponding entries in states, set when writing begins, should be monotonically increasing relative to order (i.e. if you run through order and look at corresponding values in frames, should be monotonically increasing serial numbers)

Definition at line 231 of file WorldStatePool.h.

Referenced by getCurrentWriteState(), isUnread(), selectWriteState(), and WorldStatePool().

MutexLock<ProcessID::NumProcesses> WorldStatePool::lock [protected]

lock on WorldStatePool's own members

Definition at line 259 of file WorldStatePool.h.

Referenced by doneReadingState(), doneWritingState(), getCurrentReadState(), and getCurrentWriteState().

const unsigned int WorldStatePool::NUM_STATES = WORLDSTATEPOOL_NUM_STATES [static, protected]

number of buffers to set up

Definition at line 202 of file WorldStatePool.h.

order_t WorldStatePool::order [protected]

indicies of entries, in the order they were written (i.e. corresponding value in frames should be monotonically increasing)

Definition at line 207 of file WorldStatePool.h.