DtParallelTickManager Class Reference

Enables parallelism in the main thread. More...

Inheritance diagram for DtParallelTickManager:

Classes
class	CallbackInterface
	Interface for defining callbacks. More...
struct	ClassInfo

Public Types
enum	AccessType { EXCLUSIVE, SHARED, UNLOCKED, DEFERRED }
typedef boost::unordered_map < std::string, bool >	EnabledMap

Public Member Functions
	DtParallelTickManager (DtVrfSimOptionsInterface *options)
virtual	~DtParallelTickManager ()
virtual void	setCallbackQueue (DtVrfCallbackQueue *)
	Takes ownership.
virtual DtVrfCallbackQueue *	queue () const
	Access the callback queue object.
virtual void	clearDeferredJobs ()
	Clear out all deferred jobs from the various queues.
virtual bool	enabled (const std::string &, bool def) const
	Simple mechanism for controlling multiple parallel sections.
virtual bool	executeCommand (const std::string &, bool on)
	Execute a console command.
virtual void	printInfo (std::ostream &) const
	Print information about current state.
virtual void	setDeferJobs (bool)
	Enable/disable deferred jobs.
virtual ThreadLocalInfo &	threadLocalInfo ()
	ThreadLocalInfo (DtParallelTickManager *m)
DtParallelTickManager::AccessType	state () const
virtual void	flushQueue (bool useThisThread)
	Wait for all queued tasks to complete This function is called when you have added a bunch of tasks to the queue and need to make sure they are finished before proceeding.
virtual void	flushQueue ()
virtual bool	mainThreadWait () const
	Accessor/mutator for main thread participation in running callbacks.
virtual void	setMainThreadWait (bool)
virtual unsigned	maxSpinCount () const
	Accessor/mutator for number of times to spin on spinlock before yielding processor.
virtual void	setMaxSpinCount (unsigned)
virtual bool	active () const
	Accessor/mutator for the entire parallel mechanism.
virtual void	setActive (bool)
virtual void	addCallback (CallbackInterface *)
	Add callbacks to the queue.
virtual void	addCallback (CallbackInterface &)
virtual void	addCallback (CallbackInterface *, const std::string &tag, bool def=true)
virtual void	addCallback (CallbackInterface &, const std::string &tag, bool def=true)
void	addCallback (CallbackInterface *, const char *tag, bool def=true)
void	addCallback (CallbackInterface &, const char *tag, bool def=true)
template<typename Container >
void	addCallbacks (Container &cont)
template<typename Container >
void	addCallbacks (Container &cont, const std::string &tag, bool def=true)
template<typename Container >
void	addCallbacks (Container &cont, const char *tag, bool def=true)
virtual bool	lock ()
	Manipulate global mutex.
virtual bool	unlock ()
virtual bool	readLock ()
virtual bool	readUnlock ()
virtual bool	upgradeToWriter ()
virtual bool	downgradeToReader ()
virtual bool	changeAccess (AccessType from, AccessType to)

Private Types
typedef tbb::cache_aligned_allocator < ThreadLocalInfo * >	ThreadLocalAllocator
typedef tbb::enumerable_thread_specific < ThreadLocalInfo *, ThreadLocalAllocator, tbb::ets_key_per_instance >	ThreadLocalContainer
	DtCriticalSection, ThreadLocalAllocator> ThreadLocalContainer;.
typedef std::vector < DtCriticalSection * >	Stack

Private Member Functions
virtual void	executeDeferredJobs (AccessType access)
virtual void	flushDeferredJobs ()
void	push (DtCriticalSection &cs)
void	pop (DtCriticalSection &cs)

Static Private Member Functions
static void	RunJob (CallbackInterface *)
static void	RunJob (CallbackInterface &)

Private Attributes
tbb::atomic< int >	myAccessCount
ThreadLocalContainer	myThreadLocals
DtVrfSimOptionsInterface *	myOptions
DtVrfCallbackQueue *	myCallbackQueue
EnabledMap	myEnabledMap
bool	myWaitFlag
unsigned	myMaxSpinCount
bool	myDeferJobsFlag
boost::ptr_vector< ClassInfo >	myDeferredJobs
tbb::atomic< unsigned >	myDeferredJobCount
DtSubCommandManager *	myCommandManager
DtConsoleCommandOwner *	myCommandOwner
__itt_domain *	myLockITTDomain
__itt_string_handle *	mySharedLockEvent
__itt_string_handle *	myExclusiveLockEvent
__itt_string_handle *	mySharedAccessEvent
__itt_string_handle *	myExclusiveAccessEvent
__itt_string_handle *	myDeferredJobTask
Stack	myLocks

Friends
class	DtCriticalSection
enum	JobClass { JobClass_VRLINK, JobClass_MAX }
	Deferred Jobs is a mechanism for deferring work until a later time. More...
virtual void	configureDeferredJobClass (JobClass jobclass, AccessType access, unsigned maxConcurrent)
	Configure a job class.
virtual void	addDeferredJob (JobClass jobclass, const boost::function< void()> &callback)
	Add a deferred job.
virtual void	addVRLinkDeferredJob (const boost::function< void()> &callback)
	Convenience functions.

Detailed Description

Enables parallelism in the main thread.

This class wraps a mutex and a callback queue thread pool which are used to execute multiple functions in parallel in the sim main thread. The mutex protects the entire global state of VR-Forces.

There are two ways to execute a callback, normal (parallel) or serial. The normal method just executes the callback with no synchronization. If the callback needs to access any of the global VR-Forces state then it must use create a SerialScopeGuard around that section (just like a mutex scope lock). This will lock the global mutex and prevent any other threads from access the global state. The serial method locks the global mutex when the callback is called This means that all other threads accessing the global state will have to wait. A serial executed callback can use ParallelScopeGuard to unlock the global mutex around a section which does not access any global state.

By default DtVrfObjects are ticked in serial since they all access the global state. Individual actuators that have safe sections (like terrain intersections or feature queries) can then be modified as needed by inserting ParallelScopeGuards.

Users generally do not access this class directly, see DtCriticalSection.

Member Typedef Documentation

typedef boost::unordered_map<std::string, bool> DtParallelTickManager::EnabledMap

typedef tbb::cache_aligned_allocator<ThreadLocalInfo*> DtParallelTickManager::ThreadLocalAllocator

private

typedef tbb::enumerable_thread_specific< ThreadLocalInfo*, ThreadLocalAllocator, tbb::ets_key_per_instance> DtParallelTickManager::ThreadLocalContainer

private

DtCriticalSection, ThreadLocalAllocator> ThreadLocalContainer;.

typedef std::vector<DtCriticalSection*> DtParallelTickManager::Stack

private

Member Enumeration Documentation

enum DtParallelTickManager::AccessType

Enumerator:

EXCLUSIVE
SHARED
UNLOCKED
DEFERRED	Any job marked with deferred access will be run when the flushQueue call has run through all threaded items.

enum DtParallelTickManager::JobClass

Deferred Jobs is a mechanism for deferring work until a later time.

For example, the VRLink API is not thread safe, so sending messages and ticking VRLink components must be done in EXCLUSIVE mode. Since there should be no code accessing VRLink code when not in EXCLUSIVE mode, it is possible for another thread to call into VRLink if it can guarantee it is the only thread doing so. Adding a job to the JobClass_VRLINK job class will queue it to be executed by an arbitrary thread the next time that thread becomes SHARED. The system guarantees that only one thread at a time will try execute VRLink jobs. The max number of threads and the access mode in which jobs will be executed can be set by calling configureDeferredJobClass in order to setup custom job classes. Any jobs which are still queued after all components are ticked will be run in the main thread. Standard job classes. You can add your own as long as they are equal to or above JobClass_MAX in value.

Enumerator:

JobClass_VRLINK
JobClass_MAX

Constructor & Destructor Documentation

DtParallelTickManager::DtParallelTickManager ( DtVrfSimOptionsInterface *  options )

explicit

virtual DtParallelTickManager::~DtParallelTickManager ( )

virtual

Member Function Documentation

virtual void DtParallelTickManager::setCallbackQueue ( DtVrfCallbackQueue *  )

virtual

Takes ownership.

virtual DtVrfCallbackQueue* DtParallelTickManager::queue ( ) const

virtual

Access the callback queue object.

virtual void DtParallelTickManager::flushQueue ( bool  useThisThread )

virtual

Wait for all queued tasks to complete This function is called when you have added a bunch of tasks to the queue and need to make sure they are finished before proceeding.

Whether the calling thread waits or participates in calling the callbacks is controlled by the useThisThread parameter or DtVrfSimOptionsInterface::flushCallbackQueueInMainThread if not supplied.

virtual void DtParallelTickManager::flushQueue ( )

virtual

virtual void DtParallelTickManager::clearDeferredJobs ( )

virtual

Clear out all deferred jobs from the various queues.

virtual bool DtParallelTickManager::mainThreadWait ( ) const

virtual

Accessor/mutator for main thread participation in running callbacks.

virtual void DtParallelTickManager::setMainThreadWait ( bool  )

virtual

virtual unsigned DtParallelTickManager::maxSpinCount ( ) const

virtual

Accessor/mutator for number of times to spin on spinlock before yielding processor.

Setting to 0 will turn off yielding. Default is 0.

virtual void DtParallelTickManager::setMaxSpinCount ( unsigned  )

virtual

virtual bool DtParallelTickManager::active ( ) const

virtual

Accessor/mutator for the entire parallel mechanism.

Disabling will delete the queue and execute callbacks in the calling thread.

virtual void DtParallelTickManager::setActive ( bool  )

virtual

virtual bool DtParallelTickManager::enabled ( const std::string &  , bool  def  ) const

virtual

Simple mechanism for controlling multiple parallel sections.

This class is designed to be used by multiple sections of code to execute different sets of parallel callbacks. This function allows each of those sections to be named and then have their options controlled individually by this class. If you supply a tag in any of the add callback functions a record will be made of that that tag by this function.

Parameters

def	Default value to record if it's a new tag.

Referenced by addCallbacks().

virtual bool DtParallelTickManager::executeCommand ( const std::string &  , bool  on  )

virtual

Execute a console command.

virtual void DtParallelTickManager::printInfo ( std::ostream &  ) const

virtual

Print information about current state.

virtual void DtParallelTickManager::addCallback ( CallbackInterface *  )

virtual

Add callbacks to the queue.

The pointer versions take ownership of their callbacks. The reference versions do not and require the caller to keep them alive. The container versions add an STL-like container of callbacks.

Parameters

runNow	Execute the callback right now instead of adding it the queue.
tag	See enabled().
def	Default value for enabled().

Referenced by addCallbacks().

virtual void DtParallelTickManager::addCallback ( CallbackInterface &  )

virtual

virtual void DtParallelTickManager::addCallback ( CallbackInterface *  , const std::string &  tag, bool  def = true  )

virtual

virtual void DtParallelTickManager::addCallback ( CallbackInterface &  , const std::string &  tag, bool  def = true  )

virtual

void DtParallelTickManager::addCallback	(	CallbackInterface *	,
		const char *	tag,
		bool	def = true
	)

void DtParallelTickManager::addCallback	(	CallbackInterface &	,
		const char *	tag,
		bool	def = true
	)

template<typename Container >

void DtParallelTickManager::addCallbacks ( Container &  cont )

inline

References addCallback().

Referenced by addCallbacks().

template<typename Container >

void DtParallelTickManager::addCallbacks ( Container &  cont, const std::string &  tag, bool  def = true  )

inline

References addCallback(), enabled(), and RunJob().

template<typename Container >

void DtParallelTickManager::addCallbacks ( Container &  cont, const char *  tag, bool  def = true  )

inline

References addCallbacks().

virtual bool DtParallelTickManager::lock ( )

virtual

Manipulate global mutex.

Returns

True if lock changes happened without any time in the unlocked state, i.e. if true then nothing in the global state has not been modified by any threads during the call.

virtual bool DtParallelTickManager::unlock ( )

virtual

virtual bool DtParallelTickManager::readLock ( )

virtual

virtual bool DtParallelTickManager::readUnlock ( )

virtual

virtual bool DtParallelTickManager::upgradeToWriter ( )

virtual

virtual bool DtParallelTickManager::downgradeToReader ( )

virtual

virtual bool DtParallelTickManager::changeAccess ( AccessType  from, AccessType  to  )

virtual

virtual void DtParallelTickManager::configureDeferredJobClass ( JobClass  jobclass, AccessType  access, unsigned  maxConcurrent  )

virtual

Configure a job class.

Parameters

jobclass	Job class to configure.
access	Access type in which the jobs will be run.
maxConcurrent	The number of thread which can run jobs from this class concurrently.

virtual void DtParallelTickManager::addDeferredJob ( JobClass  jobclass, const boost::function< void()> &  callback  )

virtual

Add a deferred job.

virtual void DtParallelTickManager::addVRLinkDeferredJob ( const boost::function< void()> &  callback )

virtual

Convenience functions.

virtual void DtParallelTickManager::setDeferJobs ( bool  )

virtual

Enable/disable deferred jobs.

Deferred jobs are disabled by default and enabled during entity tick. When disabled jobs will be run during when the are added with the access mode as EXCLUSIVE.

virtual ThreadLocalInfo& DtParallelTickManager::threadLocalInfo ( )

virtual

static void DtParallelTickManager::RunJob ( CallbackInterface *  )

staticprivate

Referenced by addCallbacks().

static void DtParallelTickManager::RunJob ( CallbackInterface &  )

staticprivate

virtual void DtParallelTickManager::executeDeferredJobs ( AccessType  access )

privatevirtual

virtual void DtParallelTickManager::flushDeferredJobs ( )

privatevirtual

DtParallelTickManager::ThreadLocalInfo ( DtParallelTickManager *  m )

explicit

DtParallelTickManager::AccessType DtParallelTickManager::state

(

)

const

void DtParallelTickManager::push ( DtCriticalSection &  cs )

private

void DtParallelTickManager::pop ( DtCriticalSection &  cs )

private

Friends And Related Function Documentation

friend class DtCriticalSection

friend

Member Data Documentation

tbb::atomic<int> DtParallelTickManager::myAccessCount

private

ThreadLocalContainer DtParallelTickManager::myThreadLocals

private

DtVrfSimOptionsInterface* DtParallelTickManager::myOptions

private

DtVrfCallbackQueue* DtParallelTickManager::myCallbackQueue

private

EnabledMap DtParallelTickManager::myEnabledMap

mutableprivate

bool DtParallelTickManager::myWaitFlag

private

unsigned DtParallelTickManager::myMaxSpinCount

private

bool DtParallelTickManager::myDeferJobsFlag

private

boost::ptr_vector<ClassInfo> DtParallelTickManager::myDeferredJobs

private

tbb::atomic<unsigned> DtParallelTickManager::myDeferredJobCount

private

DtSubCommandManager* DtParallelTickManager::myCommandManager

private

DtConsoleCommandOwner* DtParallelTickManager::myCommandOwner

private

__itt_domain* DtParallelTickManager::myLockITTDomain

private

__itt_string_handle* DtParallelTickManager::mySharedLockEvent

private

__itt_string_handle* DtParallelTickManager::myExclusiveLockEvent

private

__itt_string_handle* DtParallelTickManager::mySharedAccessEvent

private

__itt_string_handle* DtParallelTickManager::myExclusiveAccessEvent

private

__itt_string_handle* DtParallelTickManager::myDeferredJobTask

private

Stack DtParallelTickManager::myLocks

private

---

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

• /exports/nfedora7-1/nightly/docs/vrforcesDevelopment.tot/include/vrfcore/parallelTickManager.h