Package ptolemy.domains.ci.kernel

Class CIDirector

  • All Implemented Interfaces:
    java.lang.Cloneable, Executable, Initializable, Changeable, Debuggable, DebugListener, Derivable, ModelErrorHandler, MoMLExportable, Moveable, Nameable
    public class CIDirector
extends Director
    Director of the component interaction (CI) domain. The CI domain supports two styles of interaction between actors, push and pull. In push interaction, the actor that produces data initiates the interaction. The receiving actor reacts to the data. The computation proceeds as data-driven. In pull interaction, the actor that consumes data decides when the interaction takes place, and the computation proceeds as demand-driven.

    When a relation connects the push(pull) output port of one actor with the push(pull) input port of another, the style of interaction between the two actors is push(pull). To configure a port as a push port, add a parameter named push to the port, and give the value "true" to the parameter. Ports are pull ports by default. Relations connecting both push and pull ports are not supported. (TODO: add check in the director.)

    Actors in a CI model are classified as either active or inactive. Each active actor is controlled by an actor manager, which runs asynchronously with respect to the director (i.e. not in the same thread of control). Active actors include:

    • source actors with push output ports
    • sink actors with pull input ports
    • actors with pull input ports and push output ports
    These actors initiate all the computation in a CI model. The director controls the execution of inactive actors by maintaining a task queue. A task in the queue is an inactive actor that either receives a token from an active actor via the push interaction, or is requested to produce a token by an active actor via the pull interaction. In one iteration of the CI model, the director removes the first actor from the queue. If the actor is pushed, the computation proceeds as data-driven from the actor, until the produced data reach actors that are either not ready to fire or with pull output ports and no pending pull request. If the actor is pulled, then the computation proceeds as demand-driven from the actor, until either the actor is fired or the pull request reaches actors that have push input ports and are not ready to fire.
    Since:
    Ptolemy II 3.0
    Version:
    $Id$
    Author:
    Xiaojun Liu, Yang Zhao
    Pt.AcceptedRating:
    Red (liuxj)
    Pt.ProposedRating:
    Yellow (liuxj)

    • Field Detail

      • _pauseRequested

        protected boolean _pauseRequested
        If true, pause the execution of the model.

      • _interval

        protected long _interval
        The default interval between iterations of active actors.

    • Constructor Detail

      • CIDirector

        public CIDirector​(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 - The container.
        name - The name of this director.
        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 attribute with the specified name.

    • 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 Director
        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
        Check whether there is an actor pushed or pulled by an active actor. If there is a pushed actor, proceed with data-driven computation from the actor. For an asynchronously pulled actor, proceed with demand-driven computation from the actor.

        If this director is not at the top level of the model, return after completing the data-driven computation for a pushed actor or propagating the pull request for a pulled actor; otherwise, wait until active actors produce pushed data or pull requests.

        This method is not synchronized on the workspace, so the caller should be.

        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.

      • initialize

        public void initialize()
                throws IllegalActionException
        Initialize the model controlled by this director. For each active actor, create an instance of ActiveActorManager and start it.

        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.

      • newReceiver

        public Receiver newReceiver()
        Return a new receiver of type CIReceiver.
        Overrides:
        newReceiver in class Director
        Returns:
        A new CIReceiver.

      • postfire

        public boolean postfire()
                 throws IllegalActionException
        Return false if all active actors have finished execution and there is no pushed data or pull request to be processed; otherwise, return true.
        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.

      • preinitialize

        public void preinitialize()
                   throws IllegalActionException
        Validate the attributes and then invoke the preinitialize() methods of all its deeply contained actors. This method is invoked once per execution, before any iteration, and before the initialize() method. Time is not set during this stage. So preinitialize() method of actors should not make use of time. They should wait until the initialize phase of the execution.

        This method is not synchronized on the workspace, so the caller should be.

        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.

      • stop

        public void stop()
        Request that the director cease execution altogether. This causes a call to stop() on all actors contained by the container of this director, and sets a flag so that the next call to postfire() returns false.
        Specified by:
        stop in interface Executable
        Overrides:
        stop in class Director

      • stopFire

        public void stopFire()
        Request that execution of the current iteration stop. Pass the request to all actors that are deeply contained by the container of this director. Notify the threads that manage active actors to stop.
        Specified by:
        stopFire in interface Executable
        Overrides:
        stopFire in class Director

      • terminate

        public void terminate()
        Terminate any currently executing model with extreme prejudice. This method is not intended to be used as a normal route of stopping execution. To normally stop execution, call the finish() method instead. This method should be called only when execution fails to terminate by normal means due to certain kinds of programming errors (infinite loops, threading errors, etc.). There is no assurance that the topology will be in a consistent state after this method returns. The topology should probably be recreated before attempting any further operations.

        Calls terminate() on all actors contained by the container of this director. Set the _stopRequested flag to be true, and interrupt the actor manager threads.

        Specified by:
        terminate in interface Executable
        Overrides:
        terminate in class Director

      • wrapup

        public void wrapup()
            throws IllegalActionException
        Invoke the wrapup() method of all the actors contained in the director's container. Notify and wait for the threads that manage active actors to stop. This method is not synchronized on the workspace, so the caller should be.
        Specified by:
        wrapup in interface Initializable
        Overrides:
        wrapup in class Director
        Throws:
        IllegalActionException - If the wrapup() method of one of the associated actors throws it.

      • _actorEnabled

        protected void _actorEnabled​(Actor actor)
        Schedule the pulled inactive actor to fire.
        Parameters:
        actor - The pulled actor that is ready to fire.

      • _addActorManager

        protected void _addActorManager​(ActiveActorManager actorManager)
        Add the actor manager to the set of active actor managers.
        Parameters:
        actorManager - An active actor manager.

      • _addAsyncPushedActor

        protected void _addAsyncPushedActor​(Actor actor)
        Add the given actor to the list of actors that received pushed data from active actors. Notify this director.
        Parameters:
        actor - The actor that received pushed data from an active actor.

      • _addSyncPushedActor

        protected void _addSyncPushedActor​(Actor actor)
        Add the given actor to the list of synchronously pushed actors. This is done when the actor receives pushed data from an actor executing in the director's thread.
        Parameters:
        actor - The actor that received synchronously pushed data.

      • _isActive

        protected static boolean _isActive​(Actor actor)
                            throws IllegalActionException
        Return true if the actor is active, such as: source with push output; sink with pull input; actor with pull input and push output.
        Parameters:
        actor - The actor to be tested whether it is active.
        Returns:
        True if the actor is active.
        Throws:
        IllegalActionException

      • _isPulled

        protected boolean _isPulled​(Actor actor)
        Return true if the given actor has a pending pull request.
        Parameters:
        actor - The actor to test.
        Returns:
        True if the given actor has been pulled.

      • _isPushPort

        protected static boolean _isPushPort​(IOPort port)
        Return true if the port is a push port, that is a port having a parameter named push with boolean value true. Otherwise the port is considered a pull port.
        Parameters:
        port - The port to test.
        Returns:
        True if the port is a push port.

      • _isStopRequested

        protected boolean _isStopRequested()
        Return true if this director is requested to stop.
        Returns:
        True if this director is requested to stop.

      • _removeActorManager

        protected void _removeActorManager​(ActiveActorManager actorManager)
        Remove the actor manager from the set of active actor managers.
        Parameters:
        actorManager - An active actor manager.

      • _requestAsyncPull

        protected void _requestAsyncPull​(Actor actor)
        Handle the pull request from the given active actor. Add actors providing data to the given actor to the asynchronously pulled actor list. Wake up the director thread if it is waiting.
        Parameters:
        actor - The active actor with pull request.

      • _requestSyncPull

        protected void _requestSyncPull​(Actor actor)
                         throws IllegalActionException
        Record the given actor as being pulled, and recursively propagate the pull request to those actors providing data to it.
        Parameters:
        actor - The actor being pulled.
        Throws:
        IllegalActionException - If calling prefire() on an actor in that provides data to the actor being pulled throws it