ptolemy.domains.hde.kernel
Class HDEDirector

java.lang.Object
  extended byptolemy.kernel.util.NamedObj
      extended byptolemy.kernel.util.Attribute
          extended byptolemy.actor.Director
              extended byptolemy.domains.de.kernel.DEDirector
                  extended byptolemy.domains.hde.kernel.HDEDirector
All Implemented Interfaces:
Changeable, java.lang.Cloneable, Debuggable, DebugListener, Derivable, Executable, ModelErrorHandler, MoMLExportable, Nameable, java.io.Serializable

public class HDEDirector
extends DEDirector

This director implements the discrete-event model of computation (MoC) with memoried signals. It extends the DE Director. 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 actors 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.

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).

The HDEDirector employs a special HDE receiver which stores the most recent values of the inputs of an actor and reapplies them whenever an actor input changes.

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 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.

Since:
Ptolemy II 2.0
Version:
$Id: HDEDirector.java,v 1.15 2004/04/13 05:13:17 cxh Exp $
Author:
Lukito Muliadi, Edward A. Lee, Jie Liu, Steve Neuendorffer
See Also:
DEReceiver, CalendarQueue, Serialized Form
Accepted Rating:
Yellow (eal)
Proposed Rating:
Green (liuj)

Nested Class Summary
 
Nested classes inherited from class ptolemy.kernel.util.NamedObj
NamedObj.ContainedObjectsIterator
 
Field Summary
 
Fields inherited from class ptolemy.domains.de.kernel.DEDirector
_actorToDepth, _disabledActors, _eventQueue, _exceedStopTime, _microstep, _noMoreActorsToFire, _realStartTime, _sortValid, _stopWhenQueueIsEmpty, _synchronizeToRealTime, binCountFactor, isCQAdaptive, minBinCount, startTime, stopTime, stopWhenQueueIsEmpty, synchronizeToRealTime, timeResolution
 
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
HDEDirector()
          Construct a director in the default workspace with an empty string as its name.
HDEDirector(CompositeEntity container, java.lang.String name)
          Construct a director in the given container with the given name.
HDEDirector(Workspace workspace)
          Construct a director in the workspace with an empty name.
 
Method Summary
 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.
 Receiver newReceiver()
          Return a new receiver of a type HDEReceiver.
 
Methods inherited from class ptolemy.domains.de.kernel.DEDirector
_dequeueEvents, _disableActor, _enqueueEvent, _enqueueEvent, _enqueueEvent, _getDepth, _requestFiring, _writeAccessRequired, addDebugListener, attributeChanged, fireAt, fireAtCurrentTime, fireAtRelativeTime, getEventQueue, getNextIterationTime, getRealStartTimeMillis, getStartTime, getStopTime, initialize, invalidateSchedule, postfire, prefire, preinitialize, removeDebugListener, stop, stopFire, transferOutputs
 
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
 

Constructor Detail

HDEDirector

public HDEDirector()
Construct a director in the default workspace with an empty string as its name. The director is added to the list of objects in the workspace. Increment the version number of the workspace.


HDEDirector

public HDEDirector(Workspace workspace)
Construct a director in the workspace with an empty name. The director is added to the list of objects in the workspace. Increment the version number of the workspace.

Parameters:
workspace - The workspace of this object.

HDEDirector

public HDEDirector(CompositeEntity container,
                   java.lang.String name)
            throws IllegalActionException,
                   NameDuplicationException
Construct a director in the given container with the given name. The container argument must not be null, or a NullPointerException will be thrown. If the name argument is null, then the name is set to the empty string. Increment the version number of the workspace.

Parameters:
container - Container of the director.
name - Name of this director.
Throws:
IllegalActionException - If the director is not compatible with the specified container.
NameDuplicationException - If the container not a CompositeActor and the name collides with an entity in the container.
Method Detail

fire

public void fire()
          throws IllegalActionException
Advance current time to the next event in the event queue, and fire one or more actors that have events at that time. If synchronizeToRealTime is true, then before firing, wait until real time matches or exceeds the time stamp of the event. Each actor is iterated repeatedly (prefire(), fire(), postfire()), until either it has no more input tokens at the current time, or its prefire() method returns false. If there are no events in the event queue, then the behavior depends on the stopWhenQueueIsEmpty parameter. If it is false, then this thread will stall until events become available on the event queue. Otherwise, time will advance to the stop time and the execution will halt.

Specified by:
fire in interface Executable
Overrides:
fire in class DEDirector
Throws:
IllegalActionException - If the firing actor throws it.

newReceiver

public Receiver newReceiver()
Return a new receiver of a type HDEReceiver.

Overrides:
newReceiver in class DEDirector
Returns:
A new HDEReceiver.