ptolemy.actor.process
Class CompositeProcessDirector

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

public class CompositeProcessDirector
extends ProcessDirector

A baseclass for directors in process oriented domains that incorporate hierarchical heterogeneity. As with ProcessDirector CompositeProcessDirectors need to keep a count of the number of active processes and the number of processes that are blocked for any reason (e.g., trying to read from an empty channel in PN). CompositeProcessDirector is a subclass of ProcessDirector to facilitate models that consist of non-atomic actors.

A composite process director can be contained by an opaque composite actor that is contained by a composite actor. Ports contained by opaque composite actors are called opaque ports and such ports facilitate data transfer across the composite actor boundaries. A composite process director allocates two branch controllers to monitor data transfer in channels associated with opaque ports. The input branch controller monitors data transfer for channels associated with input opaque ports. The output branch controller monitors data transfer for channels associated with output opaque ports.

Associated with the channels of each opaque is a pair of process receivers. The producer receiver serves as the channel source and the consumer receiver serves as the channel destination. Each branch controller allocates a branch for each process receiver pair and when executing, a branch repeatedly attempts to transfer a single token from its producer receiver to its consumer receiver.

When a branch blocks while attempting to transfer data, it informs its branch controller by passing the branch controller the blocked receiver. If all of the branches of a controller have blocked, then we say that the branch controller is blocked and the branch controller informs the composite process director. In addition to monitoring the status of its branch controllers, a composite process director keeps track of the state of the actors that it contains. Actors can be internally or externally blocked. We say that an actor is externally blocked if it is blocked waiting to transfer tokens to or from a boundary port of its container actor. Actors that are blocked but not externally are said to be internally blocked.

Composite process directors monitor the state of the branch controllers and contained actors and when necessary invoke the _resolveDeadlock() method to deal with deadlocks. In the remainder of this paragraph we consider the case of a process-oriented opaque composite actor that is contained by another process-oriented opaque composite actor. If the actors contained by the inner composite actor are not blocked, then execution of the inner composite actor is allowed to continue independent of the state of the branch controllers. If the actors contained by the inner composite actor are internally blocked, then after the branch controllers have been deactivated, execution of the composite actor ends and postfire returns false indicating that successive iterations are not allowed. If the actors contained by the inner composite actor are externally blocked, then the composite process director waits until the branch controllers block (an inevitable condition) and registers the block with the containing (outer) composite director of the actor.

In this paragraph we consider the case of a process-oriented opaque composite actor that is contained by a schedule-oriented (non process) opaque composite actor. If the actors contained by the inner composite actor are not blocked, then execution of the inner composite actor is allowed to continue independent of the state of the branch controllers. If the actors contained by the inner composite actor are internally blocked, then after the branch controllers have been deactivated, execution of the composite actor ends and postfire returns false indicating that successive iterations are not allowed. If the actors contained by the inner composite actor are externally blocked, then the composite process director waits until the branch controllers block (an inevitable condition) and ends the iteration with postfire() returning true indicating that successive iterations are allowed.

Since:
Ptolemy II 1.0
Version:
$Id: CompositeProcessDirector.java,v 1.43.2.1 2004/06/18 00:48:59 cxh Exp $
Author:
John S. Davis II
See Also:
Director, Serialized Form
Accepted Rating:
Yellow (davisj)
Proposed Rating:
Green (mudit)

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
CompositeProcessDirector()
          Construct a director in the default workspace with an empty string as its name.
CompositeProcessDirector(CompositeEntity container, java.lang.String name)
          Construct a director in the given container with the given name.
CompositeProcessDirector(Workspace workspace)
          Construct a director in the workspace with an empty 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.
protected  void _actorUnBlocked(java.util.LinkedList receivers)
          Unregister the receivers that were previously blocked.
protected  void _actorUnBlocked(ProcessReceiver receiver)
          Unregister the specified receiver that was previously blocked.
protected  boolean _areActorsDeadlocked()
          Return false if the number of blocked processes is less than the number of active actors; return true otherwise.
protected  boolean _areActorsExternallyBlocked()
          Return true if one or more contained actors are externally blocked; return false otherwise.
protected  void _controllerBlocked(BranchController controller)
          Register that the specified controller is blocked.
protected  void _controllerUnBlocked(BranchController controller)
          Unregister the specified controller as being no longer blocked.
protected  boolean _isInputControllerBlocked()
          Return true if the input controller of this director is blocked; return false otherwise.
protected  boolean _isOutputControllerBlocked()
          Return true if the output controller of this director is blocked; return false otherwise.
protected  boolean _registerBlockedReceiversWithExecutive()
          Return true after registering all blocked receivers of the branch controllers of the director with the executive director and then waiting on the executive director to handle the blocked receivers.
protected  boolean _resolveDeadlock()
          Attempt to resolve a deadlock and return true if the deadlock no longer exists and successive iterations are allowed; if the deadlock still exists then return false indicating that future iterations are not allowed.
protected  boolean _resolveInternalDeadlock()
          Return false indicating that resolution of an internal deadlock was unsuccessful and execution should discontinue.
 java.lang.Object clone(Workspace workspace)
          Clone the director into the specified workspace.
 void createBranchController(java.util.Iterator ports)
          Create a input and/or output branch controllers according to whether the ports passed in as arguments are input or output ports.
 BranchController getInputController()
          Return the input branch controller of this director.
 BranchController getOutputController()
          Return the output branch controller of this director.
 void initialize()
          Invoke the initialize() methods of all the deeply contained actors in the container (a composite actor) of this director.
 Receiver newReceiver()
          Return a new receiver of a type compatible with this director.
 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 stopInputBranchController()
          Stop the input branch controller of this director.
 void stopOutputBranchController()
          Stop the output branch controller of this director.
 void wrapup()
          End the execution of the model under the control of this director.
 
Methods inherited from class ptolemy.actor.process.ProcessDirector
_actorHasRestarted, _actorHasStopped, _addNewThread, _areAllActorsStopped, _decreaseActiveCount, _getActiveActorsCount, _getBlockedActorsCount, _getProcessThread, _getStoppedActorsCount, _increaseActiveCount, fire, initialize, isStopFireRequested, isStopRequested, postfire, 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, 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
 

Constructor Detail

CompositeProcessDirector

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


CompositeProcessDirector

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

CompositeProcessDirector

public CompositeProcessDirector(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 ProcessDirector
Parameters:
workspace - The workspace for the cloned object.
Returns:
The new ProcessDirector.
Throws:
java.lang.CloneNotSupportedException - If one of the attributes cannot be cloned.

createBranchController

public void createBranchController(java.util.Iterator ports)
                            throws IllegalActionException
Create a input and/or output branch controllers according to whether the ports passed in as arguments are input or output ports. If any of the ports are input (output) ports, then they will be added to the input (output) branch controller.

Parameters:
ports - The ports for which branches will be assigned.
Throws:
IllegalActionException - If any of the ports are not opaque.

getInputController

public BranchController getInputController()
Return the input branch controller of this director. If this method is called prior to the invocation of initialize(), then this method will return null.

Returns:
The input branch controller of this director.

getOutputController

public BranchController getOutputController()
Return the output branch controller of this director. If this method is called prior to the invocation of initialize(), then this method will return null.

Returns:
The output branch controller of this director.

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 ProcessDirector
Throws:
IllegalActionException - If the initialize() method of one of the deeply contained actors throws it.

newReceiver

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

Overrides:
newReceiver in class ProcessDirector
Returns:
A new MailboxBoundaryReceiver.

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 of the actors that were created in the initialize() method.

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

stopInputBranchController

public void stopInputBranchController()
Stop the input branch controller of this director. This method will block until the input branch controller has stopped due to all of the branches it controls stopping.


stopOutputBranchController

public void stopOutputBranchController()
Stop the output branch controller of this director. This method will block until the output branch controller has stopped due to all of the branches it controls stopping.


wrapup

public void wrapup()
            throws IllegalActionException
End the execution of the model under the control of this director. A flag is set in all of 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.

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

Specified by:
wrapup in interface Executable
Overrides:
wrapup in class ProcessDirector
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)
Register the receiver that instigated the newly blocked actor. This method may be overridden in derived classes to add domain specific functionality. Implementations of this method must be synchronized.

Overrides:
_actorBlocked in class ProcessDirector
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. This method may be overridden in derived classes to add domain specific functionality. Implementations of this method must be synchronized.

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

_actorUnBlocked

protected void _actorUnBlocked(ProcessReceiver receiver)
Unregister the specified receiver that was previously blocked. This method may be overridden in derived classes to add domain specific functionality. Implementations of this method must be synchronized.

Overrides:
_actorUnBlocked in class ProcessDirector
Parameters:
receiver - The receiver whose data transfer was previously blocked.

_actorUnBlocked

protected void _actorUnBlocked(java.util.LinkedList receivers)
Unregister the receivers that were previously blocked. This method may be overridden in derived classes to add domain specific functionality. Implementations of this method must be synchronized.

Overrides:
_actorUnBlocked in class ProcessDirector
Parameters:
receivers - The receivers whose data transfer was previously blocked.

_areActorsDeadlocked

protected boolean _areActorsDeadlocked()
Return false if the number of blocked processes is less than the number of active actors; return true otherwise. Note that if the number of active actors is 0 then this method will return true. Derived classes may override this method to add domain specific functionality. Implementations of this method must be synchronized.

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

_areActorsExternallyBlocked

protected boolean _areActorsExternallyBlocked()
Return true if one or more contained actors are externally blocked; return false otherwise. We say an actor is externally blocked if it is blocked attempting data transfer through a boundary port of its containing actor. Note that a true return value for this method does not imply that the contained actors are deadlocked.

Returns:
true If one or more contained actors are externally blocked; return false otherwise.

_controllerBlocked

protected void _controllerBlocked(BranchController controller)
Register that the specified controller is blocked. Pass the specified controller in as an argument. Note that if the controller passed in as an argument is not contained by this director or if the state of the controller is not blocked then no registration operation will be performed by this method.

Parameters:
controller - The controller for which registration of a blocked state will occur.

_controllerUnBlocked

protected void _controllerUnBlocked(BranchController controller)
Unregister the specified controller as being no longer blocked. Pass the specified controller in as an argument. Note that if the controller passed in as an argument is not contained by this director or if the state of the controller is blocked then no registration operation will be performed by this method.

Parameters:
controller - The controller for which registration of an unblocked state will occur.

_isInputControllerBlocked

protected boolean _isInputControllerBlocked()
Return true if the input controller of this director is blocked; return false otherwise.

Returns:
true If the input controller of this director is blocked; return false otherwise.

_isOutputControllerBlocked

protected boolean _isOutputControllerBlocked()
Return true if the output controller of this director is blocked; return false otherwise.

Returns:
true If the output controller of this director is blocked; return false otherwise.

_registerBlockedReceiversWithExecutive

protected boolean _registerBlockedReceiversWithExecutive()
Return true after registering all blocked receivers of the branch controllers of the director with the executive director and then waiting on the executive director to handle the blocked receivers.

Returns:
True after registering blocked branch controller receivers with the executive director and waiting on the executive director to respond.

_resolveDeadlock

protected boolean _resolveDeadlock()
                            throws IllegalActionException
Attempt to resolve a deadlock and return true if the deadlock no longer exists and successive iterations are allowed; if the deadlock still exists then return false indicating that future iterations are not allowed. If the deadlock is internal then apply a domain specific algorithm to attempt deadlock resolution via the _resolveInternalDeadlock() method. If the algorithm is successful and deadlock no longer exists then return true. If the algorithm is unsuccessful and deadlock persists then end the iteration and return false.

If the deadlock is an external deadlock and the containing model of computation is process-oriented, then register the externally blocked receivers with the composite actor that contains this director's composite actor. If the deadlock is an external deadlock and the containing model of computation is schedule-oriented, then end this iteration and return true.

While in special cases it my be useful to override this method for domain specific functionality it is more likely that this method will remain the same and the _resolveInternalDeadlock() method will be overridden for particular models of computation.

Overrides:
_resolveDeadlock in class ProcessDirector
Returns:
false If deadlock could not be resolved and successive iterations are not allowed; return true otherwise.
Throws:
IllegalActionException - Not thrown in this base class.

_resolveInternalDeadlock

protected boolean _resolveInternalDeadlock()
                                    throws IllegalActionException
Return false indicating that resolution of an internal deadlock was unsuccessful and execution should discontinue. Subclasses may override this method for domain specific functionality. Domain specific functionality should include algorithms to resolve internal deadlock. Successful application of the algorithm should result in a return value of true; unsuccessful application should result in a return value of false.

Returns:
False indicating that internal deadlock was not resolved.
Throws:
IllegalActionException - Not thrown in this base class.