Package ptolemy.domains.tm.kernel

Class TMDirector

  • All Implemented Interfaces:
    java.lang.Cloneable, Executable, Initializable, Changeable, Debuggable, DebugListener, Derivable, ModelErrorHandler, MoMLExportable, Moveable, Nameable
    public class TMDirector
extends Director
    A director that implements a priority-driven multitasking model of computation. This model of computation is usually seen in real-time operating systems.

    Each actor in this domain is called a task. A task is eligible to execute if there is an event that triggers it. Source actors may trigger themselves by calling fireAt(time, actor) on this director. This call is treated as an interrupt that happens at that particular time. A task can have a priority and an execution time, specified by (adding) priority and executionTime parameters. The priority parameter takes an integer value, and the executionTime parameter takes a double value. These parameters may also be specified on a per input port basis, if the actor reacts differently to input events at different ports. If these parameters are not specified, then the default priority value is the java.Thread.NORM on the JVM, and the default execution time is 0.

    This domain assumes there is a single resource, say CPU, shared by the execution of all actors. At one particular time, only one of the tasks can get the resource and execute. If the execution is preemptable (by setting the preemptive parameter of this director to true), then the execution of one task may be preempted by another eligible task with a higher priority. Otherwise, the higher priority task has to wait until the current task finishes its execution.

    The priority-driven execution is achieved by using an event dispatcher, which sorts and dispatches events that trigger the execution of tasks. The events being dispatched are called TM events (implemented by the TMEvent class). An TM event has a priority and a remaining processing time, among other properties. The priority of the event is inherited from its destination port, which may further inherit its priority from the actor that contains the port. Whenever an event is produced by an actor, it is queued with the event dispatcher. At any time, the event with the highest priority is dequeued, and delivered into its destination receiver. The director then starts the execution of the destination actor (by calling its prefire() method). After that, the director tracks how much time remained for the task to finish processing the event.

    The events, called interrupt events, produced by calling fireAt() on this director are treated differently. These events carry a time stamp, and are queued with another queue which sorts these events in their chronological order. When the modeling time reaches an interrupt event time, (regardless whether there is a task executing), the interrupt event is processed. And the corresponding source actor is fired, which may in turn produce some TM events. If one of these TM events has a higher priority than the event being processed by the current task, and the execution is preemptive, then the current tasks is stalled, and the task triggered by the highest priority event is started. Note that, a task is always granted the resource that is specified by the executionTime, no matter whether it has been preempted. When that amount of time is elapsed, the fire() method of the actor will be called, and the actor is expected to produce its output, if there is any.

    The TM domain can be nested with other (timed) domains. In that case, the inputs from the outside domain are treated as interrupts that happen at the (outside) current time.

    This director supports executions that synchronize to real time. To enable such an execution, set the synchronizeToRealTime parameter to true.

    Since:
    Ptolemy II 2.0
    Version:
    $Id$
    Author:
    Jie Liu, Edward A. Lee
    See Also:
    DEEvent
    Pt.AcceptedRating:
    Yellow (janneck)
    Pt.ProposedRating:
    Yellow (liuj)

    • Field Detail

      • preemptive

        public Parameter preemptive
        Indicating whether the execution of the actors is preemptable. The default value is false, of type boolean.

      • defaultTaskExecutionTime

        public Parameter defaultTaskExecutionTime
        The default execution time of a task (i.e. actor). If an actor (or its ports) does not specify its execution time, then this number will be used. The default value is 0.0, of type double, meaning that the task takes no time to execute (similar to the synchrony assumption in Synchronous/Reactive models).

      • synchronizeToRealTime

        public Parameter synchronizeToRealTime
        Indicating whether the execution synchronizes to the real time. This parameter has default value false, of type boolean. If this parameter is true, then the director does not process events until the elapsed real time matches the time stamp of the events.

      • _scheduleListeners

        protected java.util.LinkedList _scheduleListeners
        The list of schedule listeners registered with this object.

    • Constructor Detail

      • TMDirector

        public TMDirector​(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 - Container of the director.
        name - Name of this director.
        Throws:
        IllegalActionException - If the director is not compatible with the specified container.
        NameDuplicationException - If the name collides with a property in the container.

    • Method Detail

      • addScheduleListener

        public void addScheduleListener​(ScheduleListener listener)
        Append a listener to the current set of schedule listeners. If the listener is already in the set, do not add it again.
        Parameters:
        listener - The listener to which to send scheduling messages.
        See Also:
        removeScheduleListener(ScheduleListener)

      • attributeChanged

        public void attributeChanged​(Attribute attribute)
                      throws IllegalActionException
        Update the director parameters when the attributes are changed. If the change is stopTime, or defaultTaskExecutionTime, then check whether its value is less than zero. If so, throw an exception.
        Overrides:
        attributeChanged in class Director
        Parameters:
        attribute - The changed parameter.
        Throws:
        IllegalActionException - If the parameter set is not valid.

      • fire

        public void fire()
          throws IllegalActionException
        Execute the model for one iteration. It first compare the current time to the time stamp of the first event in the interrupt event queue. If they are equal, then dequeue the events at the current time from the interrupt event queue, and fire the destination actors. If the current time is less than the time stamp of the first event in the interrupt event queue, then look at the TM event queue. Pick the task with the highest priority and start/continue its execution. If the task has executionTime being zero, then finish that task. Otherwise, finish its execution util time advances.
        Specified by:
        fire in interface Executable
        Overrides:
        fire in class Director
        Throws:
        IllegalActionException - If an interrupt is in the past, or one of the execution methods of an actor throws it.

      • fireAt

        public Time fireAt​(Actor actor,
                   Time time,
                   int microstep)
            throws IllegalActionException
        Request an interrupt at the specified time. This inserts an event into the interrupt event queue. The corresponding actor will be executed when the current time of this director reaches the specified time.
        Overrides:
        fireAt in class Director
        Parameters:
        actor - The scheduled actor to fire.
        time - The scheduled time to fire.
        microstep - The microstep (ignored by this director).
        Returns:
        The same time argument passed in.
        Throws:
        IllegalActionException - If requested time is in the past.
        See Also:
        Director.fireAtCurrentTime(Actor), Director.fireContainerAt(Time)

      • initialize

        public void initialize()
                throws IllegalActionException
        Set the starting time of execution and initialize all the actors. If this is director is not at the top level and the interrupt event queue is not empty, the request a refire from the executive director.
        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 TMReceiver.
        Overrides:
        newReceiver in class Director
        Returns:
        a new TMReceiver.

      • prefire

        public boolean prefire()
                throws IllegalActionException
        Advance time to the next event time (or the outside time if this director is embedded in another domain); if there are any tasks that finish at the current time, then finish the execution of the current task by calling the fire() method of that actors. If synchronizeToRealTime is true, then wait until the real time has caught up the current time.
        Specified by:
        prefire in interface Executable
        Overrides:
        prefire in class Director
        Returns:
        True
        Throws:
        IllegalActionException - If the execution method of one of the actors throws it.

      • postfire

        public boolean postfire()
                 throws IllegalActionException
        If the current time is greater than the stop time, or both interrupt event queue and TM event queue are empty then return false. Otherwise, return true.
        Specified by:
        postfire in interface Executable
        Overrides:
        postfire in class Director
        Returns:
        Whether the execution should continue.
        Throws:
        IllegalActionException - Not thrown in this baseclass.

      • removeScheduleListener

        public void removeScheduleListener​(ScheduleListener listener)
        Remove a schedule listener from this director. If the listener is not attached to this director, do nothing.
        Parameters:
        listener - The ScheduleListener to be removed.
        See Also:
        addScheduleListener(ScheduleListener)

      • _disableActor

        protected void _disableActor​(Actor actor)
        Disable the specified actor. All events destined for this actor will be ignored. If the argument is null, then do nothing.
        Parameters:
        actor - The actor to disable.

      • _displaySchedule

        protected final void _displaySchedule()
        Send the status of the current TM scheduling to all debug listeners that have registered. By convention, messages should not include a newline at the end. The newline will be added by the listener, if appropriate.

      • _displaySchedule

        protected final void _displaySchedule​(java.lang.String actorName,
                                      double time,
                                      int scheduleEvent)
        Send a debug message to all debug listeners that have registered. By convention, messages should not include a newline at the end. The newline will be added by the listener, if appropriate.
        Parameters:
        actorName - The name of the actor.
        time - The time.
        scheduleEvent - The schedule event.

      • _enqueueEvent

        protected void _enqueueEvent​(TMEvent event)
        Put an event into the event queue with the specified destination receiver, token, and priority.
        Parameters:
        event - The event to be enqueued.