Tekkotsu Homepage
Demos
Overview
Downloads
Dev. Resources
Reference
Credits

WorldStatePool Class Reference

#include <WorldStatePool.h>

Inheritance diagram for WorldStatePool:

List of all members.


Detailed Description

holds multiple instances of WorldState, allows one process to be updating while another is reading

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 Types

enum  status_t { SENSORS_APPLIED = 1<<0, FEEDBACK_APPLIED = 1<<1 }
 flags for the status field on each WriteRequest -- tracks partial completion when multiple writers are involved More...

Public Member Functions

 WorldStatePool ()
 constructor
WorldStatePool::UpdateInfoisUnread (const RCRegion &msg, unsigned int curFrameNumber, unsigned int &lastFrameNumber, bool haveFeedback, bool motionOverride)
 returns true if the process should call read (i.e. msg has new or unprocessed data (such as motion needs to supply feedback))
bool read (const UpdateInfo &info, WriteRequest &wsw, bool feedbackGenerated, bool zeroPIDFeedback, const PostureEngine *feedback=NULL)
 takes a sensor update from the simulator/system, updates an entry in the pool with the new information
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()

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
SemaphoreManager::semid_t complete [NUM_STATES]
 this semaphore is set to positive value when writing begins, and then lowered to zero when complete
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

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...
WorldStatePooloperator= (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
 common base class for ReadRequest or WriteRequest More...
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 206 of file WorldStatePool.h.


Member Enumeration Documentation

flags for the status field on each WriteRequest -- tracks partial completion when multiple writers are involved

Enumerator:
SENSORS_APPLIED  bit flag signals sensor data has been applied to the write target
FEEDBACK_APPLIED  bit flag signals motion feedback has been applied to the write target (only required if feedback is being generated)

Definition at line 135 of file WorldStatePool.h.


Constructor & Destructor Documentation

WorldStatePool::WorldStatePool (  ) 

constructor

Definition at line 14 of file WorldStatePool.cc.

WorldStatePool::WorldStatePool ( const WorldStatePool  )  [private]

this shouldn't be called...


Member Function Documentation

WorldStatePool::UpdateInfo * WorldStatePool::isUnread ( const RCRegion msg,
unsigned int  curFrameNumber,
unsigned int &  lastFrameNumber,
bool  haveFeedback,
bool  motionOverride 
)

returns true if the process should call 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 incoming message to test
curFrameNumber the most recent frame number sent, i.e. SharedGlobals::MotionSimConfig::frameNumber
[out] lastFrameNumber if the incoming frame is already complete (no need to read), then the frame's number will be assigned here
haveFeedback you should pass true if motion feedback can be provided to read() (note the feedback doesn't necessarily need to be available right now, just if the call to read is necessary)
motionOverride true if motion feedback overrides sensor data (i.e SharedGlobals::MotionSimConfig::override)
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 119 of file WorldStatePool.cc.

bool WorldStatePool::read ( const UpdateInfo info,
WriteRequest wsw,
bool  feedbackGenerated,
bool  zeroPIDFeedback,
const PostureEngine feedback = NULL 
)

takes a sensor update from the simulator/system, updates an entry in the pool with the new information

If isUnread() returns non-NULL, you should acquire a WriteRequest, and check that it succeeds, is current, and is still incomplete, before calling read()

Parameters:
info the info structure returned by isUnread
wsw the WriteRequest aquired before calling read (yes, you should submit a WriteRequest for info.frameNumber between isUnread() and read())
feedbackGenerated pass true if feedback will be generated by a caller to read() -- doesn't need to be this process, but a process.
zeroPIDFeedback pass true if sensor data should override motion feedback for joints with 0's for PID control (i.e. SharedGlobals::MotionSimConfig::zeroPIDFeedback)
feedback pointer to actual motion feedback, or NULL if not available in this process (weight values of feedback are ignored, assumes all values are valid)

Definition at line 154 of file WorldStatePool.cc.

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

Implements Resource.

Definition at line 183 of file WorldStatePool.h.

Referenced by doUseResource().

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

Implements Resource.

Definition at line 185 of file WorldStatePool.h.

Referenced by doReleaseResource().

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 34 of file WorldStatePool.cc.

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 60 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 211 of file WorldStatePool.h.

Referenced by read().

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

called when access to an entry for reading is requested

Definition at line 287 of file WorldStatePool.cc.

Referenced by doUseResource().

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

called when an read access to an entry is complete

Definition at line 336 of file WorldStatePool.cc.

Referenced by doReleaseResource().

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

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

Definition at line 342 of file WorldStatePool.cc.

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

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 221 of file WorldStatePool.h.

Referenced by getCurrentWriteState(), and isUnread().

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 350 of file WorldStatePool.cc.

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 387 of file WorldStatePool.cc.

Referenced by doUseResource().

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

called when an write access to an entry is complete

Definition at line 428 of file WorldStatePool.cc.

Referenced by doReleaseResource(), and getCurrentWriteState().

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

this shouldn't be called...


Member Data Documentation

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

number of buffers to set up

Definition at line 203 of file WorldStatePool.h.

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

Definition at line 208 of file WorldStatePool.h.

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

entries to hand out

Definition at line 230 of file WorldStatePool.h.

Referenced by getCurrentReadState(), and getCurrentWriteState().

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 232 of file WorldStatePool.h.

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

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

flag set when a reader is blocking for writing to finish, until read is satisified

Definition at line 234 of file WorldStatePool.h.

Referenced by doneReadingState(), getCurrentReadState(), selectWriteState(), and WorldStatePool().

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

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)

Definition at line 236 of file WorldStatePool.h.

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

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

the status is intended as a bitfield to support communication between writers if they need to cooperatively fill out an entry

The value is set to 0 before handing out to a writer with a new frame number

Definition at line 239 of file WorldStatePool.h.

Referenced by doReleaseResource(), doUseResource(), getCurrentWriteState(), and WorldStatePool().

this semaphore is set to positive value when writing begins, and then lowered to zero when complete

A semaphore is used on "normal" systems because the MutexLock also implies a thread lock, which we actually don't want in this case because a different thread may complete the entry than the one which started it. Since Aperios does not allow multithreading, we don't have to worry about it there.

As an aside, we could use this to store writing, but that would only be feasible if Aperios gave us semaphores. Bah.

Definition at line 254 of file WorldStatePool.h.

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

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

locks to be acquired before handing out corresponding states entry for writing

Definition at line 258 of file WorldStatePool.h.

Referenced by doneWritingState(), and getCurrentWriteState().

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

lock on WorldStatePool's own members

Definition at line 260 of file WorldStatePool.h.

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


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

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