Package ptolemy.domains.metroII.kernel

Class MetroIIDEDirector

  • All Implemented Interfaces:
    java.lang.Cloneable, Executable, Initializable, SuperdenseTimeDirector, GetFirable, Changeable, Debuggable, DebugListener, Derivable, ModelErrorHandler, MoMLExportable, Moveable, Nameable
    public class MetroIIDEDirector
extends DEDirector
implements GetFirable
    MetroIIDEDirector is a Discrete Event (DE) director that adapts to MetroII semantics. This MoC is mainly used to design the functional model, in which some actors can be mapped to an architectural models. This allows users to explore choices about how the model can be implemented.

    In DE director, events are totally ordered and executed. In MetroIIDEDirector, these events are called Ptolemy events that are still totally ordered. But the execution of Ptolemy events has some variances. Typically, a Ptolemy event is associated with a fire() action of an actor. Executing the Ptolemy event triggers the firing of the actor. In MetroIIDEDirector, the firing has two variances, depending on the types of the actor:

    1. If the actor is a normal Ptolemy actor, the execution of the event instantly triggers fire() of the actor.
    2. If the actor is an actor with a MetroII wrapper (@see BlockingFire or @see ResumableFire), the execution of the event will trigger a MetroII event to be PROPOSED. The firing will not be executed until the MetroII event is NOTIFIED.

    A MetroII actor is a Ptolemy actor that implements GetFirable interface, which includes MetroIICompositeActor. To understand MetroII event and its states (e.g. PROPOSED, WAITING, NOTIFIED), please @see MetroIIDirector.

    By using a MetroII actor under the MetroIIDEDirector, the user understands the firing of the MetroII actor might be delayed because the scheduling is not solely determined by the MetroIIDEDirector but also determined by MetroIIDirector on the upper level and the architectural model which the MetroII actor is mapped onto. This introduces some non-determinisms. But these non-determinisms are desirable and can be used to optimize the architectures.

    It is highly recommend not to place MetroIIDEDirector in a MetroIICompositeActor under another MetroIIDEDirector because there would be a semantic conflict if the enclosed MetroIIDEDirector directs a normal Ptolemy actor.

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

    • Field Detail

      • printTrace

        public Parameter printTrace
        True if the trace information is printed.

    • Constructor Detail

      • MetroIIDEDirector

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

      • 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 DEDirector
        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)

      • initialize

        public void initialize()
                throws IllegalActionException
        Initialize 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 DEDirector
        Throws:
        IllegalActionException - If the initialize() method of one of the associated actors throws it.

      • stop

        public void stop()
        Request the execution of the current iteration to stop. This is similar to stopFire(), except that the current iteration is not allowed to complete.
        Specified by:
        stop in interface Executable
        Overrides:
        stop in class DEDirector

      • _checkNextActorToFire

        protected Pair<Actor,​java.lang.Integer> _checkNextActorToFire()
                                                             throws IllegalActionException
        Return the actor that is about to fire and its state.
        Returns:
        0 if firing can be executed, and the next event in event queue should be checked for processing; -1 if there's no actor to fire, and we should not keep firing; 1 if there's no actor to fire, but the next event should be checked for processing.
        Throws:
        IllegalActionException - If the firing actor throws it, or event queue is not ready, or an event is missed, or time is set backwards.

      • _checkForNextEvent

        protected boolean _checkForNextEvent()
                              throws IllegalActionException
        Enforce a firing of a DE director only handles events with the same tag. Checks what is the model time of the earliest event in the event queue.
        Overrides:
        _checkForNextEvent in class DEDirector
        Returns:
        true if the earliest event in the event queue is at the same model time as the event that was just processed. Else if that event's timestamp is in the future, return false.
        Throws:
        IllegalActionException - If model time is set backwards.

      • getfire

        public void getfire​(net.jimblackler.Utils.ResultHandler<java.lang.Iterable<metroIIcomm.Event.Builder>> resultHandler)
             throws net.jimblackler.Utils.CollectionAbortedException,
                    IllegalActionException
        Fire actors according to events in the event queue. Whether the actual firing of an actor can be done also depend on the MetroII events associated with the actor if the actor is a MetroII actor. Only when the associated MetroII event is NOTIFIED, the firing can be executed. Otherwise the state of the MetroII event will be checked again along with 'the next event'. Note that 'the next event' is the next event globally, which could be either the next event in the event queue of MetroIIDEDirector or the event in architectural model which this model is mapped to.

        The time advancing is via proposing a MetroII event with time tag as its quantity, see TimeScheduler.

        Specified by:
        getfire in interface GetFirable
        Parameters:
        resultHandler - iterable of events 'yield returned'.
        Throws:
        IllegalActionException - If we couldn't process an event or if an event of smaller timestamp is found within the event queue.
        net.jimblackler.Utils.CollectionAbortedException

      • adapter

        public net.jimblackler.Utils.YieldAdapterIterable<java.lang.Iterable<metroIIcomm.Event.Builder>> adapter()
        Since the MetroIIDEDirector is always used inside a MetroIICompositeActor, the adapter() in MetroIICompositeActor is responsible for creating the iterator of getfire(), this adapter() should never be called.
        Specified by:
        adapter in interface GetFirable
        Returns:
        An iterator, in this case null. However, in this base class, an assertion will be thrown.