Package ptolemy.domains.dde.kernel

Class DDEDirector

  • All Implemented Interfaces:
    java.lang.Cloneable, Executable, Initializable, Changeable, Debuggable, DebugListener, Derivable, ModelErrorHandler, MoMLExportable, Moveable, Nameable
    public class DDEDirector
extends CompositeProcessDirector
    A DDEDirector governs the execution of actors operating according to the DDE model of computation (MoC). The DDE MoC incorporates a distributed notion of time into a dataflow style communication semantic. Blocking reads occur if attempts to consume data are made when the corresponding receiver is empty and blocking writes occur if attempts to produce data are made when the corresponding receiver is full.

    In conjunction with the blocking read/write facilities, the DDE domain uses a distributed, local notion of time. In a network of actors governed by a DDEDirector each actor has a local notion of time. Several features of the DDEDirector are intended to facilitate these local notions of time.

    All DDE models have a completion time. The completion time is a preset time after which all execution ceases. The completion time for a DDEDirector is specified via the stopTime parameter. The value of the stopTime parameter is passed to the receivers of all actors that the DDEDirector governs via newReceiver() during initialize(). After initialize() has been called, the value of stopTime can not be changed.

    The default value of the stopTime parameter is PrioritizedTimedQueue.ETERNITY. Given this value, a DDE model will continue executing without regard for a completion time.

    Deadlock due to feedback loops is dealt with via NullTokens. When an actor in a DDE model receives a NullToken, it may advance its local time value even though no computation results directly from consumption of the NullToken. For models with feedback topologies, the FeedBackDelay actor should be used in the feedback loop.

    The DDE model of computation assumes that valid time stamps have non-negative values. Three special purpose negative time values are reserved with the following meanings. The value of PrioritizedTimedQueue.INACTIVE is reserved to indicate the termination of a receiver. The value of PrioritizedTimedQueue.ETERNITY is reserved to indicate that a receiver has not begun to participate in a model's execution. The value of PrioritizedTimedQueue.IGNORE is reserved to indicate that the current token at the head of a DDEReceiver should be ignored in favor of the tokens contained in the other receivers of the actor in question. More details of IGNORE can be found in FeedBackDelay.

    NOTE: The current implementation of this director does not include an infrastructure for mutations. Hence, ChangeRequest and other facilities for changing the topology of a model are not included in this director.

    Since:
    Ptolemy II 0.3
    Version:
    $Id$
    Author:
    John S. Davis II, Mudit Goel
    See Also:
    PNDirector, FeedBackDelay, NullToken
    Pt.AcceptedRating:
    Red (cxh)
    Pt.ProposedRating:
    Red (davisj)

    • Field Detail

      • READ_BLOCKED

        public static final boolean READ_BLOCKED
        Indicator that a thread is read blocked.
        See Also:
        Constant Field Values

      • WRITE_BLOCKED

        public static final boolean WRITE_BLOCKED
        Indicator that a thread is write blocked.
        See Also:
        Constant Field Values

    • Constructor Detail

      • DDEDirector

        public DDEDirector​(Workspace workspace)
            throws IllegalActionException,
                   NameDuplicationException
        Construct a director in the workspace with an empty string as a name. The director is added to the list of objects in the workspace. Increment the version number of the workspace.
        Parameters:
        workspace - The workspace of this object.
        Throws:
        IllegalActionException - If the director is not compatible with the specified container.
        NameDuplicationException - If thrown while adding a stopTime parameter.

      • DDEDirector

        public DDEDirector​(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. The given name must be unique with respect to the container. 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 of this 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 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). The result is an object with no container.
        Overrides:
        clone in class CompositeProcessDirector
        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)

      • fireAt

        public Time fireAt​(Actor actor,
                   Time time,
                   int microstep)
            throws IllegalActionException
        Schedule an actor to be fired at the specified time. If the thread that calls this method is an instance of DDEThread, then the specified actor must be contained by this thread. If the thread that calls this method is not an instance of DDEThread, then store the actor and refire time in the initial time table of this director.

        NOTE: The current implementation of this method is such that a more appropriate name might be continueAt() rather than fireAt().

        Overrides:
        fireAt in class Director
        Parameters:
        actor - The actor scheduled to fire.
        time - The scheduled time to fire.
        microstep - The microstep (ignored by this director).
        Returns:
        The time at which the actor passed as an argument will be fired.
        Throws:
        IllegalActionException - If the specified time is in the past or if the thread calling this method is a DDEThread but the specified actor is not contained by the DDEThread.
        See Also:
        Director.fireAtCurrentTime(Actor), Director.fireContainerAt(Time)

      • getCurrentTime

        @Deprecated
public double getCurrentTime()
        Deprecated.
        As of Ptolemy II 4.1, replaced by getModelTime()
        Return the current time of the DDEThread that calls this method on behalf of an actor. If this method is called by other than a DDEThread, then return the current time as specified by the superclass of this method.
        Overrides:
        getCurrentTime in class Director
        Returns:
        The current time of the DDEThread that calls this method.
        See Also:
        Director.setCurrentTime(double)

      • getModelTime

        public Time getModelTime()
        Return the current time of the DDEThread that calls this method on behalf of an actor. If this method is called by other than a DDEThread, then return the current time as specified by the superclass of this method.
        Overrides:
        getModelTime in class Director
        Returns:
        The current time of the DDEThread that calls this method.
        See Also:
        Director.setModelTime(Time)

      • newReceiver

        public Receiver newReceiver()
        Return a new receiver of a type compatible with this director. If the completion time of this director has been explicitly set to a particular value then set the completion time of the receiver to this same value; otherwise set the completion time to PrioritizedTimedQueue.ETERNITY which indicates that the receivers should ignore the completion time.
        Overrides:
        newReceiver in class CompositeProcessDirector
        Returns:
        A new DDEReceiver.

      • postfire

        public boolean postfire()
                 throws IllegalActionException
        Return true if the actors governed by this director can continue execution, and false otherwise. Continuation of execution is dependent upon whether the system is deadlocked in a manner that can not be resolved even if external communication occurs. If stop() has been called, then return false.
        Specified by:
        postfire in interface Executable
        Overrides:
        postfire in class ProcessDirector
        Returns:
        True if execution can continue; false otherwise.
        Throws:
        IllegalActionException - Not thrown in this base class. May be thrown in derived classes.

      • threadBlocked

        public void threadBlocked​(java.lang.Thread thread,
                          ProcessReceiver receiver,
                          boolean readOrWrite)
        Notify the director that the specified thread is blocked on an I/O operation.
        Parameters:
        thread - The thread.
        receiver - The receiver handling the I/O operation, or null if it is not a specific receiver.
        readOrWrite - Either READ_BLOCKED or WRITE_BLOCKED to indicate whether the thread is blocked on read or write.
        See Also:
        CompositeProcessDirector.threadBlocked(Thread, ProcessReceiver)

      • threadUnblocked

        public void threadUnblocked​(java.lang.Thread thread,
                            ProcessReceiver receiver,
                            boolean readOrWrite)
        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.
        Parameters:
        thread - The thread.
        receiver - The receiver handling the I/O operation, or null if it is not a specific receiver.
        readOrWrite - Either READ_BLOCKED or WRITE_BLOCKED to indicate whether the thread is blocked on read or write.
        See Also:
        CompositeProcessDirector.threadUnblocked(Thread, ProcessReceiver)

      • _incrementLowestCapacityPort

        protected void _incrementLowestCapacityPort()
                                     throws IllegalActionException
        Increment the port capacity's according to Tom Parks' algorithm. Select the port with the smallest capacity and double the capacity.
        Throws:
        IllegalActionException - If there is an error while attempting to set the capacity of a DDE receiver.

      • _resolveInternalDeadlock

        protected boolean _resolveInternalDeadlock()
                                    throws IllegalActionException
        Apply an algorithm to resolve an internal deadlock and return true if the algorithm is successful. If the algorithm is unsuccessful then return false. The algorithm applied was created by Thomas Parks for resolving internal deadlocks in which one or more actors are write blocked.
        Overrides:
        _resolveInternalDeadlock in class CompositeProcessDirector
        Returns:
        True if an internal deadlock has been resolved; otherwise return false.
        Throws:
        IllegalActionException - If thrown while incrementing the lowest capacity port.