Package ptolemy.domains.pn.kernel

Class TimedPNDirector

  • All Implemented Interfaces:
    java.lang.Cloneable, Executable, Initializable, Changeable, Debuggable, DebugListener, Derivable, ModelErrorHandler, MoMLExportable, Moveable, Nameable
    public class TimedPNDirector
extends PNDirector
    A TimedPNDirector governs the execution of a CompositeActor with Kahn-MacQueen process networks (PN) semantics extended by introduction of a notion of global time.

    The thread that calls the various execution methods (initialize, prefire, fire and postfire) on the director is referred to as the directing thread. This directing thread might be the main thread responsible for the execution of the entire simulation or might be the thread created by the executive director of the containing composite actor.

    In the PN domain, the director creates a thread (an instance of ProcessThread), representing a Kahn process, for each actor in the model. The threads are created in initialize() and started in the prefire() method of the ProcessDirector. A process is considered active from its creation until its termination. An active process can block when trying to read from a channel (read-blocked), when trying to write to a channel (write-blocked), or when waiting for time to progress (time-blocked). Time can progress for an active process in this model of computation only when the process is blocked.

    A deadlock is when all the active processes are blocked. The director is responsible for handling deadlocks during execution. This director handles three different sorts of deadlocks, real deadlock, timed deadlock and artificial deadlock.

    A real deadlock is when all the processes are blocked on a read meaning that no process can proceed until it receives new data. The execution can be terminated, if desired, in such a situation. If the container of this director does not have any input ports (as is in the case of a top-level composite actor), then the executive director or manager terminates the execution. If the container has input ports, then it is up to the executive director of the container to decide on the termination of the execution. To terminate the execution after detection of a real deadlock, the manager or the executive director calls wrapup() on the director.

    An artificial deadlock is when all processes are blocked and at least one process is blocked on a write. In this case the director increases the capacity of the receiver with the smallest capacity amongst all the receivers on which a process is blocked on a write. This breaks the deadlock and the execution can proceed.

    A timed deadlock is when all the processes under the control of this director are blocked, at least one process is blocked on a delay (time-blocked) and no process is blocked on a write. This director supports a notion of global time. All active processes that are not blocked and are executing concurrently are executing at the same global time. A process that wants time to advance, suspends itself by calling the fireAt() method of the director and specifies the time it wants to be awakened at. Time can advance only when a timed deadlock occurs. In such a case, the director advances time to the time when the first timed-blocked process can be awakened.

    Since:
    Ptolemy II 0.2
    Version:
    $Id$
    Author:
    Mudit Goel
    Pt.AcceptedRating:
    Green (davisj)
    Pt.ProposedRating:
    Green (mudit)

    • Field Detail

      • _eventQueue

        protected CalendarQueue _eventQueue
        The priority queue that stores the list of processes waiting for time to advance. These processes are sorted by the time they want to resume at.

      • _delayBlockCount

        protected int _delayBlockCount
        The number of time-blocked processes.

    • Constructor Detail

      • TimedPNDirector

        public TimedPNDirector()
                throws IllegalActionException,
                       NameDuplicationException
        Construct a director in the default workspace with an empty string as its name. The director is added to the list of objects in the workspace. Increment the version number of the workspace. Create a director parameter "initialQueueCapacity" with the default value 1. This sets the initial capacities of the FIFO queues in all the receivers created in the PN domain.
        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 entity with the specified name.

      • TimedPNDirector

        public TimedPNDirector​(Workspace workspace)
                throws IllegalActionException,
                       NameDuplicationException
        Construct a director in the workspace with an empty name. The director is added to the list of objects in the workspace. Increment the version number of the workspace. Create a director parameter "initialQueueCapacity" with the default value 1. This sets the initial capacities of the queues in all the receivers created in the PN domain.
        Parameters:
        workspace - The workspace of this object.
        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 entity with the specified name.

      • TimedPNDirector

        public TimedPNDirector​(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. Create a director parameter "initialQueueCapacity" with the default value 1. This sets the initial capacities of the queues in all the receivers created in the PN domain.
        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 derived classes.
        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 and no topology listeners. The count of active processes is zero. The parameter "initialQueueCapacity" has the same value as the director being cloned.
        Overrides:
        clone in class PNDirector
        Parameters:
        workspace - The workspace for the cloned object.
        Returns:
        The new TimedPNDirector.
        Throws:
        java.lang.CloneNotSupportedException - If one of the attributes cannot be cloned.
        See Also:
        NamedObj.exportMoML(Writer, int, String), NamedObj.setDeferringChangeRequests(boolean)

      • fireAt

        public Time fireAt​(Actor actor,
                   Time newFiringTime,
                   int microstep)
            throws IllegalActionException
        Suspend the calling process until the time has advanced to at least the time specified by the method argument. Add the actor corresponding to the calling process to the priority queue and sort it by the time specified by the method argument. Increment the count of the actors blocked on a delay. Suspend the calling process until the time has advanced to at least the time specified by the method argument. Resume the execution of the calling process and return.
        Overrides:
        fireAt in class Director
        Parameters:
        actor - The actor scheduled to be fired.
        newFiringTime - The scheduled time.
        microstep - The microstep (ignored by this director).
        Returns:
        the value of the newFiringTime argument.
        Throws:
        IllegalActionException - If the operation is not permissible (e.g. the given time is in the past).
        See Also:
        Director.fireAtCurrentTime(Actor), Director.fireContainerAt(Time)

      • _areThreadsDeadlocked

        protected boolean _areThreadsDeadlocked()
        Return true if a deadlock is detected. Return false otherwise. Return true if all the active processes in the container are either read-blocked, write-blocked or delay-blocked.
        Overrides:
        _areThreadsDeadlocked in class CompositeProcessDirector
        Returns:
        true if a deadlock is detected.

      • _informOfDelayBlock

        protected void _informOfDelayBlock()
        Increment by 1 the count of actors waiting for the time to advance. Check for a resultant deadlock or pausing of the execution. If either of them is detected, then notify the directing thread of the same.

      • _informOfDelayUnblock

        protected void _informOfDelayUnblock()
        Decrease by 1 the count of processes blocked on a delay.

      • _resolveDeadlock

        protected boolean _resolveDeadlock()
                            throws IllegalActionException
        Return false on detection of a real deadlock. Otherwise break the deadlock and return true. On detection of a timed deadlock, advance time to the earliest time that a delayed process is waiting for, wake up all the actors waiting for time to advance to the new time, and remove them from the priority queue. This method is synchronized on the director.
        Overrides:
        _resolveDeadlock in class CompositeProcessDirector
        Returns:
        true if a real deadlock is detected, false otherwise.
        Throws:
        IllegalActionException - Not thrown in this base class. This might be thrown by derived classes.