Package ptolemy.domains.dt.kernel

Class DTDirector

  • All Implemented Interfaces:
    java.lang.Cloneable, Executable, Initializable, PeriodicDirector, Changeable, Debuggable, DebugListener, Derivable, ModelErrorHandler, MoMLExportable, Moveable, Nameable
    public class DTDirector
extends SDFDirector
    The Discrete Time (DT) domain director.

    DT overview

    The Discrete Time (DT) domain is a timed extension of the Synchronous Dataflow (SDF) domain. Like SDF, it has static scheduling of the dataflow graph model. Similarly, DT requires that the data rates on the ports of all actors be known beforehand and fixed. DT handles feedback systems in the same way that SDF does, but with additional constraints on initial tokens.

    Local and Global Time

    Because of the inherent concurrency occurring within SDF models, there are two notions of time in DT -- global time and local time. Global time increases steadily as execution progresses. Moreover, global time increases by fixed discrete amounts given by the period parameter. On the other hand, each receiver is associated with an independent local time. All the receivers have distinct local times as an iteration proceeds. The local time of a receiver during an iteration depends on the global time, period, firing count, port rates, and the schedule. These local times obey the following constraint:

    Global Time <= Local Time <= (Global Time + period)

    The exact way that local time increments during an iteration is described in detail in the DTReceiver documentation.

    n

    Period Parameter

    The DT director has a period parameter which specifies the amount of time per iteration. For hierarchical DT, this period parameter only makes sense on the top-level. The user cannot explicitly set the period parameter for a DT subsystem inside another DT system. For heterogeneous hierarchies (e.g. DT inside DE or DT inside CT), the period parameter specifies the time interval between firings of the DT subsystem. The DT subsystem will not fire on times that are not integer multiples of the period parameter.

    DT Features

    The design of the DT domain is motivated by the following criteria:

    1. ) Uniform Token Flow: The time interval between tokens should be regular and unchanging. This conforms to the idea of having sampled systems with fixed rates. Although the tokens flowing in DT do not keep internal time stamps, each actor can query the DT director for its own local time. This local time is uniformly increasing by a constant fraction of the director's period. Local time is incremented every time the get() method is called to obtain a token.
    2. ) Causality: Tokens produced by an actor should only depend on tokens produced or consumed in the past. This makes sense because we don't expect an actor to produce a token before it can calculate the token's value. For example, if an actor needs three tokens A, B, and C to compute token D, then the time when tokens A, B, and C are consumed should be earlier than or equal to the time when token D is produced. Note that in DT, time does not get incremented due to computation.
    3. ) SDF-style semantics: Ideally, we want DT to be a timed-superset of SDF with compatible token flow and scheduling. However, we can only approximate this behavior. It is not possible to have uniform token flow, causality, and SDF-style semantics at the same time. Causality breaks for non-homogeneous actors in a feedback system when fully-compatible SDF-style semantics is adopted. To remedy this situation, every actor in DT that has non-homogeneous input ports should produce initial tokens at each of its output ports.

    Design Notes

    DT (Discrete Time) is a timed model of computation. In order to benefit from the internal time-keeping mechanism of DT, one should use actors aware of time. For example, one should use TimedPlotter or TimedScope instead of SequencePlotter or SequenceScope.

    Top-level DT Directors have a period parameter that can be set by the user. Setting the period parameter of a non-top-level DT Director under hierarchical DT has no meaning; and hence will be ignored.

    Domain-polymorphic actors that want to take advantage of the multi-rate timing capabilities of DT should call getCurrentTime(channel_number) for every get(channel_number). Moreover, the call sequence should be ordered as follows: getCurrentTime(channel_number) before get(channel_number).

    Known bugs: 

     1.) Put more tests on this case: when events come in faster than the period
 of a DT composite actor (e.g clock feeding DT)
 2.) Put more tests on this case: when DT composite actor doesn't fire because
 there aren't enough tokens.
 3.) Domain-polymorphic actors that use getCurrentTime() should be modified
 to use DT's multirate timing capabilities.
 CurrentTime  - modified
 TimedPlotter - modified
 TimedScope   - modified
 SequentialClock - no input ports, gets global time only
 PoissonClock - under investigation
 Clock        - under investigation
 Expression   - under investigation
 4.) This director does not implement fireAt(). Instead, it inherits
 the implementation from SDF, which isn't quite correct. It does not always
 return the correct next time of firing. As a workaround, this class does not
 check the values returned by fireAt(). Thus, if it is embedded in a domain
 that does not respect the calls to fireAt(), then the user could get
 odd behavior without any error reported.
    Since:
    Ptolemy II 1.0
    Version:
    $Id$
    Author:
    C. Fong
    See Also:
    DTReceiver, SDFDirector, SDFReceiver, SDFScheduler
    Pt.AcceptedRating:
    Yellow (vogel)
    Pt.ProposedRating:
    Yellow (chf)

    • Constructor Detail

      • DTDirector

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

      • DTDirector

        public DTDirector​(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.
        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.

      • DTDirector

        public DTDirector​(CompositeEntity container,
                  java.lang.String name)
           throws IllegalActionException,
                  NameDuplicationException
        Construct a director in the given container with the given name. If the container argument is null, 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 container is 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 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). The result is an object with no container.
        Overrides:
        clone in class SDFDirector
        Parameters:
        workspace - The workspace for the cloned object.
        Returns:
        The new object.
        Throws:
        java.lang.CloneNotSupportedException - Not thrown in this base class
        See Also:
        NamedObj.exportMoML(Writer, int, String), NamedObj.setDeferringChangeRequests(boolean)

      • fire

        public void fire()
          throws IllegalActionException
        Go through the schedule and iterate every actor with calls to prefire() , fire() , and postfire(). If this director is not in the top-level, get the outside director's current time; and check whether the returned time is an integer multiple of the period parameter. If it is not, then don't fire.
        Specified by:
        fire in interface Executable
        Overrides:
        fire in class SDFDirector
        Throws:
        IllegalActionException - If an actor executed by this director returns false in its prefire().

      • getPeriod

        public double getPeriod()
                 throws IllegalActionException
        Get the global time increment per iteration for this director. This is a convenience method for getting the period parameter. For hierarchical DT (DT inside DT), extra calculation is done to compute the period as a fraction of the outside period.
        Returns:
        The value of the period parameter.
        Throws:
        IllegalActionException - If the period parameter is is not of type DoubleToken or IntToken.

      • initialize

        public void initialize()
                throws IllegalActionException
        Initialize all the actors associated with this director by calling super.initialize(). Determine which actors need to generate initial tokens for causality. All actors with nonhomogeneous input ports will need to generate initial tokens for all of their output ports. For example, if actor A has a nonhomogeneous input port and an output port with production rate 'm' then actor A needs to produce 'm' initial tokens on the output port.
        Specified by:
        initialize in interface Initializable
        Overrides:
        initialize in class SDFDirector
        Throws:
        IllegalActionException - If the initialize() method of one of the associated actors throws it.

      • newReceiver

        public Receiver newReceiver()
        Return a new receiver consistent with the DT domain.
        Overrides:
        newReceiver in class SDFDirector
        Returns:
        A new DTReceiver.

      • 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. Always return true in order to allow firing or pseudo-firing. Pseudo-firing is needed when DT is interacting hierarchically with DE.
        Specified by:
        prefire in interface Executable
        Overrides:
        prefire in class SDFDirector
        Returns:
        True.
        Throws:
        IllegalActionException - If the parent class throws it.

      • setActorLocalTime

        public void setActorLocalTime​(Time newTime,
                              Actor actor)
        Set the local time of an actor in the model under this director. This method is called by the DTReceiver class and doesn't need to be called by any other classes.
        Parameters:
        newTime - The new current simulation time.
        actor - The actor to be assigned a new local time

      • transferInputs

        public boolean transferInputs​(IOPort port)
                       throws IllegalActionException
        Override the base class method to make sure that enough tokens are available to complete one iteration. This behavior is required to handle the case of non-homogeneous opaque composite actors. The port argument must be an opaque input port. If any channel of the input port has no data, then that channel is ignored.
        Overrides:
        transferInputs in class SDFDirector
        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.

      • transferOutputs

        public boolean transferOutputs​(IOPort port)
                        throws IllegalActionException
        This is called by the outside director to get tokens from an opaque composite actor. Return true if data is transferred from an output port of the container to the ports it is connected to on the outside. This method differs from the base class method in that this method will transfer all available tokens in the receivers, while the base class method will transfer at most one token. 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 SDFDirector
        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.

      • _getRepetitions

        protected int _getRepetitions​(Actor actor)
                       throws IllegalActionException
        Get the number of times an actor repeats in the schedule of an SDF graph. If the actor does not exist, throw an exception.
        Parameters:
        actor - The actor whose firing count is needed.
        Returns:
        The number of times an actor repeats in the schedule.
        Throws:
        IllegalActionException - If actor does not exist.