ptolemy.domains.sr.kernel
Class SRDirector

java.lang.Object
  ptolemy.kernel.util.NamedObj
      ptolemy.kernel.util.Attribute
          ptolemy.actor.Director
              ptolemy.actor.sched.StaticSchedulingDirector
                  ptolemy.actor.sched.FixedPointDirector
                      ptolemy.domains.sr.kernel.SRDirector

All Implemented Interfaces:

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

public class SRDirector
extends FixedPointDirector
implements PeriodicDirector

A director for the Synchronous Reactive (SR) model of computation. The SR model of computation has a notion of a global "tick" of a clock, and at each tick of the clock, each port either has a value or is "absent." The job of this director is determine what that value is for each connection between ports. An iteration of this director is one tick of this global clock.

Execution proceeds as follows. The director checks each actor to determine whether it is strict or not by calling its isStrict() method (here, "strict" means that all inputs must be known before the actor can specify any outputs). By default, actors are strict. Strict actors are fired only once in an iteration. Their inputs are all known (and may absent) when prefire() is invoked. If prefire() returns true, the fire() and postfire() are invoked exactly once.

Specialized actors may be non-strict, meaning that they are able to produce outputs even their inputs are not known. Such actors must conform to certain requirements in order to ensure determinacy. First, such actors should check input ports by calling their isKnown() method before calling hasToken() to determine whether the port is "absent." Only if both isKnown() and hasToken() return true should the actor call get() on that port. A non-strict actor may be prefired and fired repeatedly in an iteration if some of the inputs are unknown. Once an actor is fired with all its inputs known, it will not be fired again in the same iteration. A composite actor containing this director is a non-strict actor.

Each actor's fire() method implements a (possibly state-dependent) function from input ports to output ports. At each tick of the clock, the fire() method of each non-strict actor may be evaluated multiple times, and each time, it must implement the same function. Thus, the actors are required to conform with the strict actor semantics, which means that they do not change their state in the prefire() or fire() methods, and only change their state in postfire(). This helps ensure that the actor is monotonic. Montonicity implies three constraints on the actor. First, if prefire() ever returns true during an iteration, then it will return true on all subsequent invocations of prefire() in the same iteration(). In subsequent iterations, inputs may become known, but once they are known, the value of the input and whether it is present cannot change in subsequent firings in the same iteration. Second, if either prefire() or fire() call clear() on an output port, then no subsequent invocation in the same iteration can call put() on the port. Third, if prefire() or fire() call put() on an output port with some token, then no subsequent invocation in the same iteration can call clear() or put() with a token with a different value. These constraints ensure determinacy.

If synchronizeToRealTime is set to true, then the postfire() method stalls until the real time elapsed since the model started matches the current time. This ensures that the director does not get ahead of real time. However, of course, this does not ensure that the director keeps up with real time. Note that this synchronization occurs after actors have been fired, but before they have been postfired.

The SR director has a period parameter which specifies the amount of model time that elapses per iteration. If the value of period is 0.0 (the default), then it has no effect, and this director never increments time nor calls fireAt() on the enclosing director. If the period is greater than 0.0, then if this director is at the top level, it increments time by this amount in each invocation of postfire(). If it is not at the top level, then it refuses to fire at times that do not match a multiple of the period (by returning false in prefire()), and if it fires, it calls fireAt(currentTime + period) in postfire().

This behavior gives an interesting use of SR within DE or Continuous. In particular, if set a period other than 0.0, the composite actor with this SR director will fire periodically with the specified period.

If period is greater than 0.0 and the parameter synchronizeToRealTime is set to true, then the prefire() method stalls until the real time elapsed since the model started matches the period multiplied by the iteration count. This ensures that the director does not get ahead of real time. However, of course, this does not ensure that the director keeps up with real time.

Since:

Ptolemy II 2.0

Version:

$Id: SRDirector.java 57046 2010-01-27 23:35:53Z cxh $

Author:

Paul Whitaker, Edward A. Lee, Contributor: Ivan Jeukens, Haiyang Zheng

See Also:

Serialized Form

Accepted Rating:

Green (pwhitake)

Proposed Rating:

Green (pwhitake)

Nested Class Summary

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

NamedObj.ContainedObjectsIterator

Field Summary

private PeriodicDirectorHelper	_periodicDirectorHelper Helper class supporting the period parameter.
Parameter	period The time period of each iteration.

Fields inherited from class ptolemy.actor.sched.FixedPointDirector

_index, _receivers, iterations, synchronizeToRealTime

Fields inherited from class ptolemy.actor.sched.StaticSchedulingDirector

_postfireReturns

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

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

private void	_init() Initialize the object.
java.lang.Object	clone(Workspace workspace) Clone the object into the specified workspace.
Time	fireAt(Actor actor, Time time) Request a firing of the given actor at the given absolute time, and return the time at which the specified will be fired.
Time	getModelNextIterationTime() Return the time value of the next iteration.
void	initialize() Initialize the director and all deeply contained actors by calling the super.initialize() method.
double	periodValue() Return the value of the period as a double.
boolean	postfire() Call postfire() on all contained actors that were fired on the last invocation of fire().
boolean	prefire() Invoke super.prefire(), which will synchronize to real time, if appropriate.

Methods inherited from class ptolemy.actor.sched.FixedPointDirector

_receiverChanged, _resetAllReceivers, _synchronizeToRealTime, fire, getIndex, implementsStrictActorSemantics, isFireFunctional, isStrict, newReceiver, setIndex, suggestedModalModelDirectors, transferInputs, transferOutputs

Methods inherited from class ptolemy.actor.sched.StaticSchedulingDirector

_setScheduler, addDebugListener, getScheduler, invalidateSchedule, isScheduleValid, removeDebugListener, setScheduler

Methods inherited from class ptolemy.actor.Director

_description, _fireContainerAt, _isEmbedded, _isTopLevel, _transferInputs, _transferOutputs, addInitializable, attributeChanged, createSchedule, defaultDependency, finish, fireAt, fireAtCurrentTime, getCausalityInterface, getCurrentTime, getErrorTolerance, getGlobalTime, getModelStartTime, getModelStopTime, getModelTime, getNextIterationTime, getStartTime, getStopTime, getTimeResolution, initialize, invalidateResolvedTypes, isStopRequested, iterate, preinitialize, preinitialize, removeInitializable, requestInitialization, setContainer, setCurrentTime, setModelTime, stop, stopFire, supportMultirateFiring, terminate, wrapup

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, 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, 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.Executable

fire, isFireFunctional, isStrict, iterate, stop, stopFire, terminate

Methods inherited from interface ptolemy.actor.Initializable

addInitializable, preinitialize, removeInitializable, wrapup

Methods inherited from interface ptolemy.kernel.util.Nameable

description, getContainer, getDisplayName, getFullName, getName, getName, setName

Field Detail

period

public Parameter period

The time period of each iteration. This parameter has type double and default value 0.0, which means that this director does not increment model time and does not request firings by calling fireAt() on any enclosing director. If the value is set to something greater than 0.0, then if this director is at the top level, it will increment model time by the specified amount in its postfire() method. If it is not at the top level, then it will call fireAt() on the enclosing executive director with the argument being the current time plus the specified period.

_periodicDirectorHelper

private PeriodicDirectorHelper _periodicDirectorHelper

Helper class supporting the period parameter.

Constructor Detail

SRDirector

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

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.

SRDirector

public SRDirector(Workspace workspace)
           throws IllegalActionException,
                  NameDuplicationException

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.

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.

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

clone

public java.lang.Object clone(Workspace workspace)
                       throws java.lang.CloneNotSupportedException

Clone the object into the specified workspace. The new object is not added to the directory of that workspace (you must do this yourself if you want it there).

Overrides:

clone in class FixedPointDirector

Parameters:

workspace - The workspace for the cloned object.

Returns:

The new Attribute.

Throws:

java.lang.CloneNotSupportedException - Not thrown in this base class

See Also:

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

fireAt

public Time fireAt(Actor actor,
                   Time time)
            throws IllegalActionException

Request a firing of the given actor at the given absolute time, and return the time at which the specified will be fired. If the period is 0.0 and there is no enclosing director, then this method returns the current time. If the period is 0.0 and there is an enclosing director, then this method delegates to the enclosing director, returning whatever it returns. If the period is not 0.0, then this method checks to see whether the requested time is equal to the current time plus an integer multiple of the period. If so, it returns the requested time. If not, it returns current time plus the period.

Overrides:

fireAt in class Director

Parameters:

actor - The actor scheduled to be fired.

time - The requested time.

Returns:

Either the requested time or the current time plus the period.

Throws:

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

See Also:

Director.fireAtCurrentTime(Actor)

getModelNextIterationTime

public Time getModelNextIterationTime()

Return the time value of the next iteration. If this director is at the top level, then the returned value is the current time plus the period. Otherwise, this method delegates to the executive director.

Overrides:

getModelNextIterationTime in class Director

Returns:

The time of the next iteration.

See Also:

Director.getModelTime()

initialize

public void initialize()
                throws IllegalActionException

Initialize the director and all deeply contained actors by calling the super.initialize() method. If the period parameter is greater than zero, then request a first firing of the executive director, if there is one.

Specified by:

initialize in interface Initializable

Overrides:

initialize in class FixedPointDirector

Throws:

IllegalActionException - If the superclass throws it.

periodValue

public double periodValue()
                   throws IllegalActionException

Return the value of the period as a double.

Specified by:

periodValue in interface PeriodicDirector

Returns:

The value of the period as a double.

Throws:

IllegalActionException - If the period parameter cannot be evaluated

prefire

public boolean prefire()
                throws IllegalActionException

Invoke super.prefire(), which will synchronize to real time, if appropriate. Then if the period parameter is zero, return whatever the superclass returns. Otherwise, return true only if the current time of the enclosing director (if there is one) matches a multiple of the period. If the current time of the enclosing director exceeds the time at which we next expected to be invoked, then adjust that time to the least multiple of the period that either matches or exceeds the time of the enclosing director.

Specified by:

prefire in interface Executable

Overrides:

prefire in class FixedPointDirector

Returns:

true If current time is appropriate for a firing.

Throws:

IllegalActionException - If the period parameter cannot be evaluated.

postfire

public boolean postfire()
                 throws IllegalActionException

Call postfire() on all contained actors that were fired on the last invocation of fire(). Return false if the model 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 requested. This method is called only once for each iteration. Note that actors are postfired in arbitrary order.

If the period parameter is greater than 0.0, then if this director is at the top level, then increment time by the specified period, and otherwise request a refiring at the current time plus the period.

Specified by:

postfire in interface Executable

Overrides:

postfire in class FixedPointDirector

Returns:

True if the Director wants to be fired again in the future.

Throws:

IllegalActionException - If the iterations or period parameter does not contain a legal value.

_init

private void _init()
            throws IllegalActionException,
                   NameDuplicationException

Initialize the object. In this case, we give the SDFDirector a default scheduler of the class SDFScheduler, an iterations parameter and a vectorizationFactor parameter.

Throws:

IllegalActionException

NameDuplicationException