ptolemy.domains.dde.kernel
Class DDEDirector

java.lang.Object
  ptolemy.kernel.util.NamedObj
      ptolemy.kernel.util.Attribute
          ptolemy.actor.Director
              ptolemy.actor.process.ProcessDirector
                  ptolemy.actor.process.CompositeProcessDirector
                      ptolemy.domains.dde.kernel.DDEDirector

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable, Executable, Initializable, TimedDirector, Changeable, Debuggable, DebugListener, Derivable, ModelErrorHandler, MoMLExportable, Moveable, Nameable

public class DDEDirector
extends CompositeProcessDirector
implements TimedDirector

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 57040 2010-01-27 20:52:32Z cxh $

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/interfaces inherited from class ptolemy.kernel.util.NamedObj

NamedObj.ContainedObjectsIterator

Field Summary

private Time	_completionTime The completion time.
private java.util.Hashtable	_initialTimeTable
private java.util.HashMap	_writeBlockedQueues The set of receivers blocked on a write to a receiver.
static boolean	READ_BLOCKED Indicator that a thread is read blocked.
Parameter	stopTime The stopTime parameter specifies the completion time of a model's execution.
static boolean	WRITE_BLOCKED Indicator that a thread is write blocked.

Fields inherited from class ptolemy.actor.process.ProcessDirector

_notDone, _stopFireRequested

Fields inherited from class ptolemy.actor.Director

_actorsFinishedExecution, _currentTime, _finishRequested, _initializables, _stopRequested, timeResolution

Fields inherited from class ptolemy.kernel.util.NamedObj

_changeListeners, _changeLock, _changeRequests, _debugging, _debugListeners, _elementName, _isPersistent, _verbose, _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

(package private) java.util.Hashtable	_getInitialTimeTable() Return the initial time table of this director.
protected void	_incrementLowestCapacityPort() Increment the port capacity's according to Tom Parks' algorithm.
protected ProcessThread	_newProcessThread(Actor actor, ProcessDirector director) Return a new ProcessThread of a type compatible with this director.
protected boolean	_resolveInternalDeadlock() Apply an algorithm to resolve an internal deadlock and return true if the algorithm is successful.
Dependency	delayDependency(double delay) Return a boolean dependency representing a model-time delay of the specified amount.
Time	fireAt(Actor actor, Time time) Schedule an actor to be fired at the specified time.
double	getCurrentTime() Deprecated. As of Ptolemy II 4.1, replaced by getModelTime()
Time	getModelTime() Return the current time of the DDEThread that calls this method on behalf of an actor.
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.
void	threadBlocked(java.lang.Thread thread, ProcessReceiver receiver, boolean readOrWrite) Notify the director that the specified thread is blocked on an I/O operation.
void	threadUnblocked(java.lang.Thread thread, ProcessReceiver receiver, boolean readOrWrite) Notify the director that the specified thread is unblocked on an I/O operation.

Methods inherited from class ptolemy.actor.process.CompositeProcessDirector

_areActorsExternallyBlocked, _areThreadsDeadlocked, _controllerBlocked, _controllerUnBlocked, _isInputControllerBlocked, _isOutputControllerBlocked, _resolveDeadlock, clone, createBranchController, getInputController, getOutputController, prefire, setModelTime, stopInputBranchController, stopOutputBranchController, threadBlocked, threadUnblocked, wrapup

Methods inherited from class ptolemy.actor.process.ProcessDirector

_areAllThreadsStopped, _getActiveThreadsCount, _getBlockedThreadsCount, _getStoppedThreadsCount, addThread, finish, fire, initialize, isStopFireRequested, isStopRequested, isThreadActive, preinitialize, removeThread, stop, stopFire, terminate, threadHasPaused, threadHasResumed, transferInputs, transferOutputs

Methods inherited from class ptolemy.actor.Director

_description, _fireContainerAt, _isEmbedded, _isTopLevel, _transferInputs, _transferOutputs, addInitializable, attributeChanged, createSchedule, defaultDependency, fireAt, fireAtCurrentTime, getCausalityInterface, getErrorTolerance, getGlobalTime, getModelNextIterationTime, getModelStartTime, getModelStopTime, getNextIterationTime, getStartTime, getStopTime, getTimeResolution, implementsStrictActorSemantics, invalidateResolvedTypes, invalidateSchedule, isFireFunctional, isStrict, iterate, preinitialize, removeInitializable, requestInitialization, setContainer, setCurrentTime, suggestedModalModelDirectors, supportMultirateFiring

Methods inherited from class ptolemy.kernel.util.Attribute

_checkContainer, _getContainedObject, _propagateExistence, getContainer, moveDown, moveToFirst, moveToIndex, moveToLast, moveUp, setName, updateContent

Methods inherited from class ptolemy.kernel.util.NamedObj

_addAttribute, _adjustOverride, _attachText, _cloneFixAttributeFields, _debug, _debug, _debug, _debug, _debug, _exportMoMLContents, _getIndentPrefix, _isMoMLSuppressed, _markContentsDerived, _propagateValue, _recordDecoratedAttributes, _removeAttribute, _splitName, _stripNumericSuffix, _validateSettables, addChangeListener, addDebugListener, attributeList, attributeList, attributeTypeChanged, clone, containedObjectsIterator, deepContains, depthInHierarchy, description, description, event, executeChangeRequests, exportMoML, exportMoML, exportMoML, exportMoML, exportMoML, exportMoMLPlain, getAttribute, getAttribute, getAttributes, getChangeListeners, getClassName, getDecoratorAttribute, getDecoratorAttributes, getDerivedLevel, getDerivedList, getDisplayName, getElementName, getFullName, getModelErrorHandler, getName, getName, getPrototypeList, getSource, handleModelError, isDeferringChangeRequests, isOverridden, isPersistent, lazyContainedObjectsIterator, message, propagateExistence, propagateValue, propagateValues, removeChangeListener, removeDebugListener, requestChange, setClassName, setDeferringChangeRequests, setDerivedLevel, setDisplayName, setModelErrorHandler, setPersistent, setSource, sortContainedObjects, toplevel, toString, uniqueName, validateSettables, workspace

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface ptolemy.actor.TimedDirector

getTimeResolution

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.

READ_BLOCKED

public static final boolean READ_BLOCKED

Indicator that a thread is read blocked.

See Also:

Constant Field Values

WRITE_BLOCKED

public static final boolean WRITE_BLOCKED

Indicator that a thread is write blocked.

See Also:

Constant Field Values

_completionTime

private Time _completionTime

The completion time. Since the completionTime is a constant, we do not convert it to a time object.

_writeBlockedQueues

private java.util.HashMap _writeBlockedQueues

The set of receivers blocked on a write to a receiver.

_initialTimeTable

private java.util.Hashtable _initialTimeTable

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.

Throws:

IllegalActionException - If the director is not compatible with the specified container.

NameDuplicationException - If thrown while adding a stopTime parameter.

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.

Throws:

IllegalActionException - If the director is not compatible with the specified container.

NameDuplicationException - If thrown while adding a stopTime parameter.

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

delayDependency

public Dependency delayDependency(double delay)

Return a boolean dependency representing a model-time delay of the specified amount.

Specified by:

delayDependency in interface TimedDirector

Parameters:

delay - A non-negative delay.

Returns:

A boolean dependency representing a delay.

fireAt

public Time fireAt(Actor actor,
                   Time 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.

Returns:

The time at which the actor passed as an argument will be fired.

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.

See Also:

Director.fireAtCurrentTime(Actor)

getCurrentTime

public double getCurrentTime()

Deprecated. As of Ptolemy II 4.1, replaced by getModelTime()

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.

See Also:

Director.setCurrentTime(double)

getModelTime

public Time getModelTime()

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.

Specified by:

getModelTime in interface TimedDirector

Overrides:

getModelTime in class Director

Returns:

The current time of the DDEThread that calls this method.

See Also:

Director.setModelTime(Time)

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 Initializable

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.

threadBlocked

public void threadBlocked(java.lang.Thread thread,
                          ProcessReceiver receiver,
                          boolean readOrWrite)

Notify the director that the specified thread is blocked on an I/O operation.

Parameters:

thread - The thread.

receiver - The receiver handling the I/O operation, or null if it is not a specific receiver.

readOrWrite - Either READ_BLOCKED or WRITE_BLOCKED to indicate whether the thread is blocked on read or write.

See Also:

CompositeProcessDirector.threadBlocked(Thread, ProcessReceiver)

threadUnblocked

public void threadUnblocked(java.lang.Thread thread,
                            ProcessReceiver receiver,
                            boolean readOrWrite)

Notify the director that the specified thread is unblocked on an I/O operation. If the thread has not been registered with threadBlocked(), then this call is ignored.

Parameters:

thread - The thread.

receiver - The receiver handling the I/O operation, or null if it is not a specific receiver.

readOrWrite - Either READ_BLOCKED or WRITE_BLOCKED to indicate whether the thread is blocked on read or write.

See Also:

CompositeProcessDirector.threadUnblocked(Thread, ProcessReceiver)

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

_newProcessThread

protected ProcessThread _newProcessThread(Actor actor,
                                          ProcessDirector director)
                                   throws IllegalActionException

Return a new ProcessThread of a type compatible with this director.

Overrides:

_newProcessThread in class ProcessDirector

Parameters:

actor - The actor that the new ProcessThread will control.

director - The director that manages the new ProcessThread.

Returns:

A new DDEThread.

Throws:

IllegalActionException - If an error occurs while instantiating the new ProcessThread.

_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 - If thrown while incrementing the lowest capacity port.

_getInitialTimeTable

java.util.Hashtable _getInitialTimeTable()

Return the initial time table of this director.

Returns:

The initial time table of this director.