ptolemy.domains.dde.kernel
Class DDEDirector

java.lang.Object
  extended byptolemy.kernel.util.NamedObj
      extended byptolemy.kernel.util.Attribute
          extended byptolemy.actor.Director
              extended byptolemy.actor.process.ProcessDirector
                  extended byptolemy.actor.process.CompositeProcessDirector
                      extended byptolemy.domains.dde.kernel.DDEDirector
All Implemented Interfaces:
Changeable, java.lang.Cloneable, Debuggable, DebugListener, Derivable, Executable, ModelErrorHandler, MoMLExportable, Nameable, java.io.Serializable

public class DDEDirector
extends CompositeProcessDirector

A DDEDirector governs the execution of actors operating according to the DDE model of computation (MoC). The DDE MoC incorporates a distributed notion of time into a dataflow style communication semantic. Blocking reads occur if attempts to consume data are made when the corresponding receiver is empty and blocking writes occur if attempts to produce data are made when the corresponding receiver is full.

In conjunction with the blocking read/write facilities, the DDE domain uses a distributed, local notion of time. In a network of actors governed by a DDEDirector each actor has a local notion of time. Several features of the DDEDirector are intended to facilitate these local notions of time.

All DDE models have a completion time. The completion time is a preset time after which all execution ceases. The completion time for a DDEDirector is specified via the stopTime parameter. The value of the stopTime parameter is passed to the receivers of all actors that the DDEDirector governs via newReceiver() during initialize(). After initialize() has been called, the value of stopTime can not be changed.

The default value of the stopTime parameter is PrioritizedTimedQueue.ETERNITY. Given this value, a DDE model will continue executing without regard for a completion time.

Deadlock due to feedback loops is dealt with via NullTokens. When an actor in a DDE model receives a NullToken, it may advance its local time value even though no computation results directly from consumption of the NullToken. For models with feedback topologies, the FeedBackDelay actor should be used in the feedback loop.

The DDE model of computation assumes that valid time stamps have non-negative values. Three special purpose negative time values are reserved with the following meanings. The value of PrioritizedTimedQueue.INACTIVE is reserved to indicate the termination of a receiver. The value of PrioritizedTimedQueue.ETERNITY is reserved to indicate that a receiver has not begun to participate in a model's execution. The value of PrioritizedTimedQueue.IGNORE is reserved to indicate that the current token at the head of a DDEReceiver should be ignored in favor of the tokens contained in the other receivers of the actor in question. More details of IGNORE can be found in FeedBackDelay.

NOTE: The current implementation of this director does not include an infrastructure for mutations. Hence, ChangeRequest and other facilities for changing the topology of a model are not included in this director.

Since:
Ptolemy II 0.3
Version:
$Id: DDEDirector.java,v 1.96 2004/04/13 05:13:11 cxh Exp $
Author:
John S. Davis II, Mudit Goel
See Also:
PNDirector, FeedBackDelay, NullToken, Serialized Form
Accepted Rating:
Red (cxh)
Proposed Rating:
Red (davisj)

Nested Class Summary
 
Nested classes inherited from class ptolemy.kernel.util.NamedObj
NamedObj.ContainedObjectsIterator
 
Field Summary
 Parameter stopTime
          The stopTime parameter specifies the completion time of a model's execution.
 
Fields inherited from class ptolemy.actor.process.ProcessDirector
_notDone
 
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
DDEDirector()
          Construct a DDEDirector in the default workspace with an empty string as its name.
DDEDirector(CompositeEntity container, java.lang.String name)
          Construct a director in the given container with the given name.
DDEDirector(Workspace workspace)
          Construct a director in the workspace with an empty string as a name.
 
Method Summary
protected  void _actorBlocked(java.util.LinkedList receivers)
          Register the receivers that instigated the newly blocked actor.
protected  void _actorBlocked(ProcessReceiver receiver)
          Register the receiver that instigated the newly blocked actor and increment the count of blocked actors by one.
protected  void _actorUnBlocked(DDEReceiver receiver)
          Unregister the specified receiver that was previously blocked and decrement the count of blocked actors by one.
protected  void _actorUnBlocked(java.util.LinkedList receivers)
          Call _actorsUnblocked(DDEReceivers) on each element of the list.
protected  ProcessThread _getProcessThread(Actor actor, ProcessDirector director)
          Return a new ProcessThread of a type compatible with this director.
protected  void _incrementLowestCapacityPort()
          Increment the port capacity's according to Tom Parks' algorithm.
protected  boolean _resolveInternalDeadlock()
          Apply an algorithm to resolve an internal deadlock and return true if the algorithm is successful.
 void fireAt(Actor actor, double time)
          Schedule an actor to be fired at the specified time.
 double getCurrentTime()
          Return the current time of the DDEThread that calls this method on behalf of an actor.
 boolean hasMutation()
          Return false indicating that none of the actors governed by this director have a mutation.
 void initialize()
          Initialize this director and the actors it contains and set variables to their initial values.
 Receiver newReceiver()
          Return a new receiver of a type compatible with this director.
 boolean postfire()
          Return true if the actors governed by this director can continue execution, and false otherwise.
 
Methods inherited from class ptolemy.actor.process.CompositeProcessDirector
_actorUnBlocked, _areActorsDeadlocked, _areActorsExternallyBlocked, _controllerBlocked, _controllerUnBlocked, _isInputControllerBlocked, _isOutputControllerBlocked, _registerBlockedReceiversWithExecutive, _resolveDeadlock, clone, createBranchController, getInputController, getOutputController, prefire, stopInputBranchController, stopOutputBranchController, wrapup
 
Methods inherited from class ptolemy.actor.process.ProcessDirector
_actorHasRestarted, _actorHasStopped, _addNewThread, _areAllActorsStopped, _decreaseActiveCount, _getActiveActorsCount, _getBlockedActorsCount, _getStoppedActorsCount, _increaseActiveCount, fire, initialize, isStopFireRequested, isStopRequested, preinitialize, stop, stopFire, terminate, transferInputs, transferOutputs
 
Methods inherited from class ptolemy.actor.Director
_description, _isEmbedded, _isTopLevel, _writeAccessRequired, domainPolymorphicTransferInputs, domainPolymorphicTransferOutputs, fireAtCurrentTime, getNextIterationTime, getTimeResolution, invalidateResolvedTypes, invalidateSchedule, iterate, needWriteAccess, requestInitialization, setContainer, setCurrentTime, setTimeResolution
 
Methods inherited from class ptolemy.kernel.util.Attribute
_getContainedObject, _propagateExistence, 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, addDebugListener, attributeChanged, 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, removeDebugListener, 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

stopTime

public Parameter stopTime
The stopTime parameter specifies the completion time of a model's execution. During the initialize() method the value of this parameter is passed to all receivers governed by this director. The default value of stopTime is PrioritizedTimedQueue.ETERNITY indicating that execution will continue indefinitely.

Constructor Detail

DDEDirector

public DDEDirector()
            throws IllegalActionException,
                   NameDuplicationException
Construct a DDEDirector 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.


DDEDirector

public DDEDirector(Workspace workspace)
            throws IllegalActionException,
                   NameDuplicationException
Construct a director in the workspace with an empty string as a 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.

DDEDirector

public DDEDirector(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. The given name must be unique with respect to the container. If the name argument is null, then the name is set to the empty string. Increment the version number of the workspace.

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

getCurrentTime

public double getCurrentTime()
Return the current time of the DDEThread that calls this method on behalf of an actor. If this method is called by other than a DDEThread, then return the current time as specified by the superclass of this method.

Overrides:
getCurrentTime in class Director
Returns:
The current time of the DDEThread that calls this method.

fireAt

public void fireAt(Actor actor,
                   double time)
            throws IllegalActionException
Schedule an actor to be fired at the specified time. If the thread that calls this method is an instance of DDEThread, then the specified actor must be contained by this thread. If the thread that calls this method is not an instance of DDEThread, then store the actor and refire time in the initial time table of this director.

NOTE: The current implementation of this method is such that a more appropriate name might be continueAt() rather than fireAt().

Overrides:
fireAt in class Director
Parameters:
actor - The actor scheduled to fire.
time - The scheduled time to fire.
Throws:
IllegalActionException - If the specified time is in the past or if the thread calling this method is a DDEThread but the specified actor is not contained by the DDEThread.

hasMutation

public boolean hasMutation()
Return false indicating that none of the actors governed by this director have a mutation. Note that the DDE domain is not equipped to properly handle mutations.

Returns:
False.

initialize

public void initialize()
                throws IllegalActionException
Initialize this director and the actors it contains and set variables to their initial values. Create a DDEThread for each actor that this director controls but do not start the thread.

Specified by:
initialize in interface Executable
Overrides:
initialize in class CompositeProcessDirector
Throws:
IllegalActionException - If there is an error during the creation of the threads or initialization of the actors.

newReceiver

public Receiver newReceiver()
Return a new receiver of a type compatible with this director. If the completion time of this director has been explicitly set to a particular value then set the completion time of the receiver to this same value; otherwise set the completion time to PrioritizedTimedQueue.ETERNITY which indicates that the receivers should ignore the completion time.

Overrides:
newReceiver in class CompositeProcessDirector
Returns:
A new DDEReceiver.

postfire

public boolean postfire()
                 throws IllegalActionException
Return true if the actors governed by this director can continue execution, and false otherwise. Continuation of execution is dependent upon whether the system is deadlocked in a manner that can not be resolved even if external communication occurs. If stop() has been called, then return false.

Specified by:
postfire in interface Executable
Overrides:
postfire in class ProcessDirector
Returns:
True if execution can continue; false otherwise.
Throws:
IllegalActionException - Not thrown in this base class. May be thrown in derived classes.

_actorBlocked

protected void _actorBlocked(ProcessReceiver receiver)
Register the receiver that instigated the newly blocked actor and increment the count of blocked actors by one. Note whether the receiver is read blocked or write blocked.

Overrides:
_actorBlocked in class CompositeProcessDirector
Parameters:
receiver - The receiver whose data transfer is blocked.

_actorBlocked

protected void _actorBlocked(java.util.LinkedList receivers)
Register the receivers that instigated the newly blocked actor. and increment the count of blocked actors by one. Note whether the receivers are read blocked or write blocked.

Overrides:
_actorBlocked in class CompositeProcessDirector
Parameters:
receivers - The receivers whose data transfer is blocked.

_actorUnBlocked

protected void _actorUnBlocked(java.util.LinkedList receivers)
Call _actorsUnblocked(DDEReceivers) on each element of the list. Implementations of this method must be synchronized.

Overrides:
_actorUnBlocked in class CompositeProcessDirector
Parameters:
receivers - A list of DDEReceivers to unblock.

_actorUnBlocked

protected void _actorUnBlocked(DDEReceiver receiver)
Unregister the specified receiver that was previously blocked and decrement the count of blocked actors by one.

Parameters:
receiver - The receiver whose data transfer was previously blocked.

_getProcessThread

protected ProcessThread _getProcessThread(Actor actor,
                                          ProcessDirector director)
                                   throws IllegalActionException
Return a new ProcessThread of a type compatible with this director.

Overrides:
_getProcessThread in class ProcessDirector
Parameters:
actor - The actor that the new ProcessThread will control.
director - The director that manages the new ProcessThread.
Returns:
Return a new ProcessThread that will control the actor passed as a parameter for this method.
Throws:
IllegalActionException - If an error occurs while instantiating the new ProcessThread.

_incrementLowestCapacityPort

protected void _incrementLowestCapacityPort()
                                     throws IllegalActionException
Increment the port capacity's according to Tom Parks' algorithm. Select the port with the smallest capacity and double the capacity.

Throws:
IllegalActionException - If there is an error while attempting to set the capacity of a DDE receiver.

_resolveInternalDeadlock

protected boolean _resolveInternalDeadlock()
                                    throws IllegalActionException
Apply an algorithm to resolve an internal deadlock and return true if the algorithm is successful. If the algorithm is unsuccessful then return false. The algorithm applied was created by Thomas Parks for resolving internal deadlocks in which one or more actors are write blocked.

Overrides:
_resolveInternalDeadlock in class CompositeProcessDirector
Returns:
True if an internal deadlock has been resolved; otherwise return false.
Throws:
IllegalActionException - Not thrown in this base class.