ptolemy.domains.csp.kernel
Class CSPDirector

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.csp.kernel.CSPDirector
All Implemented Interfaces:
Changeable, java.lang.Cloneable, Debuggable, DebugListener, Derivable, Executable, ModelErrorHandler, MoMLExportable, Nameable, java.io.Serializable

public class CSPDirector
extends CompositeProcessDirector

CSPDirector governs the execution of a composite actor with the semantics of the Communicating Sequential Processes (CSP) domain.

In the CSP domain, the director creates a thread for executing each actor under its control. Each actor corresponds to a process in the model. The threads are created in the initialize method and started in the prefire method. After the thread for an actor is started it is active until the thread finishes. While the process is active, it can also be blocked or delayed, but not both. A process is blocked if it is trying to communicate but the process with which it is trying to communicate is not ready to do so yet. A process is delayed if it is waiting for time to advance, or if it is waiting for a deadlock to occur.

The director is responsible for handling deadlocks, both real and timed. It is also responsible for carrying out any requests for changes to the topology that have been made when a deadlock occurs. It maintains counts of the number of active processes, the number of blocked processes, and the number of delayed processes. Deadlock occurs when the number of blocked processes plus the number of delayed processes equals the number of active processes. Time deadlock occurs if at least one of the active processes is delayed. Real deadlock occurs if all of the active processes under the control of this director are blocked trying to communicate. The fire method controls and responds to deadlocks and carries out changes to the topology when it is appropriate.

If real deadlock occurs, the fire method returns. If there are no levels above this level in the hierarchy then this marks the end of execution of the model. The model execution is terminated by setting a flag in every receiver contained in actors controlled by this director. When a process tries to send or receive from a receiver with the terminated flag set, a TerminateProcessException is thrown which causes the actors execution thread to terminate.

Time is controlled by the director. Each process can delay for some delta time, and it will continue when the director has advanced time by that length of time from the current time. A process is delayed by calling delay(double) method. The director advances time each occasion a time deadlock occurs and no changes to the topology are pending. If a process specifies zero delay, then the process continues immediately. A process may delay itself until the next time deadlock occurs by calling waitForDeadlock(). Then the next occasion time deadlock occurs, the director wakes up any processes waiting for deadlock, and does not advance the current time. Otherwise the current model time is increased as well as being advanced. By default the model of computation used in the CSP domain is timed. To use CSP without a notion of time, do not use the delay(double) method in any process.

Changes to the topology can occur when deadlock, real or timed, is reached. The director carries out any changes that have been queued with it. Note that the result of the topology changes may remove the deadlock that caused the changes to be carried out.

Since:
Ptolemy II 0.2
Version:
$Id: CSPDirector.java,v 1.103 2004/04/13 05:12:58 cxh Exp $
Author:
Neil Smyth, Mudit Goel, John S. Davis II
See Also:
Director, Serialized Form
Accepted Rating:
Green (kienhuis)
Proposed Rating:
Green (nsmyth)

Nested Class Summary
 
Nested classes inherited from class ptolemy.kernel.util.NamedObj
NamedObj.ContainedObjectsIterator
 
Field Summary
 
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
CSPDirector()
          Construct a director in the default workspace with an empty string as its name.
CSPDirector(CompositeEntity container, java.lang.String name)
          Construct a director in the given container with the given name.
CSPDirector(Workspace workspace)
          Construct a director in the workspace with an empty name.
 
Method Summary
protected  void _actorBlocked(CSPReceiver receiver)
          Increase the count of blocked processes and check if the actors are deadlocked or stopped.
protected  void _actorDelayed(double delta, CSPActor actor)
          Called by a CSPActor when it wants to delay.
protected  void _actorUnBlocked(CSPReceiver receiver)
          An actor has unblocked, decrease the count of blocked actors.
protected  boolean _areActorsDeadlocked()
          Returns true if all active processes are either blocked or delayed, false otherwise.
protected  boolean _resolveInternalDeadlock()
          Determines how the director responds when a deadlock is detected.
 java.lang.Object clone(Workspace workspace)
          Clone the director into the specified workspace.
 void initialize()
          Reset flags to initialize values.
 Receiver newReceiver()
          Return a new CSPReceiver compatible with this director.
 boolean postfire()
          Return false if deadlock has occurred and there are no input ports, or if stop() has been called, and true otherwise.
 void setCurrentTime(double newTime)
          Set the current model time.
 void wrapup()
          Override the base class to stop any actors that might be stalled in a call to delay().
 
Methods inherited from class ptolemy.actor.process.CompositeProcessDirector
_actorBlocked, _actorBlocked, _actorUnBlocked, _actorUnBlocked, _areActorsExternallyBlocked, _controllerBlocked, _controllerUnBlocked, _isInputControllerBlocked, _isOutputControllerBlocked, _registerBlockedReceiversWithExecutive, _resolveDeadlock, createBranchController, getInputController, getOutputController, prefire, stopInputBranchController, stopOutputBranchController
 
Methods inherited from class ptolemy.actor.process.ProcessDirector
_actorHasRestarted, _actorHasStopped, _addNewThread, _areAllActorsStopped, _decreaseActiveCount, _getActiveActorsCount, _getBlockedActorsCount, _getProcessThread, _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, fireAt, fireAtCurrentTime, getCurrentTime, getNextIterationTime, getTimeResolution, invalidateResolvedTypes, invalidateSchedule, iterate, needWriteAccess, requestInitialization, setContainer, 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
 

Constructor Detail

CSPDirector

public CSPDirector()
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.


CSPDirector

public CSPDirector(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.

CSPDirector

public CSPDirector(CompositeEntity container,
                   java.lang.String name)
            throws IllegalActionException,
                   NameDuplicationException
Construct a director in the given container with the given name. If 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

clone

public java.lang.Object clone(Workspace workspace)
                       throws java.lang.CloneNotSupportedException
Clone the director into the specified workspace. The new object is not added to the directory of that workspace (you must do this yourself if you want it there). The result is a new director with no container, no pending changes to the topology, current time is 0.0, and no actors are delayed or blocked.

Overrides:
clone in class CompositeProcessDirector
Parameters:
workspace - The workspace for the cloned object.
Returns:
The new CSPDirector.
Throws:
java.lang.CloneNotSupportedException - If one of the attributes cannot be cloned.

initialize

public void initialize()
                throws IllegalActionException
Reset flags to initialize values.

Specified by:
initialize in interface Executable
Overrides:
initialize in class CompositeProcessDirector
Throws:
IllegalActionException - If the super class throws it.

newReceiver

public Receiver newReceiver()
Return a new CSPReceiver compatible with this director. In the CSP domain, we use CSPReceivers.

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

postfire

public boolean postfire()
Return false if deadlock has occurred and there are no input ports, or if stop() has been called, and true otherwise.

Specified by:
postfire in interface Executable
Overrides:
postfire in class ProcessDirector
Returns:
False if no more execution is possible, and true otherwise.

setCurrentTime

public void setCurrentTime(double newTime)
                    throws IllegalActionException
Set the current model time. It is intended for use when composing CSP with other timed domains.

This method should only be called when no processes are delayed, as the director stores the model time at which to resume them. If the current model time changed while one or more processes are delayed, then the state of the director would be undefined as the resumption time of the delayed processes would not be comparable with the new model time.

Overrides:
setCurrentTime in class Director
Parameters:
newTime - The new current model time.
Throws:
IllegalActionException - If one or more processes are delayed.

wrapup

public void wrapup()
            throws IllegalActionException
Override the base class to stop any actors that might be stalled in a call to delay().

Specified by:
wrapup in interface Executable
Overrides:
wrapup in class CompositeProcessDirector
Throws:
IllegalActionException - If the parent class throws it.

_actorBlocked

protected void _actorBlocked(CSPReceiver receiver)
Increase the count of blocked processes and check if the actors are deadlocked or stopped.


_actorDelayed

protected void _actorDelayed(double delta,
                             CSPActor actor)
                      throws InvalidStateException
Called by a CSPActor when it wants to delay. When the director has advanced time to "getCurrentTime() + delta", the process corresponding to the actor will continue. Note that actors can only deal with delta time.

The method waitForDeadlock() in CSPActor calls this method with a zero argument. Thus the process will continue the next occasion time deadlock occurs. *

Parameters:
delta - The length of time to delay the actor.
actor - The actor being delayed.
Throws:
InvalidStateException - If an actor is delayed for negative time.

_actorUnBlocked

protected void _actorUnBlocked(CSPReceiver receiver)
An actor has unblocked, decrease the count of blocked actors.


_areActorsDeadlocked

protected boolean _areActorsDeadlocked()
Returns true if all active processes are either blocked or delayed, false otherwise.

Overrides:
_areActorsDeadlocked in class CompositeProcessDirector
Returns:
false If the number of blocked processes is less than the number of active actors; return true otherwise.

_resolveInternalDeadlock

protected boolean _resolveInternalDeadlock()
Determines how the director responds when a deadlock is detected. It is where nearly all the control for the model at this level in the hierarchy is located.

Deadlock occurs if the number of blocked and delayed processes equals the number of active processes. The method looks for three cases in the following order: are there topology changes waiting to happen, are there any processes delayed, are all the processes blocked trying to rendezvous.

If there are changes to the topology waiting to happen, they are performed and the execution of the model continues. Note that the result of performing the topology changes may be to remove the deadlock that had occurred.

If the number of delayed processes is greater than zero, then time deadlock has occurred. If one or more processes are delayed waiting for deadlock to occur, then those processes are resumed and time is not advanced. Otherwise time is advanced and the earliest delayed process is resumed. Current time is defined as the double value returned by getCurrentTime() plus/minus 10e-10.

If all the processes are blocked, then real deadlock has occurred, and this method returns false. If there are no levels above this one in the hierarchy, then real deadlock marks the end of executing the model.

Overrides:
_resolveInternalDeadlock in class CompositeProcessDirector
Returns:
False if real deadlock occurred, true otherwise.