Package ptolemy.domains.csp.kernel

Class CSPDirector

  • All Implemented Interfaces:
    java.lang.Cloneable, Executable, Initializable, Changeable, Debuggable, DebugListener, Derivable, ModelErrorHandler, MoMLExportable, Moveable, Nameable
    public class CSPDirector
extends CompositeProcessDirector
    CSPDirector governs the execution of a composite actor with the semantics of the Communicating Sequential Processes (CSP) domain.

    In the CSP domain, the director creates a thread for executing each actor under its control. Each actor corresponds to a process in the model. The threads are created in the initialize method and started in the prefire method. After the thread for an actor is started it is active until the thread finishes. While the process is active, it can also be blocked or delayed, but not both. A process is blocked if it is trying to communicate but the process with which it is trying to communicate is not ready to do so yet. A process is delayed if it is waiting for time to advance, or if it is waiting for a deadlock to occur.

    The director is responsible for handling deadlocks, both real and timed. It is also responsible for carrying out any requests for changes to the topology that have been made when a deadlock occurs. It maintains counts of the number of active processes, the number of blocked processes, and the number of delayed processes. Deadlock occurs when the number of blocked processes plus the number of delayed processes equals the number of active processes. Time deadlock occurs if at least one of the active processes is delayed. Real deadlock occurs if all of the active processes under the control of this director are blocked trying to communicate. The fire method controls and responds to deadlocks and carries out changes to the topology when it is appropriate.

    If real deadlock occurs, the fire method returns. If there are no levels above this level in the hierarchy then this marks the end of execution of the model. The model execution is terminated by setting a flag in every receiver contained in actors controlled by this director. When a process tries to send or receive from a receiver with the terminated flag set, a TerminateProcessException is thrown which causes the actors execution thread to terminate.

    Time is controlled by the director. Each process can delay for some delta time, and it will continue when the director has advanced time by that length of time from the current time. A process is delayed by calling delay(double) method. The director advances time each occasion a time deadlock occurs and no changes to the topology are pending. If a process specifies zero delay, then the process continues immediately. A process may delay itself until the next time deadlock occurs by calling waitForDeadlock(). Then the next occasion time deadlock occurs, the director wakes up any processes waiting for deadlock, and does not advance the current time. Otherwise the current model time is increased as well as being advanced. By default the model of computation used in the CSP domain is timed. To use CSP without a notion of time, do not use the delay(double) method in any process.

    Changes to the topology can occur when deadlock, real or timed, is reached. The director carries out any changes that have been queued with it. Note that the result of the topology changes may remove the deadlock that caused the changes to be carried out.

    Since:
    Ptolemy II 0.2
    Version:
    $Id$
    Author:
    Neil Smyth, Mudit Goel, John S. Davis II
    See Also:
    Director
    Pt.AcceptedRating:
    Green (kienhuis)
    Pt.ProposedRating:
    Green (nsmyth)

    • Constructor Detail

      • CSPDirector

        public CSPDirector​(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 - Container of the director.
        name - Name of this director.
        Throws:
        IllegalActionException - 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 (you must do this yourself if you want it there). The result is a new director with no container, no pending changes to the topology, current time is 0.0, and no actors are delayed or blocked.

        Overrides:
        clone in class CompositeProcessDirector
        Parameters:
        workspace - The workspace for the cloned object.
        Returns:
        The new CSPDirector.
        Throws:
        java.lang.CloneNotSupportedException - If one of the attributes cannot be cloned.
        See Also:
        NamedObj.exportMoML(Writer, int, String), NamedObj.setDeferringChangeRequests(boolean)

      • newReceiver

        public Receiver newReceiver()
        Return a new CSPReceiver compatible with this director. In the CSP domain, we use CSPReceivers.
        Overrides:
        newReceiver in class CompositeProcessDirector
        Returns:
        A new CSPReceiver.

      • suggestedModalModelDirectors

        public java.lang.String[] suggestedModalModelDirectors()
        Return an array of suggested directors to be used with ModalModel. This is the FSMDirector followed by the NonStrictFSMDirector.
        Overrides:
        suggestedModalModelDirectors in class Director
        Returns:
        An array of suggested directors to be used with ModalModel.
        See Also:
        Director.suggestedModalModelDirectors()

      • _actorDelayed

        protected void _actorDelayed​(double delta,
                             CSPActor actor)
                      throws InvalidStateException
        Called by a CSPActor when it wants to delay. When the director has advanced time to "getCurrentTime() + delta", the process corresponding to the actor will continue. Note that actors can only deal with delta time.

        The method waitForDeadlock() in CSPActor calls this method with a zero argument. Thus the process will continue the next occasion time deadlock occurs.

        Parameters:
        delta - The length of time to delay the actor.
        actor - The actor being delayed.
        Throws:
        InvalidStateException - If an actor is delayed for negative time.

      • _areThreadsDeadlocked

        protected boolean _areThreadsDeadlocked()
        Returns true if all active processes are either blocked or delayed, false otherwise.
        Overrides:
        _areThreadsDeadlocked in class CompositeProcessDirector
        Returns:
        false If the number of blocked processes is less than the number of active actors; return true otherwise.

      • _areAllThreadsStopped

        protected boolean _areAllThreadsStopped()
        Return true if the count of active processes equals the number of stopped, blocked, and delayed threads. Otherwise return false.
        Overrides:
        _areAllThreadsStopped in class ProcessDirector
        Returns:
        True if all threads are stopped.

      • _receiverStatus

        protected static java.lang.String _receiverStatus​(Receiver receiver)
        Return a string describing the status of the specified receiver.
        Parameters:
        receiver - The receiver to describe.
        Returns:
        A string describing the status of the specified receiver.

      • _resolveInternalDeadlock

        protected boolean _resolveInternalDeadlock()
                                    throws IllegalActionException
        Respond to a deadlock. This is where nearly all the control for the model at this level in the hierarchy is located.

        Deadlock occurs if the number of blocked and delayed processes equals the number of active processes. The method looks for three cases in the following order: are there topology changes waiting to happen, are there any processes delayed, are all the processes blocked trying to rendezvous.

        If there are changes to the topology waiting to happen, they are performed and the execution of the model continues. Note that the result of performing the topology changes may be to remove the deadlock that had occurred.

        If the number of delayed processes is greater than zero, then time deadlock has occurred. If one or more processes are delayed waiting for deadlock to occur, then those processes are resumed and time is not advanced. Otherwise time is advanced and the earliest delayed process is resumed.

        If all the processes are blocked, then real deadlock has occurred, and this method returns false. If there are no levels above this one in the hierarchy, then real deadlock marks the end of executing the model.

        Overrides:
        _resolveInternalDeadlock in class CompositeProcessDirector
        Returns:
        False if real deadlock occurred, true otherwise.
        Throws:
        IllegalActionException - If setting the model time, or getting a parameter throws it.