Package ptolemy.domains.sdf.kernel

Class SDFDirector

  • All Implemented Interfaces:
    java.lang.Cloneable, Executable, Initializable, PeriodicDirector, Changeable, Debuggable, DebugListener, Derivable, ModelErrorHandler, MoMLExportable, Moveable, Nameable
    Direct Known Subclasses:
    DistributedSDFDirector, DTDirector, HDFDirector, MetroIISequentialSDFDirector, OptimizingSDFDirector, PSDFDirector, PthalesDirector
    public class SDFDirector
extends StaticSchedulingDirector
implements PeriodicDirector
    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

    • The number of tokens accumulated on every relation is bounded, given an infinite number of executions of the schedule.
    • Deadlock will never occur, given an infinite number of executions of the schedule.

    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 SDFScheduler for more information. The SampleDelay actor is usually used in a model to specify the delay across a relation.

    The allowDisconnectedGraphs parameter of this director determines 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 of the allowDisconnectedGraphs parameter is a BooleanToken with the value false.

    The iterations parameter of this director corresponds to a limit on the number of times the director will fire its hierarchy before it returns false in postfire. If this number is not greater than zero, then no limit is set and postfire will always return true. The default value of the iterations parameter is an IntToken with value one.

    If any actor's postfire() method returns false during an iteration, then at the conclusion of the iteration, this director's postfire() method will return false. This will normally result in termination of the execution. The reasoning for this behavior is that the model cannot continue executing without the participation of all actors, and if any actor returns false in postfire(), then it is indicating that it wishes to not continue executing.

    The vectorizationFactor parameter of this director sets the number of times that the basic schedule is executed during each firing of this director. This might allow the director to execute the model more efficiently, by combining multiple firings of each actor. The default value of the vectorizationFactor parameter is an IntToken with value one.

    The SDF 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 calls fireAt(currentTime + period) in postfire().

    This behavior gives an interesting use of SDF within DE: You can "kick start" an SDF submodel with a single event, and then if the director of that SDF submodel has a period greater than 0.0, then it will continue to 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 0.2
    Version:
    $Id$
    Author:
    Steve Neuendorffer, Contributor: Christopher Brooks
    See Also:
    SDFScheduler, SDFReceiver
    Pt.AcceptedRating:
    Yellow (cxh)
    Pt.ProposedRating:
    Yellow (cxh)

    • Field Detail

      • allowDisconnectedGraphs

        public 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 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 true, then such models are valid and this class dynamically computes a new schedule at runtime. If this parameter is false, 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 false. This is a boolean with default value false.

      • constrainBufferSizes

        public Parameter constrainBufferSizes
        If true, then buffer sizes are fixed according to the schedule, and attempts to write to the buffer that cause the buffer to exceed the schedule size result in an exception. This method works by setting the capacity of the receivers if the value is true. This parameter is a boolean that defaults to true.

      • iterations

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

        If the number of iterations is -1, which is the value of the AUTO choice in the UI, then if the container of the director is the the top level then one iteration will occur before postfire() returns false.

        If the number of iterations is -1 and and the container of the director is not at the top level then postfire() will always return true and execution will continue forever.

        The default value is an IntToken with the value AUTO, which is -1. The UI has a second choice: UNBOUNDED, which is 0.

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

      • synchronizeToRealTime

        public Parameter synchronizeToRealTime
        Specify whether the execution should synchronize to the real time. This parameter has type boolean and defaults to false. If set to true, then this director stalls in the prefire() method until the elapsed real real time matches the product of the period parameter value and the iteration count. If the period parameter has value 0.0 (the default), then changing this parameter to true has no effect.

      • vectorizationFactor

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

      • AUTO_INTTOKEN

        public static final IntToken AUTO_INTTOKEN
        The value used to signify special behavior for the iterations parameter.

      • AUTO_NAME

        public static final java.lang.String AUTO_NAME
        The name of the AUTO iterations parameter choice: "AUTO".
        See Also:
        Constant Field Values

      • UNBOUNDED_INTTOKEN

        public static final IntToken UNBOUNDED_INTTOKEN
        The UNBOUNDED iterations choice is equivalent to IntToken.ZERO.

      • UNBOUNDED_NAME

        public static final java.lang.String UNBOUNDED_NAME
        The name of the UNBOUNDED iterations parameter choice: "UNBOUNDED".
        See Also:
        Constant Field Values

      • ITERATIONS_NAME

        public static final java.lang.String ITERATIONS_NAME
        The name of the iterations parameter: "iterations".
        See Also:
        Constant Field Values

      • _iterationCount

        protected int _iterationCount
        The iteration count.

      • _periodicDirectorHelper

        protected PeriodicDirectorHelper _periodicDirectorHelper
        Helper class supporting the period parameter.

    • Constructor Detail

      • SDFDirector

        public SDFDirector()
            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. The SDFDirector will have a default scheduler of type SDFScheduler.
        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.

      • SDFDirector

        public SDFDirector​(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. The SDFDirector will have a default scheduler of type SDFScheduler.
        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.

      • SDFDirector

        public SDFDirector​(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. The SDFDirector will have a default scheduler of type SDFScheduler.
        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 a derived class.
        NameDuplicationException - If the container is not a CompositeActor and the name collides with an entity 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 local copy of the parameter value will be updated.
        Overrides:
        attributeChanged in class Director
        Parameters:
        attribute - The changed parameter.
        Throws:
        IllegalActionException - If the parameter set is not valid.

      • getIterations

        public int getIterations()
                  throws IllegalActionException
        Return the number of iterations.

        The number of iterations returned depends on the value of the iterations parameter and whether the container of the director is at the top level. See the iterations documentation for details.

        Code that uses SDFDirector should call getIterations() instead of directly referring to the value of the iterations parameter.

        Returns:
        the number of iterations
        Throws:
        IllegalActionException - If thrown while getting the value of the iterations parameter.

      • fireAt

        public Time fireAt​(Actor actor,
                   Time time,
                   int microstep)
            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.
        microstep - The microstep (ignored by this director).
        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), Director.fireContainerAt(Time)

      • initialize

        public void initialize()
                throws 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.
        Specified by:
        initialize in interface Initializable
        Overrides:
        initialize in class StaticSchedulingDirector
        Throws:
        IllegalActionException - If the initialize() method of one of the associated actors throws it, or if there is no scheduler.

      • newReceiver

        public Receiver newReceiver()
        Return a new receiver consistent with the SDF domain.
        Overrides:
        newReceiver in class Director
        Returns:
        A new SDFReceiver.

      • prefire

        public boolean prefire()
                throws 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.

        This method also implements the functionality of synchronizeToRealTime by waiting for real time to elapse if the parameter value is true.

        Specified by:
        prefire in interface Executable
        Overrides:
        prefire in class StaticSchedulingDirector
        Returns:
        true If all of the input ports of the container of this director have enough tokens.
        Throws:
        IllegalActionException - If port methods throw it.

      • preinitialize

        public void preinitialize()
                   throws 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.
        Specified by:
        preinitialize in interface Initializable
        Overrides:
        preinitialize in class Director
        Throws:
        IllegalActionException - If the preinitialize() method of one of the associated actors throws it.

      • postfire

        public boolean postfire()
                 throws 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. 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 StaticSchedulingDirector
        Returns:
        True if the Director wants to be fired again in the future.
        Throws:
        IllegalActionException - If the iterations parameter does not contain a legal value.

      • suggestedModalModelDirectors

        public java.lang.String[] suggestedModalModelDirectors()
        Return an array of suggested ModalModel directors to use with SDFDirector. The default director is HDFFSMDirector, which supports multirate actors and only allows state transitions on each iteration. This is the most safe director to use with SDF models. MultirateFSMDirector supports multirate actors and allows state transitions on each firing of the modal model. MultirateFSMDirector can be used with SDF if rate signatures for all the states in the modal model are same. If rate signatures change during an iteration, the SDFDirector will throw an exception. FSMDirector can be used with SDFDirector only when rate signatures for modal model are all 1.
        Overrides:
        suggestedModalModelDirectors in class Director
        Returns:
        An array of suggested directors to be used with ModalModel.
        See Also:
        Director.suggestedModalModelDirectors()

      • supportMultirateFiring

        public boolean supportMultirateFiring()
        Return true to indicate that a ModalModel under control of this director supports multirate firing.
        Overrides:
        supportMultirateFiring in class Director
        Returns:
        True indicating a ModalModel under control of this director supports multirate firing.

      • transferInputs

        public boolean transferInputs​(IOPort port)
                       throws 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.
        Overrides:
        transferInputs in class Director
        Parameters:
        port - The port to transfer tokens from.
        Returns:
        True if data are transferred.
        Throws:
        IllegalActionException - If the port is not an opaque input port, or if there are not enough input tokens available.

      • transferOutputs

        public boolean transferOutputs​(IOPort port)
                        throws 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.
        Overrides:
        transferOutputs in class Director
        Parameters:
        port - The port to transfer tokens from.
        Returns:
        True if data are transferred.
        Throws:
        IllegalActionException - If the port is not an opaque output port.