SimEventQueue Class Reference

Helper class to gather events generated while running a simulation. More...

#include <Simulation/SimEventQueue.H>

Inheritance diagram for SimEventQueue:

[legend]

Collaboration diagram for SimEventQueue:

[legend]

List of all members.

Classes
struct	RealmData
struct	TypeInfoCompare
Public Member Functions
	SimEventQueue (OptionManager &mgr, const std::string &descrName="Simulation Event Queue", const std::string &tagName="SimEventQueue", const SimTime starttime=SimTime::ZERO())
	Constructor.
virtual	~SimEventQueue ()
	Destructor.
template<class E >
void	post (rutz::shared_ptr< E > e)
	Post a new SimEvent; typically, SimModule modules do this.
template<class R >
size_t	request (rutz::shared_ptr< R > r, const SimReqQueueFlag flags=SRQ_NONE_FATAL\|SRQ_SEVERAL_FATAL)
	Handle a new SimReq; typically, SimModule modules do this.
template<class E >
SeC< E >	check (const SimModule caller, const SimEventQueueFlag flags=SEQ_UNMARKED\|SEQ_MARK, const SimModule eventsrc=0)
	Return event, if any, that satisfies the given criteria.
virtual SimStatus	evolve ()
	Increment the master clock and delete old events.
virtual const SimTime &	now () const
	Get the master clock's time.
virtual void	clear ()
	Erase the entire queue; like reset() but does not reset time.
virtual void	prune (const SimTime &tt)
	Erase all events with time <= tt.
virtual void	resetTime (const SimTime &tim=SimTime::ZERO())
	Reset the time to the given value and erase the entire queue.
void	registerSimCallbackClient (SimModule *s)
	Register a new SimCallbackClient, taking all its callbacks.
void	registerSimReqHandlerClient (SimModule *s)
	Register a new SimReqHandlerClient, taking all its callbacks.
void	printCallbacks () const
	Show all registered callbacks.
Protected Types
typedef std::pair< SimTime, rutz::shared_ptr< SimEvent > >	SeqEntry
typedef std::vector< SeqEntry >	SeqEntryVec
typedef std::multiset < SimCallbackBase *, SimCallbackCompare >	sscbb
typedef std::map< const std::type_info *, rutz::shared_ptr< sscbb > , TypeInfoCompare >	scbm
typedef std::vector < SimReqHandlerBase * >	ssrhb
typedef std::map< const std::type_info *, rutz::shared_ptr< ssrhb > , TypeInfoCompare >	srhm
typedef std::map< std::string, RealmData >	SeqData
Protected Member Functions
virtual void	postHelper (const std::type_info &etype, const rutz::shared_ptr< SimEvent > &e)
	This is called by post(). Default is a no-op.
virtual void	requestHelper (const std::type_info &etype, const rutz::shared_ptr< SimReq > &e)
	This is called by request(). Default is a no-op.
virtual void	checkHelper (const std::type_info &etype, const rutz::shared_ptr< SimEvent > &e, const SimModule caller, const SimEventQueueFlag flags, const SimModule eventsrc)
	this is called by check(). Default is a no-op.
virtual void	reset1 ()
	Reset and propagate the reset signal to the sub-components.
virtual void	start1 ()
	get started
RealmData *	getRealm (const std::string &realmname, const bool create_on_fail)
Protected Attributes
OModelParam< SimTime >	itsTimeStep
	Simulation time step, in seconds.
OModelParam< SimTime >	itsTooMuchTime
	Exit after a given time in seconds (if not zero).
OModelParam< bool >	itsShowMemStats
	Display memory stats when a module posts a SimEventShowMemStats.
OModelParam< size_t >	itsShowMemStatsUnits
	Default units for memory stats.
OModelParam< std::string >	itsLogFile
	text log file name
SimTime	t
	the simulation's master clock
SeqData	itsQueue

Detailed Description

Helper class to gather events generated while running a simulation.

The class maintains a list of events which may arise from various simulation modules, and can be queried for specific events.

This class implements a so-called 'blackboard architecture', a concept which was introduced in artificial intelligence research to facilitate information sharing among multiple heterogeneous problem-solving agents. The basic idea is that the blackboard is a shared repository of information which all agents can access while working towards the solution to a given problem.

Because different modules are usually run sequentially, e.g., in Brain::evolve(), the intent here is that we keep track of both the events that arise during a given evolve at SimTime t and during the previous evolve. If an event arises after a given module has already been evolve'd for the current iteration, that module will know about the event on the next iteration. For example, in Brain::evolve(), we evolve the SaliencyMap module before the EyeHeadController module; hence if an eye saccade is initiated by the EyeHeadController, the SaliencyMap will become aware of that at the next iteration, and may decide to take appropriate action, e.g., saccadic suppression. To eliminate events older than a given time, use prune(), typically this would be done at the beginning of Brain::evolve().

IMPORTANT: When a given SimModule posts an event at time t, all events posted by that same SimModule at times < t are erased from the queue. This is as soon as the event type matches, whether or not the event's contents match.

HISTORICAL NOTE: SimEventQueue was introduced as an attempt to give more autonomy to the Brain modules by employing a blackboard architecture. An example of how things worked before is as follows: a SaccadeController may decide in its evolve() function that it is time to blink, and will switch itself to blink state. Brain::evolve() would have to query the controller after running evolve() on it, to check whether anything happened, like for example the start of the blink. If so, Brain::eyeBlink() would be triggered, which in turn would dispatch the event to several other modules, calling for example SimulationViewer::eyeBlink() and SaliencyMap::blinkSuppression(). The more types of events could occur, the more complex Brain::evolve() was becoming. With SimEventQueue, most of the complex orchestration which was in Brain::evolve() is now delegated to the brain modules themselves. For example, when SaccadeController initiates a blink, it simply posts a SimEvent indicating so. When SimulationViewer's turn comes to evolve, it can query SimEventQueue to check whether a blink has started, and take appropriate action.

Definition at line 113 of file SimEventQueue.H.

Constructor & Destructor Documentation

SimEventQueue::SimEventQueue	(	OptionManager &	mgr,
		const std::string &	descrName = `"Simulation Event Queue"`,
		const std::string &	tagName = `"SimEventQueue"`,
		const SimTime	starttime = `SimTime::ZERO()`
	)

Constructor.

An optional start time for the master simulation clock may be provided.

Definition at line 63 of file SimEventQueue.C.

SimEventQueue::~SimEventQueue ( ) [virtual]

Destructor.

Definition at line 77 of file SimEventQueue.C.

Member Function Documentation

template<class E >

SeC< E > SimEventQueue::check	(	const SimModule *	caller,
		const SimEventQueueFlag	flags = `SEQ_UNMARKED \| SEQ_MARK`,
		const SimModule *	eventsrc = `0`
	)			`[inline]`

Return event, if any, that satisfies the given criteria.

Example usage is as follows:

    // Assume a SimEventQueue object q
    // Assume that caller is a SimModule
    // Assume that CovertShift derives from SimEvent
    if (SeC<CovertShift> e = q.check<CovertShift>(this))
      {
        // handle the event; you can use 'e' pretty much as you
        // would use a shared_ptr
      }

You can specify an eventsrc SimModule to further narrow the search to only events that originated from this module. NOTE: only events which are either public or intended for the caller will be returned (assuming that all other match criteria are also fullfilled). See Simulation/SimEvent.H for the distinction between public and private events. By default, the flags are set so that we will return the most recent matching unmarked event, then mark it in the queue as done by the caller module; hence several calls to check will return all unmarked events (from most recent to oldest) until they have all been marked. PROGRAMMER NOTE: don't overload this, instead you can overload checkHelper() which is called from here.

Definition at line 522 of file SimEventQueue.H.

References checkHelper(), rutz::demangled_name(), rutz::dyn_cast(), rutz::shared_ptr< T >::is_valid(), ModelComponent::realm(), SEQ_MARK, and SEQ_UNMARKED.

void SimEventQueue::checkHelper	(	const std::type_info &	etype,
		const rutz::shared_ptr< SimEvent > &	e,
		const SimModule *	caller,
		const SimEventQueueFlag	flags,
		const SimModule *	eventsrc
	)			`[inline, protected, virtual]`

this is called by check(). Default is a no-op.

Parameters:

	etype	typeid of the event which the caller wanted to check for (use rutz::demangle(etype) to get the type name)
	e	matching event found, will be invalid if no match was found. Note that e may have a different type from what the caller was looking for, namely it could be a derived class from the one looked for.
	caller	the SimModule that called check().
	flags	the flags passed to check().
	eventsrc	the event source passed to check() if any.

Reimplemented in SimEventQueueDebug.

Definition at line 566 of file SimEventQueue.H.

Referenced by check().

void SimEventQueue::clear ( void ) [virtual]

Erase the entire queue; like reset() but does not reset time.

Use reset() instead unless you know what you are doing.

Reimplemented in SimEventQueueDebug.

Definition at line 170 of file SimEventQueue.C.

References ModelComponent::stop().

Referenced by resetTime().

SimStatus SimEventQueue::evolve ( ) [virtual]

Increment the master clock and delete old events.

Events whose time is < t just before we increment the clock will be removed from the queue. We will here also check for some events that are handled directly by the queue agent.

Reimplemented in SimEventQueueDebug.

Definition at line 99 of file SimEventQueue.C.

References OModelParam< T >::getVal(), itsLogFile, itsShowMemStats, itsTimeStep, itsTooMuchTime, now(), post(), setLogTime(), and t.

Referenced by Simulation::run().

const SimTime & SimEventQueue::now ( ) const [virtual]

Get the master clock's time.

Definition at line 198 of file SimEventQueue.C.

References t.

Referenced by ThresholdFrictionSaccadeController::computeWhenNewDecision(), MonkeySaccadeController::doEvolve(), FrictionSaccadeController::doEvolve(), evolve(), VisualBufferStd::evolve(), SaccadeController::getDecision(), SimulationViewerStd::getTraj(), SimulationViewerNerdCam::getTraj(), SaliencyMapFast::integrate(), post(), request(), SaccadeController::resetPos(), SimulationViewerStats::save1(), and SimOutputFrameSeries::update().

template<class E >

void SimEventQueue::post ( rutz::shared_ptr< E > e ) [inline]

void SimEventQueue::postHelper	(	const std::type_info &	etype,
		const rutz::shared_ptr< SimEvent > &	e
	)			`[inline, protected, virtual]`

This is called by post(). Default is a no-op.

Parameters:

	etype	typeid of the event which the caller wanted to check for (use rutz::demangle(etype) to get the type name)
	e	the event posted
	the	post time

Reimplemented in SimEventQueueDebug.

Definition at line 575 of file SimEventQueue.H.

Referenced by post().

void SimEventQueue::printCallbacks ( ) const

Show all registered callbacks.

Definition at line 310 of file SimEventQueue.C.

References ModelComponent::stop().

void SimEventQueue::prune ( const SimTime & tt ) [virtual]

Erase all events with time <= tt.

Reimplemented in SimEventQueueDebug.

Definition at line 182 of file SimEventQueue.C.

References ModelComponent::stop().

void SimEventQueue::registerSimCallbackClient ( SimModule * s )

Register a new SimCallbackClient, taking all its callbacks.

Definition at line 230 of file SimEventQueue.C.

References SimCallbackBase::etype(), ModelComponent::realm(), ModelComponent::stop(), and SimCallbackBase::toString().

void SimEventQueue::registerSimReqHandlerClient ( SimModule * s )

Register a new SimReqHandlerClient, taking all its callbacks.

Definition at line 270 of file SimEventQueue.C.

References ModelComponent::realm(), SimReqHandlerBase::rtype(), ModelComponent::stop(), and SimReqHandlerBase::toString().

template<class R >

size_t SimEventQueue::request	(	rutz::shared_ptr< R >	r,
		const SimReqQueueFlag	flags = `SRQ_NONE_FATAL \| SRQ_SEVERAL_FATAL`
	)			`[inline]`

Handle a new SimReq; typically, SimModule modules do this.

Note two differences between this and post(): here, the SimReq object does not end up in the queue, it is just privately passed to the event handlewr, who will modify it, and then the caller can use the results. Second, SimReq objects are typically passed read/write while SimEvent objects are read-only in post(). This function returns the number of handlers that were triggered by the request. Zero means that nobody caught the request. Default behavior is to throw a fatal exception if zero or more than 1 handlers catch the request.

Definition at line 460 of file SimEventQueue.H.

References rutz::demangled_name(), rutz::shared_ptr< T >::is_valid(), now(), R, requestHelper(), SRQ_NONE_FATAL, SRQ_SEVERAL_FATAL, and ModelComponent::stop().

Referenced by InferoTemporalSalBayes::attentionShift(), InferoTemporalStd::attentionShift(), SimulationViewerStd::drawMegaCombo(), AttentionGateStd::extractFeatureValues(), SimulationViewerCompress::getTraj(), and SimulationViewerStats::save1().