ptolemy.domains.pn.kernel
Class PNDirector

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

public class PNDirector
extends CompositeProcessDirector

A PNDirector governs the execution of a CompositeActor with extended Kahn-MacQueen process networks (PN) semantics. This model of computation has been extended to support mutations of graphs in a non-deterministic way.

The thread that calls the various execution methods (initialize, prefire, fire and postfire) on the director is referred to as the directing thread. This directing thread might be the main thread responsible for the execution of the entire simulation or might be the thread created by the executive director of the containing composite actor.

In the PN domain, the director creates a thread (an instance of ProcessThread), representing a Kahn process, for each actor in the model. The threads are created in initialize() and started in the prefire() method of the ProcessDirector. A process is considered active from its creation until its termination. An active process can block when trying to read from a channel (read-blocked), when trying to write to a channel (write-blocked) or when waiting for a queued topology change request to be processed (mutation-blocked).

A deadlock is when all the active processes are blocked. The director is responsible for handling deadlocks during execution. This director handles two different sorts of deadlocks, real deadlock and artificial deadlock.

A real deadlock is when all the processes are blocked on a read meaning that no process can proceed until it receives new data. The execution can be terminated, if desired, in such a situation. If the container of this director does not have any input ports (as is in the case of a top-level composite actor), then the executive director or manager terminates the execution. If the container has input ports, then it is up to the executive director of the container to decide on the termination of the execution. To terminate the execution after detection of a real deadlock, the manager or the executive director calls wrapup() on the director.

An artificial deadlock is when all processes are blocked and at least one process is blocked on a write. In this case the director increases the capacity of the receiver with the smallest capacity amongst all the receivers on which a process is blocked on a write. This breaks the deadlock and the execution can resume. If the increase results in a capacity that exceeds the value of maximumQueueCapacity, then instead of breaking the deadlock, an exception is thrown. This can be used to detect erroneous models that require unbounded queues.

Since:
Ptolemy II 0.2
Version:
$Id: PNDirector.java,v 1.121 2004/04/13 05:13:10 cxh Exp $
Author:
Mudit Goel
See Also:
Serialized Form
Accepted Rating:
Green (davisj)
Proposed Rating:
Green (mudit)

Nested Class Summary
 
Nested classes inherited from class ptolemy.kernel.util.NamedObj
NamedObj.ContainedObjectsIterator
 
Field Summary
protected  int _readBlockCount
          The count of processes blocked on a read from a receiver.
protected  int _writeBlockCount
          The count of processes blocked on a write to a receiver.
protected  java.util.LinkedList _writeBlockedQueues
          The list of receivers blocked on a write to a receiver.
 Parameter initialQueueCapacity
          The initial size of the queues for each communication channel.
 Parameter maximumQueueCapacity
          The maximum size of the queues for each communication channel.
 
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
PNDirector()
          Construct a director in the default workspace with an empty string as its name.
PNDirector(CompositeEntity container, java.lang.String name)
          Construct a director in the given container with the given name.
PNDirector(Workspace workspace)
          Construct a director in the workspace with an empty name.
 
Method Summary
protected  void _actorBlocked(ProcessReceiver receiver)
          Increment by 1 the count of processes blocked while reading from a receiver and notify all process listeners of the blocking of the process.
protected  void _actorUnBlocked(PNQueueReceiver receiver)
          Decrease by 1 the count of processes blocked on a read and inform all the process listeners that the relevant process has resumed its execution.
protected  void _incrementLowestWriteCapacityPort()
          Double the capacity of one of the queues with the smallest capacity belonging to a receiver on which a process is blocked while attempting to write.
protected  boolean _resolveInternalDeadlock()
          Resolve an artificial deadlock and return true.
 void addProcessListener(PNProcessListener listener)
          Add a process state change listener to this director.
 java.lang.Object clone(Workspace workspace)
          Clone the director into the specified workspace.
 void initialize()
          Invoke the initialize() method of ProcessDirector.
 Receiver newReceiver()
          Return a new receiver compatible with this director.
 boolean postfire()
          Return true if the containing composite actor contains active processes and the composite actor has input ports and if stop() has not been called.
 void removeProcessListener(PNProcessListener listener)
          Remove a process listener from this director.
 
Methods inherited from class ptolemy.actor.process.CompositeProcessDirector
_actorBlocked, _actorUnBlocked, _actorUnBlocked, _areActorsDeadlocked, _areActorsExternallyBlocked, _controllerBlocked, _controllerUnBlocked, _isInputControllerBlocked, _isOutputControllerBlocked, _registerBlockedReceiversWithExecutive, _resolveDeadlock, createBranchController, getInputController, getOutputController, prefire, stopInputBranchController, stopOutputBranchController, wrapup
 
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, 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

initialQueueCapacity

public Parameter initialQueueCapacity
The initial size of the queues for each communication channel. This is an integer that defaults to 1.


maximumQueueCapacity

public Parameter maximumQueueCapacity
The maximum size of the queues for each communication channel. This is an integer that defaults to 65536. To specify unbounded queues, set this to 0.


_readBlockCount

protected int _readBlockCount
The count of processes blocked on a read from a receiver.


_writeBlockCount

protected int _writeBlockCount
The count of processes blocked on a write to a receiver.


_writeBlockedQueues

protected java.util.LinkedList _writeBlockedQueues
The list of receivers blocked on a write to a receiver.

Constructor Detail

PNDirector

public PNDirector()
           throws IllegalActionException,
                  NameDuplicationException
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. Create a director parameter "initialQueueCapacity" with the default value 1. This sets the initial capacities of the queues in all the receivers created in the PN domain.


PNDirector

public PNDirector(Workspace workspace)
           throws IllegalActionException,
                  NameDuplicationException
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. Create a director parameter "initialQueueCapacity" with the default value 1. This sets the initial capacities of the queues in all the receivers created in the PN domain.

Parameters:
workspace - The workspace of this object.

PNDirector

public PNDirector(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. Create a director parameter "initialQueueCapacity" with the default value 1. This sets the initial capacities of the queues in all the receivers created in the PN domain.

Parameters:
container - Container of the director.
name - Name of this director.
Throws:
IllegalActionException - If the director is not compatible with the specified container. Thrown in derived classes.
NameDuplicationException - If the container not a CompositeActor and the name collides with an entity in the container.
Method Detail

addProcessListener

public void addProcessListener(PNProcessListener listener)
Add a process state change listener to this director. The listener will be notified of each change to the state of a process.

Parameters:
listener - The PNProcessListener to add.

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

initialize

public void initialize()
                throws IllegalActionException
Invoke the initialize() method of ProcessDirector. Also set all the state variables to the their initial values. The list of process listeners is not reset as the developer might want to reuse the list of listeners.

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

newReceiver

public Receiver newReceiver()
Return a new receiver compatible with this director. The receiver is an instance of PNQueueReceiver. Set the initial capacity of the FIFO queue in the receiver to the value specified by the director parameter "initialQueueCapacity". The default value of the parameter is 1.

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

postfire

public boolean postfire()
                 throws IllegalActionException
Return true if the containing composite actor contains active processes and the composite actor has input ports and if stop() has not been called. Return false otherwise. This method is normally called only after detecting a real deadlock, or if stopFire() is called. True is returned to indicate that the composite actor can start its execution again if it receives data on any of its input ports.

Specified by:
postfire in interface Executable
Overrides:
postfire in class ProcessDirector
Returns:
true to indicate that the composite actor can continue executing on receiving additional input on its input ports.
Throws:
IllegalActionException - Not thrown in this base class. May be thrown by derived classes.

removeProcessListener

public void removeProcessListener(PNProcessListener listener)
Remove a process listener from this director. If the listener is not attached to this director, do nothing.

Parameters:
listener - The PNProcessListener to be removed.

_incrementLowestWriteCapacityPort

protected void _incrementLowestWriteCapacityPort()
                                          throws IllegalActionException
Double the capacity of one of the queues with the smallest capacity belonging to a receiver on which a process is blocked while attempting to write.

Traverse through the list of receivers on which a process is blocked on a write and choose the one containing the queue with the smallest capacity. Double the capacity if the capacity is non-negative. In case the capacity is negative, set the capacity to 1. Unblock the process blocked on a write to the receiver containing this queue. Notify the thread corresponding to the blocked process to resume its execution and return.

Throws:
IllegalActionException - If the resulting capacity would exceed the value of maximumQueueCapacity.

_actorBlocked

protected void _actorBlocked(ProcessReceiver receiver)
Increment by 1 the count of processes blocked while reading from a receiver and notify all process listeners of the blocking of the process. Check for a deadlock or pausing of the execution as a result of the process blocking on a read. If either of them is detected, then notify the directing thread of the same.

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

_actorUnBlocked

protected void _actorUnBlocked(PNQueueReceiver receiver)
Decrease by 1 the count of processes blocked on a read and inform all the process listeners that the relevant process has resumed its execution.


_resolveInternalDeadlock

protected boolean _resolveInternalDeadlock()
                                    throws IllegalActionException
Resolve an artificial deadlock and return true. If the deadlock is not an artificial deadlock (it is a real deadlock), then return false. If it is an artificial deadlock, select the receiver with the smallest queue capacity on which any process is blocked on a write and increment the capacity of the contained queue. If the capacity is non-negative, then increment the capacity by 1. Otherwise set the capacity to 1. Unblock the process blocked on this receiver. Notify the thread corresponding to the blocked process and return true.
Overrides:
_resolveInternalDeadlock in class CompositeProcessDirector
Returns:
True after handling an artificial deadlock. Otherwise return false.
Throws:
IllegalActionException - If the maximum queue capacity is exceeded. This might be thrown by derived classes.