ptolemy.actor.process
Class ProcessDirector

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

public class ProcessDirector
extends Director

The base class for directors for the process oriented domains. It provides default implementations for methods that are common across such domains.

In the process oriented domains, the director controlling a model needs to keep track of the state of the model. In particular it needs to maintain an accurate count of the number of active processes under its control and any processes that are blocked for whatever reason (trying to read from an empty channel as in PN). These counts, and perhaps other counts, are needed by the director to control and respond when deadlock is detected (no processes can make progress), or to respond to requests from higher in the hierarchy.

The methods that control how the director detects and responds to deadlocks are _areActorsDeadlocked() and _resolveDeadlock(). These methods should be overridden in derived classes to get domain-specific behaviour. The implementations given here are trivial and suffice only to illustrate the approach that should be followed.

This base class is not sufficient for executing hierarchical, heterogeneous models. In order to accommodate hierarchical, heterogeneity the subclass CompositeProcessDirector must be used.

Since:
Ptolemy II 0.2
Version:
$Id: ProcessDirector.java,v 1.152.2.1 2004/06/18 00:48:59 cxh Exp $
Author:
Mudit Goel, Neil Smyth, John S. Davis II
See Also:
Director, Serialized Form
Accepted Rating:
Yellow (mudit)
Proposed Rating:
Green (mudit)

Nested Class Summary
 
Nested classes inherited from class ptolemy.kernel.util.NamedObj
NamedObj.ContainedObjectsIterator
 
Field Summary
protected  boolean _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
ProcessDirector()
          Construct a director in the default workspace with an empty string as its name.
ProcessDirector(CompositeEntity container, java.lang.String name)
          Construct a director in the given container with the given name.
ProcessDirector(Workspace workspace)
          Construct a director in the workspace with an empty name.
 
Method Summary
protected  void _actorBlocked(java.util.LinkedList receivers)
          Increase the count of blocked actors by one and register the receivers that instigated the newly blocked actor.
protected  void _actorBlocked(ProcessReceiver receiver)
          Increase the count of blocked actors by one and register the receiver that instigated the newly blocked actor.
protected  void _actorHasRestarted()
          Decrease the count of stopped actors by one.
protected  void _actorHasStopped()
          Increase the count of stopped actors by one.
protected  void _actorUnBlocked(java.util.LinkedList receivers)
          Decrease the count of blocked actors by one and unregister the receivers that were previously blocked.
protected  void _actorUnBlocked(ProcessReceiver receiver)
          Decrease the count of blocked actors by one and unregister the receiver that was previously blocked.
protected  void _addNewThread(ProcessThread thread)
          Add a thread to the list of threads in the model.
protected  boolean _areActorsDeadlocked()
          Return true if the count of active processes in the container is 0.
protected  boolean _areAllActorsStopped()
          Return true if the count of active processes equals the number of stopped threads.
protected  void _decreaseActiveCount()
          Decrease by one the count of active processes under the control of this director.
protected  long _getActiveActorsCount()
          Return the number of active processes under the control of this director.
protected  int _getBlockedActorsCount()
          Return the number of actors that are currently blocked.
protected  ProcessThread _getProcessThread(Actor actor, ProcessDirector director)
          Create a new ProcessThread for controlling the actor that is passed as a parameter of this method.
protected  int _getStoppedActorsCount()
          Return the number of actors that are currently stopped.
protected  void _increaseActiveCount()
          Increases the count of active actors in the composite actor corresponding to this director by 1.
protected  boolean _resolveDeadlock()
          Return false indicating that deadlock has not been resolved and that execution will be discontinued.
 java.lang.Object clone(Workspace workspace)
          Clone the director into the specified workspace.
 void fire()
          Wait until a deadlock is detected.
 void initialize()
          Invoke the initialize() methods of all the deeply contained actors in the container (a composite actor) of this director.
 void initialize(Actor actor)
          Initialize the given actor.
 boolean isStopFireRequested()
          Return true if a stop has been requested on the director.
 boolean isStopRequested()
          Return true if a stop has been requested on the director.
 Receiver newReceiver()
          Return a new receiver of a type compatible with this director.
 boolean postfire()
          Return false if a stop has been requested or if the model has reached deadlock.
 boolean prefire()
          Start threads for all actors that have not had threads started already (this might include actors initialized since the last invocation of prefire).
 void preinitialize()
          Preinitialize the model controlled by this director.
 void stop()
          Request that the director cease execution altogether.
 void stopFire()
          Request that execution stop at the conclusion of the current iteration.
 void terminate()
          Terminates all threads under control of this director immediately.
 boolean transferInputs(IOPort port)
          Throw an IllegalActionException as an indication that this method should not be used within process domains.
 boolean transferOutputs(IOPort port)
          Throw an IllegalActionException as an indication that this method should not be used within process domains.
 void wrapup()
          End the execution of the model under the control of this director.
 
Methods inherited from class ptolemy.actor.Director
_description, _isEmbedded, _isTopLevel, _writeAccessRequired, domainPolymorphicTransferInputs, domainPolymorphicTransferOutputs, fireAt, fireAtCurrentTime, getCurrentTime, 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

_notDone

protected boolean _notDone
Constructor Detail

ProcessDirector

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


ProcessDirector

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

ProcessDirector

public ProcessDirector(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 - The container
name - Name of this director.
Throws:
IllegalActionException - If the name contains a period, or 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 (It must be added by the user if he wants it to be there). The result is a new director with no container, no pending mutations, and no topology listeners. The count of active processes is zero.

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

fire

public void fire()
          throws IllegalActionException
Wait until a deadlock is detected. Then deal with the deadlock by calling the protected method _resolveDeadlock() and return. This method is synchronized on the director.

Specified by:
fire in interface Executable
Overrides:
fire in class Director
Throws:
IllegalActionException - If a derived class throws it.

initialize

public void initialize()
                throws IllegalActionException
Invoke the initialize() methods of all the deeply contained actors in the container (a composite actor) of this director. These are expected to call initialize(Actor), which will result in the creation of a new thread for each actor. Also, set current time to 0.0, or to the current time of the executive director of the container, if there is one.

Specified by:
initialize in interface Executable
Overrides:
initialize in class Director
Throws:
IllegalActionException - If the initialize() method of one of the deeply contained actors throws it.

initialize

public void initialize(Actor actor)
                throws IllegalActionException
Initialize the given actor. This class overrides the base class to reset the flags for all of the receivers, and to create a new ProcessThread for each actor being controlled. This class does *NOT* directly call the initialize method of the actor. That method is instead called by the actor's thread itself. This allows actors in process domains to create tokens during initialization, since sending data in a process-based domain requires threads for each actor.

Overrides:
initialize in class Director
Throws:
IllegalActionException - If the actor is not acceptable to the domain. Not thrown in this base class.

isStopRequested

public boolean isStopRequested()
Return true if a stop has been requested on the director. This is used by the ProcessThread to tell the difference between a request to pause and a request to stop.

Returns:
True if stop() has been called.

isStopFireRequested

public boolean isStopFireRequested()
Return true if a stop has been requested on the director. This is used by the ProcessThread to tell the difference between a request to pause and a request to stop.

Returns:
True if stop() has been called.

newReceiver

public Receiver newReceiver()
Return a new receiver of a type compatible with this director. In class, this returns a new Mailbox.

Overrides:
newReceiver in class Director
Returns:
A new Mailbox.

postfire

public boolean postfire()
                 throws IllegalActionException
Return false if a stop has been requested or if the model has reached deadlock. Return true otherwise.

Specified by:
postfire in interface Executable
Overrides:
postfire in class Director
Returns:
False if the director has detected a deadlock or a stop has been requested.
Throws:
IllegalActionException - If a derived class throws it.

prefire

public boolean prefire()
                throws IllegalActionException
Start threads for all actors that have not had threads started already (this might include actors initialized since the last invocation of prefire). This starts the threads, corresponding to all the actors, that were created in the initialize() method.

Specified by:
prefire in interface Executable
Overrides:
prefire in class Director
Returns:
true.
Throws:
IllegalActionException - If a derived class throws it.

preinitialize

public void preinitialize()
                   throws IllegalActionException
Preinitialize the model controlled by this director. This subclass overrides the base class to initialize the number of running threads before proceeding with preinitialization of the model.

Specified by:
preinitialize in interface Executable
Overrides:
preinitialize in class Director
Throws:
IllegalActionException - If creating an actor thread throws it.

stop

public void stop()
Request that the director cease execution altogether. This causes a call to stop() on all actors contained by the container of this director, and a call to stopThread() on each of the process threads that contain actors controlled by this director. This also sets a flag so that the next call to postfire() returns false.

Specified by:
stop in interface Executable
Overrides:
stop in class Director

stopFire

public void stopFire()
Request that execution stop at the conclusion of the current iteration. Call stopThread() on each of the process threads that contain actors controlled by this director and call stopFire() on the actors that are contained by these threads. This method is non-blocking.

Specified by:
stopFire in interface Executable
Overrides:
stopFire in class Director

terminate

public void terminate()
Terminates all threads under control of this director immediately. This abrupt termination will not allow normal cleanup actions to be performed, and the model should be recreated after calling this method.

Specified by:
terminate in interface Executable
Overrides:
terminate in class Director

transferInputs

public boolean transferInputs(IOPort port)
                       throws IllegalActionException
Throw an IllegalActionException as an indication that this method should not be used within process domains.

Overrides:
transferInputs in class Director
Parameters:
port - The port to transfer tokens from.
Returns:
True if at least one data token is transferred.
Throws:
IllegalActionException - Always thrown. This method should not be invoked within the process domains.
See Also:
IOPort.transferInputs()

transferOutputs

public boolean transferOutputs(IOPort port)
                        throws IllegalActionException
Throw an IllegalActionException as an indication that this method should not be used within process domains.

Overrides:
transferOutputs in class Director
Parameters:
port - The port to transfer tokens from.
Returns:
True if at least one data token is transferred.
Throws:
IllegalActionException - Always thrown. This method should not be invoked within the process domains.
See Also:
IOPort.transferOutputs()

wrapup

public void wrapup()
            throws IllegalActionException
End the execution of the model under the control of this director. A flag is set in all the receivers that causes each process to terminate at the earliest communication point. Prior to setting receiver flags, this method wakes up the threads if they all are stopped. If the container is not an instance of CompositeActor, then this method does nothing.

This method is not synchronized on the workspace, so the caller should be.

Specified by:
wrapup in interface Executable
Overrides:
wrapup in class Director
Throws:
IllegalActionException - If an error occurs while accessing the receivers of all actors under the control of this director.

_actorBlocked

protected void _actorBlocked(ProcessReceiver receiver)
Increase the count of blocked actors by one and register the receiver that instigated the newly blocked actor. This method may be overridden in derived classes to added domain specific functionality. Implementations of this method must be synchronized.

Parameters:
receiver - The receiver whose data transfer is blocked.

_actorBlocked

protected void _actorBlocked(java.util.LinkedList receivers)
Increase the count of blocked actors by one and register the receivers that instigated the newly blocked actor. This method may be overridden in derived classes to added domain specific functionality. Implementations of this method must be synchronized.

Parameters:
receivers - The receivers whose data transfer is blocked.

_actorHasStopped

protected void _actorHasStopped()
Increase the count of stopped actors by one. This method is called by instances of ProcessThread in response to a call to their stopThread() method. This method may be overridden in derived classes to added domain specific functionality. Implementations of this method must be synchronized.


_actorHasRestarted

protected void _actorHasRestarted()
Decrease the count of stopped actors by one. This method is called by instances of ProcessThread after detecting that the stopFire() flag has been cleared. This method may be overridden in derived classes to added domain specific functionality. Implementations of this method must be synchronized.


_actorUnBlocked

protected void _actorUnBlocked(ProcessReceiver receiver)
Decrease the count of blocked actors by one and unregister the receiver that was previously blocked. This method may be overridden in derived classes to added domain specific functionality. Implementations of this method must be synchronized.

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

_actorUnBlocked

protected void _actorUnBlocked(java.util.LinkedList receivers)
Decrease the count of blocked actors by one and unregister the receivers that were previously blocked. This method may be overridden in derived classes to added domain specific functionality. Implementations of this method must be synchronized.

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

_addNewThread

protected void _addNewThread(ProcessThread thread)
Add a thread to the list of threads in the model. This list is used in case of abrupt termination of the model.

Parameters:
thread - The newly created thread.

_areActorsDeadlocked

protected boolean _areActorsDeadlocked()
Return true if the count of active processes in the container is 0. Otherwise return false. Derived classes must override this method to return true to any other forms of deadlocks that they might introduce.

Returns:
true if there are no active processes in the container.

_areAllActorsStopped

protected boolean _areAllActorsStopped()
Return true if the count of active processes equals the number of stopped threads. Otherwise return false.

Returns:
true if there are no active processes in the container.

_decreaseActiveCount

protected void _decreaseActiveCount()
Decrease by one the count of active processes under the control of this director. This method should be called only when an active thread that was registered using _increaseActiveCount() is terminated. This count is used to detect deadlocks for termination and other reasons.


_getActiveActorsCount

protected final long _getActiveActorsCount()
Return the number of active processes under the control of this director.

Returns:
The number of active actors.

_getBlockedActorsCount

protected final int _getBlockedActorsCount()
Return the number of actors that are currently blocked.

Returns:
Return the number of actors that are currently blocked.

_getStoppedActorsCount

protected final int _getStoppedActorsCount()
Return the number of actors that are currently stopped.

Returns:
Return the number of actors that are currently stopped.

_getProcessThread

protected ProcessThread _getProcessThread(Actor actor,
                                          ProcessDirector director)
                                   throws IllegalActionException
Create a new ProcessThread for controlling the actor that is passed as a parameter of this method. Subclasses are encouraged to override this method as necessary for domain specific functionality.

Parameters:
actor - The actor that the created ProcessThread will control.
director - The director that manages the model that the created thread is associated with.
Returns:
Return a new ProcessThread that will control the actor passed as a parameter for this method.
Throws:
IllegalActionException

_increaseActiveCount

protected void _increaseActiveCount()
Increases the count of active actors in the composite actor corresponding to this director by 1. This method should be called when a new thread corresponding to an actor is started in the model under the control of this director. This method is required for detection of deadlocks. The corresponding method _decreaseActiveCount should be called when the thread is terminated.


_resolveDeadlock

protected boolean _resolveDeadlock()
                            throws IllegalActionException
Return false indicating that deadlock has not been resolved and that execution will be discontinued. In derived classes, override this method to obtain domain specific handling of deadlocks. Return false if a real deadlock has occurred and the simulation can be ended. Return true if the simulation can proceed given additional data and need not be terminated.

Returns:
False.
Throws:
IllegalActionException - Not thrown in this base class.