|
||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||
java.lang.Objectptolemy.kernel.util.NamedObj
ptolemy.kernel.util.Attribute
ptolemy.actor.Director
ptolemy.domains.de.kernel.DEDirector
This director implements the discrete-event model of computation (MoC). It should be used as the local director of a CompositeActor that is to be executed according to this MoC. This director maintain a notion of current time, and processes events chronologically in this time. An event is a token with a time stamp. Much of the sophistication in this director is aimed at handling simultaneous events intelligently, so that deterministic behavior can be achieved.
The bottleneck in a typical DE simulator is in the maintenance of the global event queue. By default, a DE director uses the calendar queue as the global event queue. This is an efficient algorithm with O(1) time complexity in both enqueue and dequeue operations.
Sorting in the CalendarQueue class is done according to the order defined by the DEEvent class, which implements the java.lang.Comparable interface. A DE event has a time stamp, a microstep, and a depth. The time stamp indicates the time when the event occurs. The microstep represents the phase of execution when processing simultaneous events in directed loops, or when an actor schedules itself for firing later at the current time (using fireAt()). The depth is the index of the destination actor in a topological sort. A larger value of depth represents a lower priority when processing events. The depth is determined by topologically sorting the actors according to data dependencies over which there is no time delay. Note that the zero-delay data dependencies are determined on a per port basis.
Ports in the DE domain may be instances of DEIOPort. The DEIOPort class should be used whenever an actor introduces time delays between the inputs and the outputs. When an ordinary IOPort is used, the director assumes, for the purpose of calculating priorities, that the delay across the actor is zero. On the other hand, when DEIOPort is used, the delay across the actor can be declared to be non-zero by calling the delayTo() method on output ports.
Directed loops with no delay are not permitted; they would make it impossible to assign priorities. Such a loop can be broken by inserting an instance of the Delay actor. If zero delay around the loop is truly required, then simply set the delay parameter of that actor to zero. The directed loops are based on the port connections rather than the actor connections because the port connections reflect the data flow more accurately. The information of port connections are stored in a nonpersistent attribute FunctionDependency, which is constructed during run time.
Input ports in a DE model contain instances of DEReceiver. When a token is put into a DEReceiver, that receiver enqueues the event to the director by calling the _enqueueEvent() method of this director. This director sorts all such events in a global event queue (a priority queue).
An iteration, in the DE domain, is defined as processing all the events whose time stamp equals to the current time of the director. At the beginning of the fire() method, this director dequeues a subset of the oldest events (the ones with smallest time stamp, microstep, and depth) from the global event queue, and puts those events into their destination receivers. The actor(s) to which these events are destined are the ones to be fired. The depth of an event is the depth of the actor to which it is destined. The depth of an actor is its position in a topological sort of the graph. The microstep is usually zero, but is incremented when a pure event is queued with time stamp equal to the current time.
The actor that is fired must consume tokens from its input port(s), and will usually produce new events on its output port(s). These new events will be enqueued in the global event queue until their time stamps equal the current time. It is important that the actor actually consume tokens from its inputs, even if the tokens are solely used to trigger reactions. This is how polymorphic actors are used in the DE domain. The actor will be fired repeatedly until there are no more tokens in its input ports with the current time stamp. Alternatively, if the actor returns false in prefire(), then it will not be invoked again in the same iteration even if there are events in its receivers.
A model starts from the time specified by startTime, which has default value 0.0
The stop time of the execution can be set using the stopTime parameter. The parameter has default value Double.MAX_VALUE, which means the execution stops only when the model time reaches that (rather large) number.
Execution of a DE model ends when the time stamp of the oldest events
exceeds a preset stop time. This stopping condition is checked inside
the prefire() method of this director. By default, execution also ends
when the global event queue becomes empty. Sometimes, the desired
behaviour is for the director to wait on an empty queue until another
thread makes new events available. For example, a DE actor may produce
events when a user hits a button on the screen. To prevent ending the
execution when there are no more events, set the
stopWhenQueueIsEmpty parameter to false.
Parameters, isCQAdaptive, minBinCount, and binCountFactor, are used to configure the calendar queue. Changes to these parameters are ignored when the model is running.
If the parameter synchronizeToRealTime is set to true,
then the director will not process events until the real time elapsed
since the model started matches the time stamp of the event.
This ensures that the director does not get ahead of real time,
but, of course, it does not ensure that the director keeps up with
real time.
This director tolerates changes to the model during execution. The change should be queued with a component in the hierarchy using requestChange(). While invoking those changes, the method invalidateSchedule() is expected to be called, notifying the director that the topology it used to calculate the priorities of the actors is no longer valid. This will result in the priorities being recalculated the next time prefire() is invoked.
However, there is one subtlety. If an actor produces events in the future via DEIOPort, then the destination actor will be fired even if it has been removed from the topology by the time the execution reaches that future time. This may not always be the expected behavior. The Delay actor in the DE library behaves this way.
DEReceiver,
CalendarQueue,
Serialized Form
| Yellow (eal) |
| Green (liuj) |
| Nested Class Summary |
| Nested classes inherited from class ptolemy.kernel.util.NamedObj |
ptolemy.kernel.util.NamedObj.ContainedObjectsIterator |
| Field Summary | |
protected java.util.Hashtable |
_actorToDepth
|
protected java.util.Set |
_disabledActors
|
protected DEEventQueue |
_eventQueue
The queue used for sorting events. |
protected boolean |
_exceedStopTime
|
protected int |
_microstep
|
protected boolean |
_noMoreActorsToFire
Set to true when it is time to end the execution. |
protected long |
_realStartTime
|
protected long |
_sortValid
|
protected boolean |
_stopWhenQueueIsEmpty
|
protected boolean |
_synchronizeToRealTime
|
ptolemy.data.expr.Parameter |
binCountFactor
The factor when adjusting the bin number. |
ptolemy.data.expr.Parameter |
isCQAdaptive
Specify whether the calendar queue adjusts its bin number at run time. |
ptolemy.data.expr.Parameter |
minBinCount
The minimum (initial) number of bins in the calendar queue. |
ptolemy.data.expr.Parameter |
startTime
The start time of model. |
ptolemy.data.expr.Parameter |
stopTime
The stop time of the model. |
ptolemy.data.expr.Parameter |
stopWhenQueueIsEmpty
Specify whether the execution stops when the queue is empty. |
ptolemy.data.expr.Parameter |
synchronizeToRealTime
Specify whether the execution should synchronize to the real time. |
ptolemy.data.expr.Parameter |
timeResolution
The resolution in comparing time. |
| Fields inherited from class ptolemy.actor.Director |
_currentTime, _stopRequested |
| Fields inherited from class ptolemy.kernel.util.NamedObj |
_changeListeners, _changeLock, _changeRequests, _debugging, _debugListeners, _elementName, _isPersistent, _workspace, ATTRIBUTES, CLASSNAME, COMPLETE, CONTENTS, DEEP, FULLNAME, LINKS |
| Fields inherited from interface ptolemy.actor.Executable |
COMPLETED, NOT_READY, STOP_ITERATING |
| Constructor Summary | |
DEDirector()
Construct a director in the default workspace with an empty string as its name. |
|
DEDirector(ptolemy.kernel.CompositeEntity container,
java.lang.String name)
Construct a director in the given container with the given name. |
|
DEDirector(ptolemy.kernel.util.Workspace workspace)
Construct a director in the workspace with an empty name. |
|
| Method Summary | |
protected ptolemy.actor.Actor |
_dequeueEvents()
Dequeue the events from the event queue that have the smallest time stamp and depth. |
protected void |
_disableActor(ptolemy.actor.Actor actor)
Disable the specified actor. |
protected void |
_enqueueEvent(ptolemy.actor.Actor actor,
double time)
Put a pure event into the event queue with the specified time stamp. |
protected void |
_enqueueEvent(DEReceiver receiver,
ptolemy.data.Token token)
Put an event into the event queue with the specified destination receiver, and token. |
protected void |
_enqueueEvent(DEReceiver receiver,
ptolemy.data.Token token,
double time)
Put an event into the event queue with the specified destination receiver, token, and time stamp. |
protected int |
_getDepth(ptolemy.actor.Actor actor)
Return the depth of the actor. |
protected void |
_requestFiring()
|
protected boolean |
_writeAccessRequired()
Override the default Director implementation, because in DE domain, we don't need write access inside an iteration. |
void |
addDebugListener(ptolemy.kernel.util.DebugListener listener)
Append the specified listener to the current set of debug listeners. |
void |
attributeChanged(ptolemy.kernel.util.Attribute attribute)
Update the director parameters when the attributes are changed. |
void |
fire()
Advance current time to the next event in the event queue, and fire one or more actors that have events at that time. |
void |
fireAt(ptolemy.actor.Actor actor,
double time)
Schedule an actor to be fired at the specified absolute time. |
void |
fireAtCurrentTime(ptolemy.actor.Actor actor)
Schedule a firing of the given actor as soon as possible. |
void |
fireAtRelativeTime(ptolemy.actor.Actor actor,
double time)
Schedule an actor to be fired at the specified relative time. |
DEEventQueue |
getEventQueue()
Return the event queue. |
double |
getNextIterationTime()
Return the time stamp of the next event in the queue with time stamp strictly greater than the current time. |
long |
getRealStartTimeMillis()
Return the system time at which the model begins executing. |
double |
getStartTime()
Return the time of the start time in the model as set by the startTime parameter. |
double |
getStopTime()
Return the stop time of the execution as set by the stopTime parameter. |
void |
initialize()
Invoke the initialize() method of each deeply contained actor, and then check the event queue for any events. |
void |
invalidateSchedule()
Indicate that the topological depth of the ports in the model may no longer be valid. |
ptolemy.actor.Receiver |
newReceiver()
Return a new receiver of a type DEReceiver. |
boolean |
postfire()
Return false if there are no more actors to fire or if stop() has been called. |
boolean |
prefire()
Return true if there are input to this composite actor, and the current time of the outside domain is greater than or equal to the current time. |
void |
preinitialize()
Set current time to zero, invoke the preinitialize() methods of all actors deeply contained by the container, and calculate priorities for simultaneous events. |
void |
removeDebugListener(ptolemy.kernel.util.DebugListener listener)
Unregister a debug listener. |
void |
stop()
Request that execution of the current iteration stop. |
void |
stopFire()
Request that execution of the current iteration complete. |
boolean |
transferOutputs(ptolemy.actor.IOPort port)
Override the base class method to transfer all the available tokens from a DE model. |
| Methods inherited from class ptolemy.actor.Director |
_description, _isEmbedded, _isTopLevel, domainPolymorphicTransferInputs, domainPolymorphicTransferOutputs, getCurrentTime, getTimeResolution, initialize, invalidateResolvedTypes, iterate, needWriteAccess, requestInitialization, setContainer, setCurrentTime, setTimeResolution, terminate, transferInputs, wrapup |
| Methods inherited from class ptolemy.kernel.util.Attribute |
_getContainedObject, _propagateExistence, clone, getContainer, setName |
| Methods inherited from class ptolemy.kernel.util.NamedObj |
_addAttribute, _attachText, _cloneFixAttributeFields, _debug, _debug, _debug, _debug, _debug, _exportMoMLContents, _getIndentPrefix, _isMoMLSuppressed, _markContentsDerived, _propagateValue, _removeAttribute, _splitName, _stripNumericSuffix, addChangeListener, attributeList, attributeList, attributeTypeChanged, clone, containedObjectsIterator, deepContains, depthInHierarchy, description, description, event, executeChangeRequests, exportMoML, exportMoML, exportMoML, exportMoML, exportMoML, getAttribute, getAttribute, getAttributes, getChangeListeners, getClassName, getDerivedLevel, getDerivedList, getElementName, getFullName, getModelErrorHandler, getName, getName, getPrototypeList, getSource, handleModelError, isDeferringChangeRequests, isOverridden, isPersistent, message, propagateExistence, propagateValue, propagateValues, removeChangeListener, requestChange, setClassName, setDeferringChangeRequests, setDerivedLevel, setModelErrorHandler, setPersistent, setSource, toplevel, toString, uniqueName, validateSettables, workspace |
| Methods inherited from class java.lang.Object |
equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait |
| Field Detail |
public ptolemy.data.expr.Parameter startTime
public ptolemy.data.expr.Parameter stopTime
public ptolemy.data.expr.Parameter stopWhenQueueIsEmpty
public ptolemy.data.expr.Parameter synchronizeToRealTime
public ptolemy.data.expr.Parameter isCQAdaptive
public ptolemy.data.expr.Parameter minBinCount
public ptolemy.data.expr.Parameter binCountFactor
public ptolemy.data.expr.Parameter timeResolution
protected DEEventQueue _eventQueue
protected boolean _noMoreActorsToFire
protected java.util.Set _disabledActors
protected int _microstep
protected boolean _exceedStopTime
protected long _realStartTime
protected boolean _stopWhenQueueIsEmpty
protected boolean _synchronizeToRealTime
protected long _sortValid
protected java.util.Hashtable _actorToDepth
| Constructor Detail |
public DEDirector()
public DEDirector(ptolemy.kernel.util.Workspace workspace)
workspace - The workspace of this object.
public DEDirector(ptolemy.kernel.CompositeEntity container,
java.lang.String name)
throws ptolemy.kernel.util.IllegalActionException,
ptolemy.kernel.util.NameDuplicationException
container - Container of the director.name - Name of this director.
ptolemy.kernel.util.IllegalActionException - If the
director is not compatible with the specified container.
ptolemy.kernel.util.NameDuplicationException - If the container not a
CompositeActor and the name collides with an entity in the container.| Method Detail |
public void addDebugListener(ptolemy.kernel.util.DebugListener listener)
listener - The listener to add to the list of listeners
to which debug messages are sent.
public void attributeChanged(ptolemy.kernel.util.Attribute attribute)
throws ptolemy.kernel.util.IllegalActionException
attribute - The changed parameter.
ptolemy.kernel.util.IllegalActionException - If the parameter set is not valid.
Not thrown in this class. May be needed by derived classes.
public void fire()
throws ptolemy.kernel.util.IllegalActionException
ptolemy.kernel.util.IllegalActionException - If the firing actor throws it.
public void fireAt(ptolemy.actor.Actor actor,
double time)
throws ptolemy.kernel.util.IllegalActionException
actor - The scheduled actor to fire.time - The scheduled time to fire.
ptolemy.kernel.util.IllegalActionException - If the specified time is in the past.
public void fireAtCurrentTime(ptolemy.actor.Actor actor)
throws ptolemy.kernel.util.IllegalActionException
actor - The actor to be fired.
ptolemy.kernel.util.IllegalActionException - If this method is called
before the model is running.
public void fireAtRelativeTime(ptolemy.actor.Actor actor,
double time)
throws ptolemy.kernel.util.IllegalActionException
actor - The scheduled actor to fire.time - The scheduled time to fire.
ptolemy.kernel.util.IllegalActionException - If the specified time is in the past.public DEEventQueue getEventQueue()
public double getNextIterationTime()
public long getRealStartTimeMillis()
public double getStartTime()
public double getStopTime()
public void initialize()
throws ptolemy.kernel.util.IllegalActionException
ptolemy.kernel.util.IllegalActionException - If the initialize() method of
one of the associated actors throws it.public void invalidateSchedule()
public ptolemy.actor.Receiver newReceiver()
public boolean postfire()
throws ptolemy.kernel.util.IllegalActionException
ptolemy.kernel.util.IllegalActionException - Not thrown in this base class.
public boolean prefire()
throws ptolemy.kernel.util.IllegalActionException
ptolemy.kernel.util.IllegalActionException - If there are input events
in the past, or the outside time is larger than the
time stamp of the first event in the event queue.
public void preinitialize()
throws ptolemy.kernel.util.IllegalActionException
This method should be invoked once per execution, before any iteration. Actors cannot produce output data in their preinitialize() methods. If initial events are needed, e.g. pure events for source actor, the actors should do so in their initialize() methods. This method is not synchronized on the workspace, so the caller should be.
ptolemy.kernel.util.IllegalActionException - If there is a delay-free loop, or
if the preinitialize() method of the
container or one of the deeply contained actors throws it.public void removeDebugListener(ptolemy.kernel.util.DebugListener listener)
listener - The listener to remove from the list of listeners
to which debug messages are sent.public void stop()
public void stopFire()
public boolean transferOutputs(ptolemy.actor.IOPort port)
throws ptolemy.kernel.util.IllegalActionException
port - The port to transfer tokens from.
ptolemy.kernel.util.IllegalActionException - If the port is not an opaque
output port.protected ptolemy.actor.Actor _dequeueEvents()
protected void _disableActor(ptolemy.actor.Actor actor)
actor - The actor to disable.
protected void _enqueueEvent(ptolemy.actor.Actor actor,
double time)
throws ptolemy.kernel.util.IllegalActionException
actor - The destination actor.time - The time stamp of the "pure event".
ptolemy.kernel.util.IllegalActionException - If the time argument is in the past.
protected void _enqueueEvent(DEReceiver receiver,
ptolemy.data.Token token,
double time)
throws ptolemy.kernel.util.IllegalActionException
receiver - The destination receiver.token - The token destined for that receiver.time - The time stamp of the event.
ptolemy.kernel.util.IllegalActionException - If the delay is negative.
protected void _enqueueEvent(DEReceiver receiver,
ptolemy.data.Token token)
throws ptolemy.kernel.util.IllegalActionException
receiver - The destination receiver.token - The token destined for that receiver.
ptolemy.kernel.util.IllegalActionException - If the delay is negative.
protected int _getDepth(ptolemy.actor.Actor actor)
throws ptolemy.kernel.util.IllegalActionException
ptolemy.kernel.util.IllegalActionException - If the actor is not accessible.protected boolean _writeAccessRequired()
protected void _requestFiring()
throws ptolemy.kernel.util.IllegalActionException
ptolemy.kernel.util.IllegalActionException
|
||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||