ptolemy.domains.sr.kernel
Class SRDirector

java.lang.Object
  extended byptolemy.kernel.util.NamedObj
      extended byptolemy.kernel.util.Attribute
          extended byptolemy.actor.Director
              extended byptolemy.actor.sched.StaticSchedulingDirector
                  extended byptolemy.domains.sr.kernel.SRDirector
All Implemented Interfaces:
Changeable, java.lang.Cloneable, Debuggable, DebugListener, Derivable, Executable, ModelErrorHandler, MoMLExportable, Nameable, java.io.Serializable

public class SRDirector
extends StaticSchedulingDirector

A director for the Synchronous Reactive (SR) model of computation. In SR, both computation and communication are considered to happen instantaneously. In models with cycles, this introduces interesting issues involving instantaneous feedback.

SR is an untimed domain, so it has no notion of the passage of time. Computation happens in a series of instants. An instant is one iteration of the director. If SR is embedded inside a timed domain, the SR director will inherit the current time of the outside director.

In SR, each iteration begins with the values on all channels being unknown. To ensure that an iteration converges to final values in finite time, it is required that values change only from unknown to known, and never the other way around. Once a value is set (or cleared), it must not change again in the course of the iteration.

An actor is considered ready to fire if sufficient known inputs are available. In a sense, an actor firing is triggered by these known inputs, because the director only fires an actor if it is ready to fire. Unless an actor contains an attribute called "_nonStrictMarker", it is assumed to be a strict actor, meaning that it requires all of its inputs to be known before it is fired. This is very important since once an actor defines a particular output, it is not allowed to change that value in a subsequent firing in the course of the iteration. A nonstrict actor can fire even if no inputs are known, and may fire any number of times in the course of an iteration. Thus, a nonstrict actor can be used to produce an initial token in a cyclic graph. Since strict actors are only fired if all of their inputs are known, a given strict actor is only fired once in a given iteration. An actor has completed firing if it has defined all of its outputs.

An actor is considered allowed to fire if its prefire() method has returned true. An actor is considered allowed to iterate if its postfire() method has not returned false.

A scheduler returns an ordering of the actors. SR semantics do not require any specific ordering of actor firings, but a particular ordering may be desirable in an attempt to reduce the computation time required for a given iteration to converge. If the scheduler is an SRRandomizedScheduler, in the course of an iteration, the director cycles through the schedule repeatedly, firing those actors that are allowed to fire and ready to fire. If the scheduler is an SROptimizedScheduler, the director makes only one pass through the schedule, since it guarantees the convergence of the iteration.

For an actor to be valid in the SR domain, its prefire() method must be monotonic. In other words, once the prefire() method of an actor returns true in a given iteration, this method must not return false if it were to be called again in the same iteration. It is only possible for the number of known inputs of an actor to increase in a given iteration, so, for example, if the prefire() method of an actor returns true and then more inputs become known, the method must return true if it were to be called again. If this were not the case, the behavior of the model would be nondeterministic since the execution results would depend on the order of the schedule.

An iteration has converged if both the total number of known outputs and the number of actors that are allowed to fire have converged. In other words, the system is executed until the values in the model reach a fixed-point. Further execution would not result in more defined values, and the iteration has converged.

Since:
Ptolemy II 2.0
Version:
$Id: SRDirector.java,v 1.72 2004/04/13 05:13:07 cxh Exp $
Author:
Paul Whitaker
See Also:
Serialized Form
Accepted Rating:
Green (pwhitake)
Proposed Rating:
Green (pwhitake)

Nested Class Summary
 
Nested classes inherited from class ptolemy.kernel.util.NamedObj
NamedObj.ContainedObjectsIterator
 
Field Summary
 Parameter iterations
          The number of times that postfire may be called before it returns false.
 Parameter scheduler
          The name of the scheduler to be used.
 
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
SRDirector()
          Construct a director in the default workspace with an empty string as its name.
SRDirector(CompositeEntity container, java.lang.String name)
          Construct a director in the given container with the given name.
SRDirector(Workspace workspace)
          Construct a director in the given workspace with an empty name.
 
Method Summary
protected  boolean _writeAccessRequired()
          Override the base class to indicate that this director does not need write access on the workspace during an iteration.
 void attributeChanged(Attribute attribute)
          React to a change in an attribute.
 void fire()
          Fire contained actors until the iteration converges.
 int getIterations()
          Return the number of iterations to be executed by the director, which is specified by a parameter of the director.
 void initialize()
          Initialize the director and invoke the initialize() methods of all actors deeply contained by the container.
 Receiver newReceiver()
          Return a new receiver consistent with the SR domain.
 boolean postfire()
          Call postfire() on all contained actors.
 void preinitialize()
          Instantiate a new scheduler if necessary and invoke the preinitialize() methods of all deeply contained actors.
 void receiverChanged(Receiver receiver)
          React to the change in receiver status by incrementing the count of known receivers.
 boolean transferInputs(IOPort port)
          Transfer data from the specified input port of the container to the ports it is connected to on the inside.
 boolean transferOutputs(IOPort port)
          Transfer data from the specified output port of the container to the ports it is connected to on the outside.
 
Methods inherited from class ptolemy.actor.sched.StaticSchedulingDirector
_setScheduler, addDebugListener, getScheduler, invalidateSchedule, isScheduleValid, prefire, removeDebugListener, setScheduler, setScheduleValid
 
Methods inherited from class ptolemy.actor.Director
_description, _isEmbedded, _isTopLevel, domainPolymorphicTransferInputs, domainPolymorphicTransferOutputs, fireAt, fireAtCurrentTime, getCurrentTime, getNextIterationTime, getTimeResolution, initialize, invalidateResolvedTypes, iterate, needWriteAccess, requestInitialization, setContainer, setCurrentTime, setTimeResolution, stop, stopFire, terminate, wrapup
 
Methods inherited from class ptolemy.kernel.util.Attribute
_getContainedObject, _propagateExistence, clone, 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, 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, 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

iterations

public Parameter iterations
The number of times that postfire may be called before it returns false. The type must be IntToken, and the value defaults to zero. If the value is less than or equal to zero, then the execution will never return false in postfire, and thus the execution can continue forever.


scheduler

public Parameter scheduler
The name of the scheduler to be used. The default is a String "ptolemy.domains.sr.kernel.SRRandomizedScheduler". The only other valid value is "ptolemy.domains.sr.kernel.SROptimizedScheduler".

Constructor Detail

SRDirector

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


SRDirector

public SRDirector(Workspace workspace)
Construct a director in the given 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 for this object.

SRDirector

public SRDirector(CompositeEntity container,
                  java.lang.String name)
           throws IllegalActionException,
                  NameDuplicationException
Construct a director in the given container with the given name. 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 - Container of the director.
name - Name of this director.
Throws:
IllegalActionException - If the director is not compatible with the specified container.
NameDuplicationException - If the name collides with an attribute in the container.
Method Detail

attributeChanged

public void attributeChanged(Attribute attribute)
                      throws IllegalActionException
React to a change in an attribute. If the changed attribute matches a parameter of the director, then the corresponding private copy of the parameter value will be updated. In particular, if the scheduler parameter is changed, then the corresponding scheduler name will be recorded. The new scheduler will be instantiated during the next invocation of preinitialize().

Overrides:
attributeChanged in class NamedObj
Parameters:
attribute - The changed attribute.
Throws:
IllegalActionException - If the new scheduler that is specified is not valid.

fire

public void fire()
          throws IllegalActionException
Fire contained actors until the iteration converges. This method also calls the prefire() method of an actor before it is fired for the first time.

Specified by:
fire in interface Executable
Overrides:
fire in class StaticSchedulingDirector
Throws:
IllegalActionException - If an actor attempts to modify a known value.

getIterations

public int getIterations()
                  throws IllegalActionException
Return the number of iterations to be executed by the director, which is specified by a parameter of the director.

Returns:
The number of iterations.
Throws:
IllegalActionException - If the iterations parameter does not have a valid token.

initialize

public void initialize()
                throws IllegalActionException
Initialize the director and invoke the initialize() methods of all actors deeply contained by the container.

Specified by:
initialize in interface Executable
Overrides:
initialize in class Director
Throws:
IllegalActionException - If the superclass throws it.

newReceiver

public Receiver newReceiver()
Return a new receiver consistent with the SR domain.

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

postfire

public boolean postfire()
                 throws IllegalActionException
Call postfire() on all contained actors. Return false if the system has finished executing, either by reaching the iteration limit, or if no actors in the model return true in postfire(), or if stop() has been called.

Specified by:
postfire in interface Executable
Overrides:
postfire in class StaticSchedulingDirector
Returns:
True if the execution is not finished.
Throws:
IllegalActionException - If the iterations parameter does not have a valid token.

preinitialize

public void preinitialize()
                   throws IllegalActionException
Instantiate a new scheduler if necessary and invoke the preinitialize() methods of all deeply contained actors.

Specified by:
preinitialize in interface Executable
Overrides:
preinitialize in class Director
Throws:
IllegalActionException - If the superclass throws it.

receiverChanged

public void receiverChanged(Receiver receiver)
React to the change in receiver status by incrementing the count of known receivers.


transferInputs

public boolean transferInputs(IOPort port)
                       throws IllegalActionException
Transfer data from the specified input port of the container to the ports it is connected to on the inside. If there is no data on the specified input port, then set the ports on the inside to absent by calling sendClearInside(). This method delegates the data transfer operation to the same method on IOPort, so that the subclass of IOPort, TypedIOPort, can override this method to perform run-time type conversion.

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 - If the port is not an opaque input port.
See Also:
IOPort.transferInputs()

transferOutputs

public boolean transferOutputs(IOPort port)
                        throws IllegalActionException
Transfer data from the specified output port of the container to the ports it is connected to on the outside. If there is no data on the specified output port, then set the ports on the outside to absent by calling sendClear(). This method delegates the data transfer operation to the same method on IOPort.

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 - If the port is not an opaque output port.
See Also:
IOPort.transferOutputs()

_writeAccessRequired

protected boolean _writeAccessRequired()
Override the base class to indicate that this director does not need write access on the workspace during an iteration.

Overrides:
_writeAccessRequired in class Director
Returns:
False.