Package ptolemy.domains.metroII.kernel

Class MetroIIDirector

  • All Implemented Interfaces:
    java.lang.Cloneable, Executable, Initializable, Changeable, Debuggable, DebugListener, Derivable, ModelErrorHandler, MoMLExportable, Moveable, Nameable
    public class MetroIIDirector
extends Director

    A MetroII Director governs the execution of actors with simplified MetroII execution semantics. The major distinction from other directors is the way MetroIIDirector fires the actors. In stead of explicitly calling fire() of the governing actors, MetroIIDirector implicitly fires actors by exchanging MetroII events with actors (@see ptolemy.domains.metroII.kernel.util.ProtoBuf.Event). Under MetroIIDirector, each actor is wrapped by either BlockingFire (@see BlockingFire) or ResumableFire (@see ResumableFire). With a wrapper, the firing of an actor is a process which executes and then blocks to generate MetroII events. Each MetroII event has one of the following states: PROPOSED, WAITING, and NOTIFIED. When the firing of an actor blocks to generate MetroII events, the events are sent to MetroIIDirector with the state of PROPOSED. This is also referred to as proposing MetroII events. MetroIIDirector delegates the events to constraint solvers (@see ConstraintSolver) which update the event states to either WAITING or NOTIFIED. If any event state of a process is updated to NOTIFIED, the process is supposed to resume execution. The resumed execution may depend on the updated events.

    The execution of MetroIIDirector has two phases. In Phase 1, MetroIIDirector repeatedly fires each actor (no particular order should be presumed). As mentioned, each firing is a process runs and then blocks to propose MetroII events. Phase 1 ends when all processes of firing are blocked. In Phase 2, MetroIIDirector delegates all the proposed events to constraint solvers (@see ConstraintSolver), which updates the states of MetroII events based on the constraints. In particular, MappingConstraintSolver (MappingConstraintSolver) is a constraint solver that resolves rendezvous constraints. A rendezvous constraint requires the specified pair of MetroII events must be proposed together, otherwise the states will be updated to WAITING. A collection of two completed phases is referred to as an iteration. After constraint resolving in Phase 2, MetroIIDirector goes back to Phase 1, in which each existing process has a chance to react to the updated MetroII events. The process with at least one NOTIFIED event is supposed to resume execution while the process with all events WAITING keeps blocked. If the process of firing successfully completes in last iteration, a new process will be created as long as prefire() returns true. The actor with postfire() returns false will not be fired any more.

    An actor that implements GetFirable interface (@see GetFirable) is wrapped by ResumableFire (@see ResumableFire). Otherwise it's wrapped by BlockingFire (@see BlockingFire). Particularly, the MetroIIComposite, MetroIIModalModel, MetroIIPtidesPlatform have GetFirable interface implemented and are thus wrapped by ResumableFire. And all other ordinary Ptolemy actors are wrapped by BlockingFire. If an actor is wrapped by BlockingFire, the firing of an actor has two MetroII events associated: FIRE_BEGIN and FIRE_END. FIRE_BEGIN is first proposed and the firing blocks. When FIRE_BEGIN is NOTIFIED, fire() is called and FIRE_END is proposed. When FIRE_END is NOTIFIED, the firing successfully completes. The firing is atomic and there is no chance to propose events during firing. If an actor is wrapped by ResumableFire, in addition to FIRE_BEGIN and FIRE_END, getfire(MetroII event list) is called instead of fire(). The process of firing may not only block on FIRE_BEGIN and FIRE_END, but also block on the internal events of getfire(MetroII event list).

    In ResumableFire, the 'start', 'block', and 'resume' are realized using YieldAdapter, see http://jimblackler .net/blog/?p=61. The underlying mechanism is to create, suspend, and resume a java thread. And proposed MetroII events are returned by the parameters of startOrResume().

    Since:
    Ptolemy II 11.0
    Version:
    $Id$
    Author:
    Liangpeng Guo
    Pt.AcceptedRating:
    Red (glp)
    Pt.ProposedRating:
    Red (glp)

    • Field Detail

      • mappingFileName

        public FileParameter mappingFileName
        A mapping constraint is a pair of events that are rendezvous. Mapping file is a text file that specifies such constraints. In mapping file, each line is a mapping constraint, which contains two event names separated by a space.

        _mappingFileName is a string that contains the absolute path of the mapping file.

        The default value of _mappingFileName is null, which means no mapping constraint is specified.

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

      • printTrace

        public Parameter printTrace
        Option parameter whether trace info is printed out.

      • printDebug

        public Parameter printDebug
        Option parameter whether debug info is printed out.

      • _iterationCount

        protected int _iterationCount
        The iteration count.

    • Constructor Detail

      • MetroIIDirector

        public MetroIIDirector​(CompositeEntity container,
                       java.lang.String name)
                throws NameDuplicationException,
                       IllegalActionException
        Constructs 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. 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
        Reacts 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.

      • initialize

        public void initialize()
                throws IllegalActionException
        Initializes the model controlled by this director. Call the initialize() of super class and then wrap each actor that is controlled by this director. This method should typically be invoked once per execution, after the preinitialization phase, but before any iteration. It may be invoked in the middle of an execution, if reinitialization is desired. This method is not synchronized on the workspace, so the caller should be.
        Specified by:
        initialize in interface Initializable
        Overrides:
        initialize in class Director
        Throws:
        IllegalActionException - If the initialize() method of one of the associated actors throws it.

      • fire

        public void fire()
          throws IllegalActionException
        Each iteration has two phases. In Phase 1, MetroIIDirector calls each actor (no particular order should be presumed. See Note 1). Each actor runs until it wants to propose MetroII events: the actor saves the state and returns with MetroII events. In Phase 2, MetroIIDirector calls the MappingConstraintSolver, which updates the MetroII events based on the mapping constraints.
        Specified by:
        fire in interface Executable
        Overrides:
        fire in class Director
        Throws:
        IllegalActionException - If any called method of one of the associated actors throws it.

      • clone

        public java.lang.Object clone​(Workspace workspace)
                       throws java.lang.CloneNotSupportedException
        Clones 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 Director
        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)

      • postfire

        public boolean postfire()
                 throws IllegalActionException
        The postfire() counts the number of iterations and returns false when the number of iteration exceeds the parameter iterations or the time in TimeScheduler exceeds stopTime, whichever comes first. postfire() will always return true if the parameter iterations is less or equal to 0.
        Specified by:
        postfire in interface Executable
        Overrides:
        postfire in class Director
        Returns:
        True to continue execution, and false otherwise.
        Throws:
        IllegalActionException - Not thrown in this base class.

      • stop

        public void stop()
        Stops firing as soon as possible.
        Specified by:
        stop in interface Executable
        Overrides:
        stop in class Director

      • stopFire

        public void stopFire()
        Calls stopFire() of the superclass and show a message.
        Specified by:
        stopFire in interface Executable
        Overrides:
        stopFire in class Director