ptolemy.domains.pn.kernel
Class TimedPNDirector

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

public class TimedPNDirector
extends PNDirector

A TimedPNDirector governs the execution of a CompositeActor with Kahn-MacQueen process networks (PN) semantics extended by introduction of a notion of global time.

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 time to progress (time-blocked). Time can progress for an active process in this model of computation only when the process is blocked.

A deadlock is when all the active processes are blocked. The director is responsible for handling deadlocks during execution. This director handles three different sorts of deadlocks, real deadlock, timed 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 proceed.

A timed deadlock is when all the processes under the control of this director are blocked, at least one process is blocked on a delay (time-blocked) and no process is blocked on a write. This director supports a notion of global time. All active processes that are not blocked and are executing concurrently are executing at the same global time. A process that wants time to advance, suspends itself by calling the fireAt() method of the director and specifies the time it wants to be awakened at. Time can advance only when a timed deadlock occurs. In such a case, the director advances time to the time when the first timed-blocked process can be awakened.

Since:
Ptolemy II 0.2
Version:
$Id: TimedPNDirector.java,v 1.76 2004/04/13 03:34:09 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  CalendarQueue _eventQueue
          The priority queue that stores the list of processes waiting for time to advance.
 
Fields inherited from class ptolemy.domains.pn.kernel.PNDirector
_readBlockCount, _writeBlockCount, _writeBlockedQueues, initialQueueCapacity, maximumQueueCapacity
 
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
TimedPNDirector()
          Construct a director in the default workspace with an empty string as its name.
TimedPNDirector(CompositeEntity container, java.lang.String name)
          Construct a director in the given container with the given name.
TimedPNDirector(Workspace workspace)
          Construct a director in the workspace with an empty name.
 
Method Summary
protected  boolean _areActorsDeadlocked()
          Return true if a deadlock is detected.
protected  void _informOfDelayBlock()
          Increment by 1 the count of actors waiting for the time to advance.
protected  void _informOfDelayUnblock()
          Decrease by 1 the count of processes blocked on a delay.
protected  boolean _resolveDeadlock()
          Return false on detection of a real deadlock.
 java.lang.Object clone(Workspace workspace)
          Clone the director into the specified workspace.
 void fireAt(Actor actor, double newFiringTime)
          Suspend the calling process until the time has advanced to at least the time specified by the method argument.
 void setCurrentTime(double newTime)
          Set the current time of the model under this director.
 
Methods inherited from class ptolemy.domains.pn.kernel.PNDirector
_actorBlocked, _actorUnBlocked, _incrementLowestWriteCapacityPort, _resolveInternalDeadlock, addProcessListener, initialize, newReceiver, postfire, removeProcessListener
 
Methods inherited from class ptolemy.actor.process.CompositeProcessDirector
_actorBlocked, _actorUnBlocked, _actorUnBlocked, _areActorsExternallyBlocked, _controllerBlocked, _controllerUnBlocked, _isInputControllerBlocked, _isOutputControllerBlocked, _registerBlockedReceiversWithExecutive, 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, 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
 

Field Detail

_eventQueue

protected CalendarQueue _eventQueue
The priority queue that stores the list of processes waiting for time to advance. These processes are sorted by the time they want to resume at.

Constructor Detail

TimedPNDirector

public TimedPNDirector()
                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 FIFO queues in all the receivers created in the PN domain.


TimedPNDirector

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

TimedPNDirector

public TimedPNDirector(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. May be thrown in derived classes.
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 and no topology listeners. The count of active processes is zero. The parameter "initialQueueCapacity" has the same value as the director being cloned.

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

fireAt

public void fireAt(Actor actor,
                   double newFiringTime)
            throws IllegalActionException
Suspend the calling process until the time has advanced to at least the time specified by the method argument. Add the actor corresponding to the calling process to the priority queue and sort it by the time specified by the method argument. Increment the count of the actors blocked on a delay. Suspend the calling process until the time has advanced to at least the time specified by the method argument. Resume the execution of the calling process and return.

Overrides:
fireAt in class Director
Parameters:
actor - The actor scheduled to be fired.
newFiringTime - The scheduled time.
Throws:
IllegalActionException - If the operation is not permissible (e.g. the given time is in the past).

setCurrentTime

public void setCurrentTime(double newTime)
                    throws IllegalActionException
Set the current time of the model under this director.

Overrides:
setCurrentTime in class Director
Parameters:
newTime - The new time of the model.
Throws:
IllegalActionException - If an attempt is made to change the time to less than the current time.

_areActorsDeadlocked

protected boolean _areActorsDeadlocked()
Return true if a deadlock is detected. Return false otherwise. Return true if all the active processes in the container are either read-blocked, write-blocked or delay-blocked.

Overrides:
_areActorsDeadlocked in class CompositeProcessDirector
Returns:
true if a deadlock is detected.

_informOfDelayBlock

protected void _informOfDelayBlock()
Increment by 1 the count of actors waiting for the time to advance. Check for a resultant deadlock or pausing of the execution. If either of them is detected, then notify the directing thread of the same.


_informOfDelayUnblock

protected void _informOfDelayUnblock()
Decrease by 1 the count of processes blocked on a delay.


_resolveDeadlock

protected boolean _resolveDeadlock()
                            throws IllegalActionException
Return false on detection of a real deadlock. Otherwise break the deadlock and return true. On detection of a timed deadlock, advance time to the earliest time that a delayed process is waiting for, wake up all the actors waiting for time to advance to the new time, and remove them from the priority queue. This method is synchronized on the director.

Overrides:
_resolveDeadlock in class CompositeProcessDirector
Returns:
true if a real deadlock is detected, false otherwise.
Throws:
IllegalActionException - Not thrown in this base class. This might be thrown by derived classes.