Package ptolemy.actor.sched

Class FixedPointDirector

  • All Implemented Interfaces:
    java.lang.Cloneable, Executable, Initializable, SuperdenseTimeDirector, Changeable, Debuggable, DebugListener, Derivable, ModelErrorHandler, MoMLExportable, Moveable, Nameable
    Direct Known Subclasses:
    ContinuousDirector, SRDirector
    public class FixedPointDirector
extends StaticSchedulingDirector
implements SuperdenseTimeDirector
    A base class for directors that have fixed point semantics at each iteration. An iteration consists of repeated firings of the actors controlled by this director until a fixed point is reached. An iteration has converged if firing actors will not change signal status any more.

    At the beginning of each iteration, the status of all inputs and outputs is unknown. Upon firing an actor, the status of its output signals may become known. Once the status of a signal becomes known, it cannot be changed back to unknown in the iteration. This monotonicity constraint ensures the existence and uniqueness of the fixed point. During an iteration, the prefire() and fire() methods of the controlled actors may be repeatedly invoked, but the postfire() method will be invoked exactly once after the fixed point has been found. The postfire() methods of the contained actors are invoked only in the postfire() method of this director, and they are invoked in arbitrary order.

    If the prefire() method of an actor returns false, then this director assumes that all the outputs of the actor are absent. The actor has declined to fire.

    Although this director does not require any specific ordering of actor firings, a scheduler is used to choose an efficient ordering.

    By default, actors are strict, which means that all their input signals must be known before the actor can be fired. Here, what we mean by "fired" is that prefire() is invoked, and if it returns true, then fire() is invoked. Such actors will be fired only once in an iteration. A non-strict actor can be fired regardless of the status of its inputs, and may be 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.

    For an actor to be used under the control of this director, it must either be strict, or if it is non-strict, it must be monotonic. Montonicity implies two constraints on the actor. First, if prefire() ever returns true during an iteration, then it will return true on all subsequent invocations 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. 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.

    This class is based on the original SRDirector, written by Paul Whitaker.

    Since:
    Ptolemy II 5.2
    Version:
    $Id$
    Author:
    Haiyang Zheng and Edward A. Lee
    Pt.AcceptedRating:
    Yellow (eal)
    Pt.ProposedRating:
    Green (hyzheng)

    • Field Detail

      • iterations

        public Parameter iterations
        The number of times that postfire may be called before it returns false. The type must be int, 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.

      • 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 current time. If the period parameter has value 0.0 (the default), then changing this parameter to true has no effect. Note that in this base class, there is no period parameter and time is never advanced, so this will have no effect. It has effect in derived classes.

      • _actorsAllowedToFire

        protected java.util.Set _actorsAllowedToFire
        The set of actors that have returned true in their prefire() methods in the current iteration. This is used only to check monotonicity constraints and to determine which actors should be postfired.

      • _actorsFired

        protected java.util.Set _actorsFired
        Actors that were fired in the most recent invocation of the fire() method.

      • _index

        protected int _index
        The current index of the model.

      • _receivers

        protected java.util.List _receivers
        List of all receivers this director has created.

      • _actorsFinishedFiring

        protected java.util.Set _actorsFinishedFiring
        The set of actors that have been fired in this iteration with all inputs known.

    • Constructor Detail

      • FixedPointDirector

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

      • FixedPointDirector

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

      • FixedPointDirector

        public FixedPointDirector​(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 director into the specified workspace. This calls the base class and then sets the attribute public members to refer to the attributes of the new director.
        Overrides:
        clone in class StaticSchedulingDirector
        Parameters:
        workspace - The workspace for the new director.
        Returns:
        A new director.
        Throws:
        java.lang.CloneNotSupportedException - If a derived class contains an attribute that cannot be cloned.
        See Also:
        NamedObj.exportMoML(Writer, int, String), NamedObj.setDeferringChangeRequests(boolean)

      • fire

        public void fire()
          throws IllegalActionException
        Prefire and fire actors in the order given by the scheduler until the iteration converges. An iteration converges when a pass through the schedule does not change the status of any receiver.
        Specified by:
        fire in interface Executable
        Overrides:
        fire in class StaticSchedulingDirector
        Throws:
        IllegalActionException - If an actor violates the monotonicity constraints, or the prefire() or fire() method of the actor throws it.

      • getIndex

        public int getIndex()
        Return the current index of the director. The current index is a portion of the superdense time. Superdense time means that time is a real value and an index, allowing multiple sequential steps to occur at a fixed (real) time.
        Specified by:
        getIndex in interface SuperdenseTimeDirector
        Returns:
        the superdense time index
        See Also:
        setIndex(int), SuperdenseTimeDirector

      • getModelNextIterationTime

        public Time getModelNextIterationTime()
                               throws IllegalActionException
        Return the next time of interest in the model being executed by this director or the director of any enclosing model up the hierarchy. If this director is at the top level, then this default implementation simply returns infinity, indicating that this director has no interest in any future time. If this director is not at the top level, then return whatever the enclosing director returns.

        This method is useful for domains that perform speculative execution (such as Continuous itself). Such a domain in a hierarchical model (i.e. CT inside DE) uses this method to determine how far into the future to execute. This is simply an optimization that reduces the likelihood of having to roll back.

        The base class implementation in Director is almost right, but not quite, because at the top level it returns current time. However, this director should not constrain any director below it from speculatively executing into the future. Instead, it assumes that any director below it implements a strict actor semantics. Note in particular that the implementation below would block time advancement in a Continuous in DE in Continuous model because the top-level model will usually only invoke the DE model during a zero-step execution, which means that the returned next iteration time will always be current time, which will force the inside Continuous director to have a zero step size always.

        Overrides:
        getModelNextIterationTime in class Director
        Returns:
        The next time of interest.
        Throws:
        IllegalActionException - If creating a Time object fails.
        See Also:
        Director.getModelTime()

      • implementsStrictActorSemantics

        public boolean implementsStrictActorSemantics()
        Return true, indicating that this director assumes and exports the strict actor semantics, as described in this paper:

        A. Goderis, C. Brooks, I. Altintas, E. A. Lee, and C. Goble, "Heterogeneous Composition of Models of Computation," EECS Department, University of California, Berkeley, Tech. Rep. UCB/EECS-2007-139, Nov. 2007. http://www.eecs.berkeley.edu/Pubs/TechRpts/2007/EECS-2007-139.html

        In particular, a director that implements this interface guarantees that it will not invoke the postfire() method of an actor until all its inputs are known at the current tag. Moreover, it it will only do so in its own postfire() method, and in its prefire() and fire() methods, it does not change its own state. Thus, such a director can be used within a model of computation that has a fixed-point semantics, such as SRDirector and ContinuousDirector.

        Overrides:
        implementsStrictActorSemantics in class Director
        Returns:
        True.

      • isFireFunctional

        public boolean isFireFunctional()
        Return true if all the controlled actors' isFireFunctional() methods return true. Otherwise, return false.
        Specified by:
        isFireFunctional in interface Executable
        Overrides:
        isFireFunctional in class Director
        Returns:
        True if all controlled actors are functional. Return false if there is no container or no actors in the container.

      • isStrict

        public boolean isStrict()
        Return false. The transferInputs() method checks whether the inputs are known before calling hasToken(). Thus this director tolerates unknown inputs.
        Specified by:
        isStrict in interface Executable
        Overrides:
        isStrict in class Director
        Returns:
        False.

      • newReceiver

        public Receiver newReceiver()
        Return a new FixedPointReceiver. If a subclass overrides this method, the receiver it creates must be a subclass of FixedPointReceiver, and it must add the receiver to the _receivers list (a protected member of this class).
        Overrides:
        newReceiver in class Director
        Returns:
        A new FixedPointReceiver.

      • postfire

        public boolean postfire()
                 throws IllegalActionException
        Call postfire() on all contained actors that were fired in the current iteration. 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, or if no actors fired at all in the last iteration. This method is called only once for each iteration. Note that actors are postfired in arbitrary order.
        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, or if there still some unknown inputs (which indicates a causality loop).

      • suggestedModalModelDirectors

        public java.lang.String[] suggestedModalModelDirectors()
        Return an array of suggested directors to be used with ModalModel. Each director is specified by its full class name. The first director in the array will be the default director used by a modal model.
        Overrides:
        suggestedModalModelDirectors in class Director
        Returns:
        An array of suggested directors to be used with ModalModel.
        See Also:
        Director.suggestedModalModelDirectors()

      • 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 sendInside(index, null). This method delegates the data transfer operation to the transferInputs method of the super class.
        Overrides:
        transferInputs in class Director
        Parameters:
        port - The port to transfer tokens from.
        Returns:
        True if at least one token is transferred.
        Throws:
        IllegalActionException - If the port is not an opaque input port.

      • 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 send(index, null). This method delegates the data transfer operation to the transferOutputs method of the super class.
        Overrides:
        transferOutputs in class Director
        Parameters:
        port - The port to transfer tokens from.
        Returns:
        True if at least one token is transferred.
        Throws:
        IllegalActionException - If the port is not an opaque input port, or if there are not enough input tokens available.

      • _areAllInputsKnown

        protected boolean _areAllInputsKnown​(Actor actor)
                              throws IllegalActionException
        Return true if all the inputs of the specified actor are known.
        Parameters:
        actor - The specified actor.
        Returns:
        True if the all the inputs of the specified actor are known.
        Throws:
        IllegalActionException - If thrown while checking if an input port is known.

      • _fireActor

        protected void _fireActor​(Actor actor)
                   throws IllegalActionException
        Fire an actor. Call its prefire() method, and if that returns true, call its fire() method.
        Parameters:
        actor - The actor to be fired.
        Throws:
        IllegalActionException - If the prefire() method returns false having previously returned true in the same iteration, or if the prefire() or fire() method of the actor throws it.

      • _hasIterationConverged

        protected boolean _hasIterationConverged()
                                  throws IllegalActionException
        Return true if this iteration has converged. The iteration has converged if both the number of known receivers has not changed since the previous invocation of this method.
        Returns:
        true if this iteration has converged.
        Throws:
        IllegalActionException - Not thrown in this base class.

      • _isReadyToFire

        protected boolean _isReadyToFire​(Actor actor)
                          throws IllegalActionException
        Return true if the specified actor is ready to fire. An actor is ready to fire if it has not previously finished firing in this iteration and either it is strict and all inputs are known or it is nonstrict. Note that this ignores whether the actor has previously returned false in postfire().
        Parameters:
        actor - The actor that is checked for being ready to fire.
        Returns:
        true if the actor is ready to fire.
        Throws:
        IllegalActionException - If thrown while determining if actors are finished firing, or while determining if the actor is strict, or while determining if all the inputs are known.

      • _receiverChanged

        protected void _receiverChanged()
        React to the change in receiver status by incrementing the count of known receivers.

      • _resetAllReceivers

        protected void _resetAllReceivers()
        Reset all receivers to unknown status and clear out variables used to track which actors fired in the last iteration.

      • _sendAbsentToAllUnknownOutputsOf

        protected void _sendAbsentToAllUnknownOutputsOf​(Actor actor)
                                         throws IllegalActionException
        Call the send(index, null) method of each output port with unknown status of the specified actor.
        Parameters:
        actor - The actor.
        Throws:
        IllegalActionException - If thrown while getting the width of a port, determining if a port is known or while sending data.

      • _synchronizeToRealTime

        protected void _synchronizeToRealTime()
                               throws IllegalActionException
        Synchronize to real time, if appropriate. NOTE: This method is provided for backward compatibility. The preferred method for synchronizing to real time is now to use a SynchronizeToRealTime attribute, which implements the TimeRegulator interface.
        Throws:
        IllegalActionException - If the synchronizeToRealTime parameter is ill formed.