Main Page | Modules | Namespace List | Class Hierarchy | Alphabetical List | Class List | Directories | File List | Namespace Members | Class Members | File Members | Related Pages

SimEventQueue Class Reference

#include <Simulation/SimEventQueue.H>

Inheritance diagram for SimEventQueue:

Inheritance graph
[legend]
Collaboration diagram for SimEventQueue:

Collaboration graph
[legend]
List of all members.

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.

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

Classes

struct  RealmData
struct  TypeInfoCompare

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 61 of file SimEventQueue.C.

SimEventQueue::~SimEventQueue (   )  [virtual]
 

Destructor.

Definition at line 75 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 536 of file SimEventQueue.H.

References checkHelper(), rutz::demangled_name(), e, ev, SimEventQueue::RealmData::events, getRealm(), rutz::shared_ptr< T >::is_valid(), LFATAL, ModelComponent::realm(), SEQ_MARK, and SEQ_UNMARKED.

Referenced by InferoTemporalSalBayes::attentionShift(), InferoTemporalHmax::attentionShift(), InferoTemporalStd::attentionShift(), SimulationViewerStats::computeAGStats(), ThresholdFrictionSaccadeController::computeWhenNewDecision(), SimulationViewerStd::drawMegaCombo(), SimulationViewerNerdCam::drawMegaCombo(), ObjRecSalBayes::evolveBrain(), SaccadeController::getDecision(), SimulationViewer::getMap(), SimulationViewerStd::getTraj(), SimulationViewerEyeMvt::getTraj(), SimulationViewerCompress::getTraj(), TaskRelevanceMapTigs2::integrate(), TaskRelevanceMapTigs::integrate(), TaskRelevanceMapGistClassify::integrate(), TaskRelevanceMapKillN::integrate(), and SimulationViewerStats::save1().

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 587 of file SimEventQueue.H.

Referenced by check().

void SimEventQueue::clear (   )  [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 166 of file SimEventQueue.C.

References SimEventQueue::RealmData::events, itsQueue, and ModelComponent::stop().

Referenced by SimEventQueueDebug::clear(), and 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 97 of file SimEventQueue.C.

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

Referenced by SimEventQueueDebug::evolve(), and ObjRecSalBayes::evolveBrain().

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

Get the master clock's time.

Definition at line 194 of file SimEventQueue.C.

References t.

Referenced by ThresholdFrictionSaccadeController::computeWhenNewDecision(), AttentionGuidanceMapSC::doClockTick(), MonkeySaccadeController::doEvolve(), FrictionSaccadeController::doEvolve(), evolve(), VisualBufferStd::evolve(), ObjRecSalBayes::evolveBrain(), 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]
 

Post a new SimEvent; typically, SimModule modules do this.

Definition at line 376 of file SimEventQueue.H.

References SimEventQueue::RealmData::callbacks, rutz::demangled_name(), dyn_cast_to_from(), ee, SimEventQueue::RealmData::events, getRealm(), i, rutz::shared_ptr< T >::is_valid(), LDEBUG, LFATAL, now(), postHelper(), SEQ_MARK, ModelComponent::stop(), t, and SimTime::toString().

Referenced by InferoTemporalHmax::attentionShift(), SaliencyMapFast::blinkSuppression(), SaliencyMapTrivial::blinkSuppression(), SaliencyMapFast::depress(), SaliencyMapTrivial::depress(), AttentionGuidanceMapSC::doClockTick(), AttentionGuidanceMap::doClockTick(), evolve(), TwoHalfDSketch::evolve(), Objects::evolve(), Geons3D::evolve(), ObjRecSalBayes::evolveBrain(), SaccadeController::getDecision(), SaliencyMapFast::input(), SaliencyMapTrivial::input(), InferoTemporalSalBayes::predict(), InferoTemporalSalBayes::predictWithSift(), SaliencyMapFast::saccadicSuppression(), SaliencyMapTrivial::saccadicSuppression(), and SimOutputFrameSeries::update().

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 596 of file SimEventQueue.H.

Referenced by post().

void SimEventQueue::printCallbacks (   )  const
 

Show all registered callbacks.

Definition at line 306 of file SimEventQueue.C.

References c, SimEventQueue::RealmData::callbacks, cmap, i, itsQueue, LINFO, SimEventQueue::RealmData::reqhandlers, s, and ModelComponent::stop().

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

Erase all events with time <= tt.

Reimplemented in SimEventQueueDebug.

Definition at line 178 of file SimEventQueue.C.

References ee, SimEventQueue::RealmData::events, itsQueue, and ModelComponent::stop().

Referenced by SimEventQueueDebug::prune().

void SimEventQueue::registerSimCallbackClient (  SimModule *  s  ) 
 

Register a new SimCallbackClient, taking all its callbacks.

Definition at line 226 of file SimEventQueue.C.

References c, SimEventQueue::RealmData::callbacks, SimCallbackBase::etype(), getRealm(), i, LDEBUG, LFATAL, ModelComponent::realm(), ModelComponent::stop(), and SimCallbackBase::toString().

void SimEventQueue::registerSimReqHandlerClient (  SimModule *  s  ) 
 

Register a new SimReqHandlerClient, taking all its callbacks.

Definition at line 266 of file SimEventQueue.C.

References c, getRealm(), i, LDEBUG, LFATAL, ModelComponent::realm(), SimEventQueue::RealmData::reqhandlers, 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 464 of file SimEventQueue.H.

References rutz::demangled_name(), dyn_cast_to_from(), getRealm(), i, rutz::shared_ptr< T >::is_valid(), LDEBUG, LFATAL, now(), SimEventQueue::RealmData::reqhandlers, requestHelper(), SRQ_NONE_FATAL, SRQ_SEVERAL_FATAL, ModelComponent::stop(), and SimTime::toString().

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

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

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

Definition at line 602 of file SimEventQueue.H.

Referenced by request().

void SimEventQueue::reset1 (   )  [protected, virtual]
 

Reset and propagate the reset signal to the sub-components.

See the base function in ModelComponent.H for info.

Reimplemented from ModelComponent.

Definition at line 334 of file SimEventQueue.C.

References ModelComponent::reset1(), and resetTime().

void SimEventQueue::resetTime (  const SimTime &  tim = SimTime::ZERO()  )  [virtual]
 

Reset the time to the given value and erase the entire queue.

Like reset() but does not propagate to subcomponents. Use reset() instead unless you know what you are doing.

Reimplemented in SimEventQueueDebug.

Definition at line 198 of file SimEventQueue.C.

References clear(), and t.

Referenced by reset1(), and SimEventQueueDebug::resetTime().

void SimEventQueue::start1 (   )  [protected, virtual]
 

get started

Reimplemented from SimModule.

Definition at line 79 of file SimEventQueue.C.

References getRealm(), ModelComponent::realm(), and SimModule::start1().

Member Data Documentation

OModelParam<std::string> SimEventQueue::itsLogFile [protected]
 

text log file name

Definition at line 220 of file SimEventQueue.H.

Referenced by evolve().

OModelParam<bool> SimEventQueue::itsShowMemStats [protected]
 

Display memory stats when a module posts a SimEventShowMemStats.

Definition at line 214 of file SimEventQueue.H.

Referenced by evolve().

OModelParam<size_t> SimEventQueue::itsShowMemStatsUnits [protected]
 

Default units for memory stats.

Definition at line 217 of file SimEventQueue.H.

OModelParam<SimTime> SimEventQueue::itsTimeStep [protected]
 

Simulation time step, in seconds.

Definition at line 208 of file SimEventQueue.H.

Referenced by evolve().

OModelParam<SimTime> SimEventQueue::itsTooMuchTime [protected]
 

Exit after a given time in seconds (if not zero).

Definition at line 211 of file SimEventQueue.H.

Referenced by evolve().

SimTime SimEventQueue::t [protected]
 

the simulation's master clock

Definition at line 222 of file SimEventQueue.H.

Referenced by SimEventQueueDebug::evolve(), evolve(), now(), post(), SimEventQueueDebug::postHelper(), and resetTime().

The documentation for this class was generated from the following files:
Generated on Mon Nov 23 15:51:05 2009 for iLab Neuromorphic Vision Toolkit by  doxygen 1.4.4