Drake
EventCollection< EventType > Class Template Referenceabstract

There are three concrete event types for any System: publish, discrete state update, and unrestricted state update, listed in order of increasing ability to change the state (i.e., zero to all). More...

#include <drake/systems/framework/event.h>

Inheritance diagram for EventCollection< EventType >:
[legend]

Public Member Functions

virtual ~EventCollection ()
 
void SetFrom (const EventCollection< EventType > &other)
 Clears all the events maintained by this and adds all the events in other to this. More...
 
void Merge (const EventCollection< EventType > &other)
 Merges all of other's events into this. More...
 
virtual void Clear ()=0
 Removes all events from this collection. More...
 
virtual bool HasEvents () const =0
 Returns false if and only if this collection contains no events. More...
 
virtual void add_event (std::unique_ptr< EventType > event)=0
 Adds an event to this collection, or throws if the concrete collection does not permit adding new events. More...
 
Does not allow copy, move, or assignment
 EventCollection (const EventCollection &)=delete
 
EventCollectionoperator= (const EventCollection &)=delete
 
 EventCollection (EventCollection &&)=delete
 
EventCollectionoperator= (EventCollection &&)=delete
 

Protected Member Functions

 EventCollection ()=default
 Constructor only accessible by derived class. More...
 
virtual void DoMerge (const EventCollection< EventType > &other)=0
 Derived implementation can assume that other is not null and that other != this. More...
 

Detailed Description

template<typename EventType>
class drake::systems::EventCollection< EventType >

There are three concrete event types for any System: publish, discrete state update, and unrestricted state update, listed in order of increasing ability to change the state (i.e., zero to all).

EventCollection is an abstract base class that stores simultaneous events of the same type that occur at the same time (i.e., simultaneous events).

For each concrete event type, the LeafSystem API provides a unique customizable function for processing all simultaneous events of that type, e.g. LeafSystem::DoPublish(const Context&, const vector<const PublishEvent*>&) for publish events, where the second argument represents all of the publish events that occur simultaneously for that leaf system. The default implementation processes the events (i.e., call their callback functions) in the order in which they are stored in the second argument. The developer of new classes derived from LeafSystem is responsible for overriding such functions if the custom LeafSystem behavior depends on the order in which events are processed. For example, suppose two publish events are being processed, events = {per-step publish, periodic publish}. Depending on the desired behavior, the developer has the freedom to ignore both events, perform only one publish action, or perform both publish actions in any arbitrary order. The System and Diagram API provide only dispatch mechanisms that delegate actual event handling to the constituent leaf systems. The Simulator promises that for each set of simultaneous events of the same type, the public event handling method (e.g. System::Publish(context, publish_events)) will be invoked exactly once.

The System API provides several functions for customizable event generation such as System::DoCalcNextUpdateTime() or System::DoGetPerStepEvents(). These functions can return any number of events of arbitrary types, and the resulting events are stored in separate CompositeEventCollection instances. Before calling the event handlers, all of these CompositeEventCollection objects must be merged to generate a complete set of simultaneous events. Then, only events of the appropriate type are passed to the event handlers. e.g. sys.Publish(context, combined_event_collection.get_publish_events()). For example, the Simulator executes this collation process when it is applied to simulate a system.

Here is a complete example. For some LeafSystem sys at time t, its System::DoCalcNextUpdateTime() generates the following CompositeEventCollection (events1):

  PublishEvent: {event1(kPeriodic, callback1)}
  DiscreteUpdateEvent: {event2(kPeriodic, callback2)}
  UnrestrictedUpdateEvent: {}

This LeafSystem also desires per-step event processing(events2), generated by its implementation of System::DoGetPerStepEvents():

  PublishEvent: {event3(kPerStep, callback3)}
  DiscreteUpdateEvent: {}
  UnrestrictedUpdateEvent: {event4(kPerStep,callback4)}

These collections of "simultaneous" events, events1 and events2, are then merged into the composite event collection all_events:

  PublishEvent: {event1, event3}
  DiscreteUpdateEvent: {event2}
  UnrestrictedUpdateEvent: {event4}

This heterogeneous event collection can be processed by calling the appropriate handler on the appropriate homogeneous subcollection:

  sys.CalcUnrestrictedUpdate(context,
      all_events.get_unrestricted_update_events(), state);
  sys.CalcDiscreteVariableUpdates(context,
      all_events.get_discrete_update_events(), discrete_state);
  sys.Publish(context, all_events.get_publish_events())

For a LeafSystem, this is equivalent to (by expanding the dispatch mechanisms in the System API):

  sys.DoCalcUnrestrictedUpdate(context, {event4}, state);
  sys.DoCalcDiscreteVariableUpdates(context, {event2}, discrete_state);
  sys.DoPublish(context, {event1, event3})
Template Parameters
EventTypea concrete derived type of Event (e.g., PublishEvent).

Constructor & Destructor Documentation

EventCollection ( const EventCollection< EventType > &  )
delete
EventCollection ( EventCollection< EventType > &&  )
delete
virtual ~EventCollection ( )
inlinevirtual
EventCollection ( )
protecteddefault

Constructor only accessible by derived class.

Here is the caller graph for this function:

Member Function Documentation

virtual void add_event ( std::unique_ptr< EventType >  event)
pure virtual

Adds an event to this collection, or throws if the concrete collection does not permit adding new events.

Derived classes must implement this method to add the specified event to the homogeneous event collection.

Implemented in LeafEventCollection< EventType >, and DiagramEventCollection< EventType >.

Here is the caller graph for this function:

virtual void Clear ( )
pure virtual

Removes all events from this collection.

Implemented in LeafEventCollection< EventType >, and DiagramEventCollection< EventType >.

Here is the caller graph for this function:

virtual void DoMerge ( const EventCollection< EventType > &  other)
protectedpure virtual

Derived implementation can assume that other is not null and that other != this.

Implemented in LeafEventCollection< EventType >, and DiagramEventCollection< EventType >.

Here is the caller graph for this function:

virtual bool HasEvents ( ) const
pure virtual

Returns false if and only if this collection contains no events.

Implemented in LeafEventCollection< EventType >, and DiagramEventCollection< EventType >.

Here is the caller graph for this function:

void Merge ( const EventCollection< EventType > &  other)
inline

Merges all of other's events into this.

If other == this, does nothing. See derived DoMerge() for more details.

Here is the caller graph for this function:

EventCollection& operator= ( EventCollection< EventType > &&  )
delete
EventCollection& operator= ( const EventCollection< EventType > &  )
delete
void SetFrom ( const EventCollection< EventType > &  other)
inline

Clears all the events maintained by this and adds all the events in other to this.


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