ptolemy.domains.sdf.kernel
Class SDFDirector

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.sdf.kernel.SDFDirector
All Implemented Interfaces:
ptolemy.kernel.util.Changeable, java.lang.Cloneable, ptolemy.kernel.util.Debuggable, ptolemy.kernel.util.DebugListener, ptolemy.kernel.util.Derivable, ptolemy.actor.Executable, ptolemy.kernel.util.ModelErrorHandler, ptolemy.kernel.util.MoMLExportable, ptolemy.kernel.util.Nameable, java.io.Serializable
Direct Known Subclasses:
DTDirector

public class SDFDirector
extends ptolemy.actor.sched.StaticSchedulingDirector

Director for the synchronous dataflow (SDF) model of computation.

SDF overview

The Synchronous Dataflow(SDF) domain supports the efficient execution of Dataflow graphs that lack control structures. Dataflow graphs that contain control structures should be executed using the Process Networks(PN) domain instead. SDF allows efficient execution, with very little overhead at runtime. It requires that the rates on the ports of all actors be known before hand. SDF also requires that the rates on the ports not change during execution. In addition, in some cases (namely systems with feedback) delays, which are represented by initial tokens on relations must be explicitly noted. SDF uses this rate and delay information to determine the execution sequence of the actors before execution begins.

Schedule Properties

Class comments

An SDFDirector is the class that controls execution of actors under the SDF domain. By default, actor scheduling is handled by the SDFScheduler class. Furthermore, the newReceiver method creates Receivers of type SDFReceiver, which extends QueueReceiver to support optimized gets and puts of arrays of tokens.

Actors are assumed to consume and produce exactly one token per channel on each firing. Actors that do not follow this convention should set the appropriate parameters on input and output ports to declare the number of tokens they produce or consume. See the

Since:
Ptolemy II 0.2
Version:
$Id: SDFDirector.java,v 1.110 2004/04/13 03:34:55 cxh Exp $
Author:
Steve Neuendorffer
See Also:
SDFScheduler, SDFReceiver, Serialized Form
Accepted Rating:
Green (neuendor)
Proposed Rating:
Green (neuendor)

Nested Class Summary
 
Nested classes inherited from class ptolemy.kernel.util.NamedObj
ptolemy.kernel.util.NamedObj.ContainedObjectsIterator
 
Field Summary
 ptolemy.data.expr.Parameter allowDisconnectedGraphs
          A parameter representing whether disconnected graphs are permitted.
 ptolemy.data.expr.Parameter allowRateChanges
          A parameter representing whether dynamic rate changes are permitted.
 ptolemy.data.expr.Parameter iterations
          A Parameter representing the number of times that postfire may be called before it returns false.
 ptolemy.data.expr.Parameter vectorizationFactor
          A Parameter representing the requested vectorization factor.
 
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
SDFDirector()
          Construct a director in the default workspace with an empty string as its name.
SDFDirector(ptolemy.kernel.CompositeEntity container, java.lang.String name)
          Construct a director in the given container with the given name.
SDFDirector(ptolemy.kernel.util.Workspace workspace)
          Construct a director in the 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(ptolemy.kernel.util.Attribute attribute)
          React to a change in an attribute.
 void initialize()
          Initialize the actors associated with this director and then set the iteration count to zero.
 ptolemy.actor.Receiver newReceiver()
          Return a new receiver consistent with the SDF domain.
 boolean postfire()
          Return false if the system has finished executing, either by reaching the iteration limit, or having an actor in the system return false in postfire.
 boolean prefire()
          Check the input ports of the container composite actor (if there are any) to see whether they have enough tokens, and return true if they do.
 void preinitialize()
          Preinitialize the actors associated with this director and compute the schedule.
 boolean transferInputs(ptolemy.actor.IOPort port)
          Override the base class method to transfer enough tokens to complete an internal iteration.
 boolean transferOutputs(ptolemy.actor.IOPort port)
          Override the base class method to transfer enough tokens to fulfill the output production rate.
 
Methods inherited from class ptolemy.actor.sched.StaticSchedulingDirector
_setScheduler, addDebugListener, fire, getScheduler, invalidateSchedule, isScheduleValid, 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

allowDisconnectedGraphs

public ptolemy.data.expr.Parameter allowDisconnectedGraphs
A parameter representing whether disconnected graphs are permitted. A model may have two or more graphs of actors that are not connected. The schedule can jump from one graph to another among the disconnected graphs. There is nothing to force the scheduler to finish executing all actors on one graph before firing actors on another graph. However, the order of execution within an graph should be correct. Usually, disconnected graphs in an SDF model indicates an error. The default value is a BooleanToken with the value false.


allowRateChanges

public ptolemy.data.expr.Parameter allowRateChanges
A parameter representing whether dynamic rate changes are permitted. An SDF model may constructed such that the values of rate parameters are modified during the execution of the system. If this parameter is false, then such models are valid and this class dynamically computes a new schedule at runtime. If this parameter is true, then the SDF domain performs a static check to disallow such models. Note that in order to generate code from an SDF model, this parameter must be set to true. The default value is a BooleanToken with the value true.


iterations

public ptolemy.data.expr.Parameter iterations
A Parameter representing the number of times that postfire may be called before it returns false. 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. Note that the amount of data processed by the SDF model is a function of both this parameter and the value of parameter vectorizationFactor, since vectorizationFactor can influence the choice of schedule. The default value is an IntToken with the value zero.


vectorizationFactor

public ptolemy.data.expr.Parameter vectorizationFactor
A Parameter representing the requested vectorization factor. The director will attempt to construct a schedule where each actor fires vectorizationFactor times more often than it would in a minimal schedule. This can allow actor executions to be grouped together, resulting in faster execution. This is more likely to be possible in graphs without tight feedback. This parameter must be a positive integer. The default value is an IntToken with the value one.

Constructor Detail

SDFDirector

public SDFDirector()
            throws ptolemy.kernel.util.IllegalActionException,
                   ptolemy.kernel.util.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. The SDFDirector will have a default scheduler of type SDFScheduler.


SDFDirector

public SDFDirector(ptolemy.kernel.util.Workspace workspace)
            throws ptolemy.kernel.util.IllegalActionException,
                   ptolemy.kernel.util.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. The SDFDirector will have a default scheduler of type SDFScheduler.

Parameters:
workspace - The workspace for this object.

SDFDirector

public SDFDirector(ptolemy.kernel.CompositeEntity container,
                   java.lang.String name)
            throws ptolemy.kernel.util.IllegalActionException,
                   ptolemy.kernel.util.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. The SDFDirector will have a default scheduler of type SDFScheduler.

Parameters:
container - Container of the director.
name - Name of this director.
Throws:
ptolemy.kernel.util.IllegalActionException - If the director is not compatible with the specified container. May be thrown in a derived class.
ptolemy.kernel.util.NameDuplicationException - If the container is not a CompositeActor and the name collides with an entity in the container.
Method Detail

attributeChanged

public void attributeChanged(ptolemy.kernel.util.Attribute attribute)
                      throws ptolemy.kernel.util.IllegalActionException
React to a change in an attribute. If the changed attribute matches a parameter of the director, then the corresponding local copy of the parameter value will be updated.

Parameters:
attribute - The changed parameter.
Throws:
ptolemy.kernel.util.IllegalActionException - If the parameter set is not valid.

initialize

public void initialize()
                throws ptolemy.kernel.util.IllegalActionException
Initialize the actors associated with this director and then set the iteration count to zero. The order in which the actors are initialized is arbitrary. In addition, if actors connected directly to output ports have initial production, then copy that initial production to the outside of the composite actor.

Throws:
ptolemy.kernel.util.IllegalActionException - If the initialize() method of one of the associated actors throws it, or if there is no scheduler.

newReceiver

public ptolemy.actor.Receiver newReceiver()
Return a new receiver consistent with the SDF domain.

Returns:
A new SDFReceiver.

prefire

public boolean prefire()
                throws ptolemy.kernel.util.IllegalActionException
Check the input ports of the container composite actor (if there are any) to see whether they have enough tokens, and return true if they do. If there are no input ports, then also return true. Otherwise, return false. Note that this does not call prefire() on the contained actors.

Returns:
true If all of the input ports of the container of this director have enough tokens.
Throws:
ptolemy.kernel.util.IllegalActionException - If port methods throw it.

preinitialize

public void preinitialize()
                   throws ptolemy.kernel.util.IllegalActionException
Preinitialize the actors associated with this director and compute the schedule. The schedule is computed during preinitialization so that hierarchical opaque composite actors can be scheduled properly, since the act of computing the schedule sets the rate parameters of the external ports. In addition, performing scheduling during preinitialization enables it to be present during code generation. The order in which the actors are preinitialized is arbitrary.

Throws:
ptolemy.kernel.util.IllegalActionException - If the preinitialize() method of one of the associated actors throws it.

postfire

public boolean postfire()
                 throws ptolemy.kernel.util.IllegalActionException
Return false if the system has finished executing, either by reaching the iteration limit, or having an actor in the system return false in postfire. Increment the number of iterations. If the "iterations" parameter is greater than zero, then see if the limit has been reached. If so, return false. Otherwise return true if all of the fired actors since the last call to prefire returned true.

Returns:
True if the Director wants to be fired again in the future.
Throws:
ptolemy.kernel.util.IllegalActionException - If the iterations parameter does not contain a legal value.

transferInputs

public boolean transferInputs(ptolemy.actor.IOPort port)
                       throws ptolemy.kernel.util.IllegalActionException
Override the base class method to transfer enough tokens to complete an internal iteration. If there are not enough tokens, then throw an exception. If the port is not connected on the inside, or has a narrower width on the inside than on the outside, then consume exactly one token from the corresponding outside channels and discard it. Thus, a port connected on the outside but not on the inside can be used as a trigger for an SDF composite actor.

Parameters:
port - The port to transfer tokens from.
Returns:
True if data are transferred.
Throws:
ptolemy.kernel.util.IllegalActionException - If the port is not an opaque input port, or if there are not enough input tokens available.

transferOutputs

public boolean transferOutputs(ptolemy.actor.IOPort port)
                        throws ptolemy.kernel.util.IllegalActionException
Override the base class method to transfer enough tokens to fulfill the output production rate. This behavior is required to handle the case of non-homogeneous opaque composite actors. The port argument must be an opaque output port. If any channel of the output port has no data, then that channel is ignored.

Parameters:
port - The port to transfer tokens from.
Returns:
True if data are transferred.
Throws:
ptolemy.kernel.util.IllegalActionException - If the port is not an opaque output port.

_writeAccessRequired

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

Returns:
false.