Package ptolemy.actor.process

Class CompositeProcessDirector

  • All Implemented Interfaces:
    java.lang.Cloneable, Executable, Initializable, Changeable, Debuggable, DebugListener, Derivable, ModelErrorHandler, MoMLExportable, Moveable, Nameable
    Direct Known Subclasses:
    CSPDirector, DDEDirector, PNDirector, RendezvousDirector
    public class CompositeProcessDirector
extends ProcessDirector
    A baseclass for directors in process oriented domains that incorporate hierarchical heterogeneity. As with ProcessDirector CompositeProcessDirectors need to keep a count of the number of active processes and the number of processes that are blocked for any reason (e.g., trying to read from an empty channel in PN). CompositeProcessDirector is a subclass of ProcessDirector to facilitate models that consist of non-atomic actors.

    A composite process director can be contained by an opaque composite actor that is contained by a composite actor. Ports contained by opaque composite actors are called opaque ports and such ports facilitate data transfer across the composite actor boundaries. A composite process director allocates two branch controllers to monitor data transfer in channels associated with opaque ports. The input branch controller monitors data transfer for channels associated with input opaque ports. The output branch controller monitors data transfer for channels associated with output opaque ports.

    Associated with the channels of each opaque port is a pair of process receivers. The producer receiver serves as the channel source and the consumer receiver serves as the channel destination. Each branch controller allocates a branch for each process receiver pair and when executing, a branch repeatedly attempts to transfer a single token from its producer receiver to its consumer receiver.

    When a branch blocks while attempting to transfer data, it informs its branch controller by passing the branch controller the blocked receiver. If all of the branches of a controller have blocked, then we say that the branch controller is blocked and the branch controller informs the composite process director. In addition to monitoring the status of its branch controllers, a composite process director keeps track of the state of the actors that it contains. Actors can be internally or externally blocked. We say that an actor is externally blocked if it is blocked waiting to transfer tokens to or from a boundary port of its container actor. Actors that are blocked but not externally are said to be internally blocked.

    Composite process directors monitor the state of the branch controllers and contained actors and when necessary invoke the _resolveDeadlock() method to deal with deadlocks. In the remainder of this paragraph we consider the case of a process-oriented opaque composite actor that is contained by another process-oriented opaque composite actor. If the actors contained by the inner composite actor are not blocked, then execution of the inner composite actor is allowed to continue independent of the state of the branch controllers. If the actors contained by the inner composite actor are internally blocked, then after the branch controllers have been deactivated, execution of the composite actor ends and postfire returns false indicating that successive iterations are not allowed. If the actors contained by the inner composite actor are externally blocked, then the composite process director waits until the branch controllers block (an inevitable condition) and registers the block with the containing (outer) composite director of the actor.

    In this paragraph we consider the case of a process-oriented opaque composite actor that is contained by a schedule-oriented (non process) opaque composite actor. If the actors contained by the inner composite actor are not blocked, then execution of the inner composite actor is allowed to continue independent of the state of the branch controllers. If the actors contained by the inner composite actor are internally blocked, then after the branch controllers have been deactivated, execution of the composite actor ends and postfire returns false indicating that successive iterations are not allowed. If the actors contained by the inner composite actor are externally blocked, then the composite process director waits until the branch controllers block (an inevitable condition) and ends the iteration with postfire() returning true indicating that successive iterations are allowed.

    Since:
    Ptolemy II 1.0
    Version:
    $Id$
    Author:
    John S. Davis II
    See Also:
    Director
    Pt.AcceptedRating:
    Yellow (davisj)
    Pt.ProposedRating:
    Green (mudit)

    • Constructor Detail

      • CompositeProcessDirector

        public CompositeProcessDirector​(CompositeEntity container,
                                java.lang.String name)
                         throws IllegalActionException,
                                NameDuplicationException
        Construct a director in the given container with the given name. If 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 - Name of this director.
        Throws:
        IllegalActionException - If the name contains a period, or if the director is not compatible with the specified container.
        NameDuplicationException - If the container 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 director into the specified workspace. The new object is not added to the directory of that workspace (It must be added by the user if he wants it to be there). The result is a new director with no container, no pending mutations, and no topology listeners. The count of active processes is zero.
        Overrides:
        clone in class ProcessDirector
        Parameters:
        workspace - The workspace for the cloned object.
        Returns:
        The new ProcessDirector.
        Throws:
        java.lang.CloneNotSupportedException - If one of the attributes cannot be cloned.
        See Also:
        NamedObj.exportMoML(Writer, int, String), NamedObj.setDeferringChangeRequests(boolean)

      • createBranchController

        public void createBranchController​(java.util.Iterator ports)
                            throws IllegalActionException
        Create a input and/or output branch controllers according to whether the ports passed in as arguments are input or output ports. If any of the ports are input (output) ports, then they will be added to the input (output) branch controller.
        Parameters:
        ports - The ports for which branches will be assigned.
        Throws:
        IllegalActionException - If any of the ports are not opaque.

      • getInputController

        public BranchController getInputController()
        Return the input branch controller of this director. If this method is called prior to the invocation of initialize(), then this method will return null.
        Returns:
        The input branch controller of this director.

      • getOutputController

        public BranchController getOutputController()
        Return the output branch controller of this director. If this method is called prior to the invocation of initialize(), then this method will return null.
        Returns:
        The output branch controller of this director.

      • initialize

        public void initialize()
                throws IllegalActionException
        Invoke the initialize() methods of all the deeply contained actors in the container (a composite actor) of this director. These are expected to call initialize(Actor), which will result in the creation of a new thread for each actor. Also, set current time to 0.0, or to the current time of the executive director of the container, if there is one.
        Specified by:
        initialize in interface Initializable
        Overrides:
        initialize in class Director
        Throws:
        IllegalActionException - If the initialize() method of one of the deeply contained actors throws it.

      • newReceiver

        public Receiver newReceiver()
        Return a new receiver of a type compatible with this director. In this base class, this returns an instance of MailboxBoundaryReceiver.
        Overrides:
        newReceiver in class Director
        Returns:
        A new MailboxBoundaryReceiver.

      • stopInputBranchController

        public void stopInputBranchController()
        Stop the input branch controller of this director. This method will block until the input branch controller has stopped due to all of the branches it controls stopping, or until the calling thread is interrupted.

      • stopOutputBranchController

        public void stopOutputBranchController()
        Stop the output branch controller of this director. This method will block until the output branch controller has stopped due to all of the branches it controls stopping.

      • threadBlocked

        public void threadBlocked​(java.lang.Thread thread,
                          ProcessReceiver receiver)
        Notify the director that the specified thread is blocked on an I/O operation. If the thread has not been registered with addThread(), then this call is ignored. This overrides the base class to keep track of the receiver in case it is on the boundary of the containing composite actor.
        Overrides:
        threadBlocked in class ProcessDirector
        Parameters:
        thread - The thread.
        receiver - The receiver handling the I/O operation, or null if it is not a specific receiver.
        See Also:
        ProcessDirector.addThread(Thread)

      • threadUnblocked

        public void threadUnblocked​(java.lang.Thread thread,
                            ProcessReceiver receiver)
        Notify the director that the specified thread is unblocked on an I/O operation. If the thread has not been registered with threadBlocked(), then this call is ignored. This overrides the base class to keep track of the receiver in case it is on the boundary of the containing composite actor.
        Overrides:
        threadUnblocked in class ProcessDirector
        Parameters:
        thread - The thread.
        receiver - The receiver handling the I/O operation, or null if it is not a specific receiver.
        See Also:
        *

      • wrapup

        public void wrapup()
            throws IllegalActionException
        End the execution of the model under the control of this director. A flag is set in all of the receivers that causes each process to terminate at the earliest communication point.

        Prior to setting receiver flags, this method wakes up the threads if they all are stopped.

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

        Specified by:
        wrapup in interface Initializable
        Overrides:
        wrapup in class ProcessDirector
        Throws:
        IllegalActionException - If an error occurs while accessing the receivers of all actors under the control of this director.

      • _areActorsExternallyBlocked

        protected boolean _areActorsExternallyBlocked()
                                       throws InvalidStateException,
                                              IllegalActionException
        Return true if one or more contained actor is externally blocked; return false otherwise. We say an actor is externally blocked if it is blocked attempting data transfer through a boundary port of its containing actor. Note that a true return value for this method does not imply that the contained actors are deadlocked.
        Returns:
        true If one or more contained actors are externally blocked; return false otherwise.
        Throws:
        IllegalActionException
        InvalidStateException

      • _areThreadsDeadlocked

        protected boolean _areThreadsDeadlocked()
        Return false if the number of blocked processes is less than the number of active actors; return true otherwise. Note that if the number of active actors is 0 then this method will return true. Derived classes may override this method to add domain specific functionality. Implementations of this method must be synchronized.
        Overrides:
        _areThreadsDeadlocked in class ProcessDirector
        Returns:
        false If the number of blocked processes is less than the number of active actors; return true otherwise.

      • _controllerBlocked

        protected void _controllerBlocked​(BranchController controller)
        Register that the specified controller is blocked. Pass the specified controller in as an argument. Note that if the controller passed in as an argument is not contained by this director or if the state of the controller is not blocked then no registration operation will be performed by this method.
        Parameters:
        controller - The controller for which registration of a blocked state will occur.

      • _controllerUnBlocked

        protected void _controllerUnBlocked​(BranchController controller)
        Unregister the specified controller as being no longer blocked. Pass the specified controller in as an argument. Note that if the controller passed in as an argument is not contained by this director or if the state of the controller is blocked then no registration operation will be performed by this method.
        Parameters:
        controller - The controller for which registration of an unblocked state will occur.

      • _isInputControllerBlocked

        protected boolean _isInputControllerBlocked()
        Return true if the input controller of this director is blocked; return false otherwise.
        Returns:
        true If the input controller of this director is blocked; return false otherwise.

      • _isOutputControllerBlocked

        protected boolean _isOutputControllerBlocked()
        Return true if the output controller of this director is blocked; return false otherwise.
        Returns:
        true If the output controller of this director is blocked; return false otherwise.

      • _resolveDeadlock

        protected boolean _resolveDeadlock()
                            throws IllegalActionException
        Attempt to resolve a deadlock and return true if the deadlock no longer exists and successive iterations are allowed; if the deadlock still exists then return false indicating that future iterations are not allowed. If the deadlock is internal then apply a domain specific algorithm to attempt deadlock resolution via the _resolveInternalDeadlock() method. If the algorithm is successful and deadlock no longer exists then return true. If the algorithm is unsuccessful and deadlock persists then end the iteration and return false.

        If the deadlock is an external deadlock and the containing model of computation is process-oriented, then register the externally blocked receivers with the composite actor that contains this director's composite actor. If the deadlock is an external deadlock and the containing model of computation is schedule-oriented, then end this iteration and return true.

        While in special cases it my be useful to override this method for domain specific functionality it is more likely that this method will remain the same and the _resolveInternalDeadlock() method will be overridden for particular models of computation.

        Overrides:
        _resolveDeadlock in class ProcessDirector
        Returns:
        false If deadlock could not be resolved and successive iterations are not allowed; return true otherwise.
        Throws:
        IllegalActionException - Not thrown in this base class.

      • _resolveInternalDeadlock

        protected boolean _resolveInternalDeadlock()
                                    throws IllegalActionException
        Return false indicating that resolution of an internal deadlock was unsuccessful and execution should discontinue. Subclasses may override this method for domain specific functionality. Domain specific functionality should include algorithms to resolve internal deadlock. Successful application of the algorithm should result in a return value of true; unsuccessful application should result in a return value of false.
        Returns:
        False indicating that internal deadlock was not resolved.
        Throws:
        IllegalActionException - Not thrown in this base class.