ptolemy.domains.pn.kernel
Class TimedPNDirector

java.lang.Object
  ptolemy.kernel.util.NamedObj
      ptolemy.kernel.util.Attribute
          ptolemy.actor.Director
              ptolemy.actor.process.ProcessDirector
                  ptolemy.actor.process.CompositeProcessDirector
                      ptolemy.domains.pn.kernel.PNDirector
                          ptolemy.domains.pn.kernel.TimedPNDirector

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable, Executable, Initializable, TimedDirector, Changeable, Debuggable, DebugListener, Derivable, ModelErrorHandler, MoMLExportable, Moveable, Nameable

public class TimedPNDirector
extends PNDirector
implements TimedDirector

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 57040 2010-01-27 20:52:32Z cxh $

Author:

Mudit Goel

See Also:

Serialized Form

Accepted Rating:

Green (davisj)

Proposed Rating:

Green (mudit)

Nested Class Summary

Nested classes/interfaces inherited from class ptolemy.kernel.util.NamedObj

NamedObj.ContainedObjectsIterator

Field Summary

protected int	_delayBlockCount The number of time-blocked processes.
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

_readBlockedQueues, _writeBlockedQueues, initialQueueCapacity, maximumQueueCapacity, READ_BLOCKED, WRITE_BLOCKED

Fields inherited from class ptolemy.actor.process.ProcessDirector

_notDone, _stopFireRequested

Fields inherited from class ptolemy.actor.Director

_actorsFinishedExecution, _currentTime, _finishRequested, _initializables, _stopRequested, timeResolution

Fields inherited from class ptolemy.kernel.util.NamedObj

_changeListeners, _changeLock, _changeRequests, _debugging, _debugListeners, _elementName, _isPersistent, _verbose, _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	_areThreadsDeadlocked() 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.
Dependency	delayDependency(double delay) Return a boolean dependency representing a model-time delay of the specified amount.
Time	fireAt(Actor actor, Time newFiringTime) Suspend the calling process until the time has advanced to at least the time specified by the method argument.
void	setModelTime(Time newTime) Set a new value to the current time of the model, where the new time must be no earlier than the current time.
void	wrapup() Reset private variables.

Methods inherited from class ptolemy.domains.pn.kernel.PNDirector

_incrementLowestWriteCapacityPort, _resolveInternalDeadlock, addProcessListener, initialize, newReceiver, postfire, preinitialize, removeProcessListener, suggestedModalModelDirectors, supportMultirateFiring, threadBlocked, threadUnblocked

Methods inherited from class ptolemy.actor.process.CompositeProcessDirector

_areActorsExternallyBlocked, _controllerBlocked, _controllerUnBlocked, _isInputControllerBlocked, _isOutputControllerBlocked, createBranchController, getInputController, getOutputController, prefire, stopInputBranchController, stopOutputBranchController, threadBlocked, threadUnblocked

Methods inherited from class ptolemy.actor.process.ProcessDirector

_areAllThreadsStopped, _getActiveThreadsCount, _getBlockedThreadsCount, _getStoppedThreadsCount, _newProcessThread, addThread, finish, fire, initialize, isStopFireRequested, isStopRequested, isThreadActive, removeThread, stop, stopFire, terminate, threadHasPaused, threadHasResumed, transferInputs, transferOutputs

Methods inherited from class ptolemy.actor.Director

_description, _fireContainerAt, _isEmbedded, _isTopLevel, _transferInputs, _transferOutputs, addInitializable, attributeChanged, createSchedule, defaultDependency, fireAt, fireAtCurrentTime, getCausalityInterface, getCurrentTime, getErrorTolerance, getGlobalTime, getModelNextIterationTime, getModelStartTime, getModelStopTime, getModelTime, getNextIterationTime, getStartTime, getStopTime, getTimeResolution, implementsStrictActorSemantics, invalidateResolvedTypes, invalidateSchedule, isFireFunctional, isStrict, iterate, preinitialize, removeInitializable, requestInitialization, setContainer, setCurrentTime

Methods inherited from class ptolemy.kernel.util.Attribute

_checkContainer, _getContainedObject, _propagateExistence, getContainer, moveDown, moveToFirst, moveToIndex, moveToLast, moveUp, setName, updateContent

Methods inherited from class ptolemy.kernel.util.NamedObj

_addAttribute, _adjustOverride, _attachText, _cloneFixAttributeFields, _debug, _debug, _debug, _debug, _debug, _exportMoMLContents, _getIndentPrefix, _isMoMLSuppressed, _markContentsDerived, _propagateValue, _recordDecoratedAttributes, _removeAttribute, _splitName, _stripNumericSuffix, _validateSettables, addChangeListener, addDebugListener, attributeList, attributeList, attributeTypeChanged, clone, containedObjectsIterator, deepContains, depthInHierarchy, description, description, event, executeChangeRequests, exportMoML, exportMoML, exportMoML, exportMoML, exportMoML, exportMoMLPlain, getAttribute, getAttribute, getAttributes, getChangeListeners, getClassName, getDecoratorAttribute, getDecoratorAttributes, getDerivedLevel, getDerivedList, getDisplayName, getElementName, getFullName, getModelErrorHandler, getName, getName, getPrototypeList, getSource, handleModelError, isDeferringChangeRequests, isOverridden, isPersistent, lazyContainedObjectsIterator, message, propagateExistence, propagateValue, propagateValues, removeChangeListener, removeDebugListener, requestChange, setClassName, setDeferringChangeRequests, setDerivedLevel, setDisplayName, setModelErrorHandler, setPersistent, setSource, sortContainedObjects, toplevel, toString, uniqueName, validateSettables, workspace

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface ptolemy.actor.TimedDirector

getModelTime, getTimeResolution

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.

_delayBlockCount

protected int _delayBlockCount

The number of time-blocked processes. changed from private to protected on 7/13/08 by Patricia Derler

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.

Throws:

IllegalActionException - If the name has a period in it, or the director is not compatible with the specified container.

NameDuplicationException - If the container already contains an entity with the specified name.

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.

Throws:

IllegalActionException - If the name has a period in it, or the director is not compatible with the specified container.

NameDuplicationException - If the container already contains an entity with the specified name.

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.

See Also:

NamedObj.exportMoML(Writer, int, String), NamedObj.setDeferringChangeRequests(boolean)

delayDependency

public Dependency delayDependency(double delay)

Return a boolean dependency representing a model-time delay of the specified amount.

Specified by:

delayDependency in interface TimedDirector

Parameters:

delay - A non-negative delay.

Returns:

A boolean dependency representing a delay.

fireAt

public Time fireAt(Actor actor,
                   Time 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 requested time.

Returns:

An instance of Time with value NEGATIVE_INFINITY, or if there is an executive director, the time at which the container of this director will next be fired in response to this request.

Throws:

IllegalActionException - If the operation is not permissible (e.g. the given time is in the past).

See Also:

Director.fireAtCurrentTime(Actor)

setModelTime

public void setModelTime(Time newTime)
                  throws IllegalActionException

Set a new value to the current time of the model, where the new time must be no earlier than the current time.

Overrides:

setModelTime in class CompositeProcessDirector

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.

See Also:

Director.getModelTime()

wrapup

public void wrapup()
            throws IllegalActionException

Reset private variables. added 7/15/08 Patricia Derler

Specified by:

wrapup in interface Initializable

Overrides:

wrapup in class CompositeProcessDirector

Throws:

IllegalActionException - If an error occurs while accessing the receivers of all actors under the control of this director.

_areThreadsDeadlocked

protected boolean _areThreadsDeadlocked()

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:

_areThreadsDeadlocked 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.