ptolemy.domains.tm.kernel
Class TMDirector

java.lang.Object
  extended byptolemy.kernel.util.NamedObj
      extended byptolemy.kernel.util.Attribute
          extended byptolemy.actor.Director
              extended byptolemy.domains.tm.kernel.TMDirector
All Implemented Interfaces:
Changeable, java.lang.Cloneable, Debuggable, DebugListener, Derivable, Executable, ModelErrorHandler, MoMLExportable, Nameable, java.io.Serializable

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: TMDirector.java,v 1.24 2004/04/13 05:12:36 cxh Exp $
Author:
Jie Liu, Edward A. Lee
See Also:
DEEvent, Serialized Form
Accepted Rating:
Yellow (janneck)
Proposed Rating:
Yellow (liuj)

Nested Class Summary
 
Nested classes inherited from class ptolemy.kernel.util.NamedObj
NamedObj.ContainedObjectsIterator
 
Field Summary
protected  java.util.LinkedList _scheduleListeners
           
 Parameter defaultTaskExecutionTime
          The default execution time of a task (i.e. actor).
 Parameter preemptive
          Indicating whether the execution of the actors is preemptable.
 Parameter stopTime
          The stop time of the model, only effective when this director is at the top level.
 Parameter synchronizeToRealTime
          Indicating whether the execution synchronizes to the real time.
 
Fields inherited from class ptolemy.actor.Director
_currentTime, _stopRequested
 
Fields inherited from class ptolemy.kernel.util.NamedObj
_changeListeners, _changeLock, _changeRequests, _debugging, _debugListeners, _elementName, _isPersistent, _workspace, ATTRIBUTES, CLASSNAME, COMPLETE, CONTENTS, DEEP, FULLNAME, LINKS
 
Fields inherited from interface ptolemy.actor.Executable
COMPLETED, NOT_READY, STOP_ITERATING
 
Constructor Summary
TMDirector()
          Construct a director in the default workspace with an empty string as its name.
TMDirector(CompositeEntity container, java.lang.String name)
          Construct a director in the given container with the given name.
TMDirector(Workspace workspace)
          Construct a director in the workspace with an empty name.
 
Method Summary
protected  void _disableActor(Actor actor)
          Disable the specified actor.
protected  void _displaySchedule()
          Send the status of the current TM scheduling to all debug listeners that have registered.
protected  void _displaySchedule(java.lang.String actorName, double time, int scheduleEvent)
          Send a debug message to all debug listeners that have registered.
protected  void _enqueueEvent(TMEvent event)
          Put an event into the event queue with the specified destination receiver, token, and priority.
 void addScheduleListener(ScheduleListener listener)
          Append a listener to the current set of schedule listeners.
 void attributeChanged(Attribute attribute)
          Update the director parameters when the attributes are changed.
 void fire()
          Execute the model for one iteration.
 void fireAt(Actor actor, double time)
          Request an interrupt at the specified time.
 void initialize()
          Set the starting time of execution and initialize all the actors.
 Receiver newReceiver()
          Return a new TMReceiver.
 boolean postfire()
          If the current time is greater than the stop time, or both interrupt event queue and TM event queue are empty then return false.
 boolean prefire()
          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.
 void preinitialize()
          In addition to the preinitialization implemented in the super class, create the interrupt event queue and the TM event queue.
 void removeScheduleListener(ScheduleListener listener)
          Remove a schedule listener from this director.
 
Methods inherited from class ptolemy.actor.Director
_description, _isEmbedded, _isTopLevel, _writeAccessRequired, domainPolymorphicTransferInputs, domainPolymorphicTransferOutputs, fireAtCurrentTime, getCurrentTime, getNextIterationTime, getTimeResolution, initialize, invalidateResolvedTypes, invalidateSchedule, iterate, needWriteAccess, requestInitialization, setContainer, setCurrentTime, setTimeResolution, stop, stopFire, terminate, transferInputs, transferOutputs, wrapup
 
Methods inherited from class ptolemy.kernel.util.Attribute
_getContainedObject, _propagateExistence, clone, getContainer, setName
 
Methods inherited from class ptolemy.kernel.util.NamedObj
_addAttribute, _attachText, _cloneFixAttributeFields, _debug, _debug, _debug, _debug, _debug, _exportMoMLContents, _getIndentPrefix, _isMoMLSuppressed, _markContentsDerived, _propagateValue, _removeAttribute, _splitName, _stripNumericSuffix, addChangeListener, addDebugListener, attributeList, attributeList, attributeTypeChanged, clone, containedObjectsIterator, deepContains, depthInHierarchy, description, description, event, executeChangeRequests, exportMoML, exportMoML, exportMoML, exportMoML, exportMoML, getAttribute, getAttribute, getAttributes, getChangeListeners, getClassName, getDerivedLevel, getDerivedList, getElementName, getFullName, getModelErrorHandler, getName, getName, getPrototypeList, getSource, handleModelError, isDeferringChangeRequests, isOverridden, isPersistent, message, propagateExistence, propagateValue, propagateValues, removeChangeListener, removeDebugListener, requestChange, setClassName, setDeferringChangeRequests, setDerivedLevel, setModelErrorHandler, setPersistent, setSource, toplevel, toString, uniqueName, validateSettables, workspace
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

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).


stopTime

public Parameter stopTime
The stop time of the model, only effective when this director is at the top level. This parameter is of type double. The value defaults to Double.MAX_VALUE.


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
Constructor Detail

TMDirector

public TMDirector()
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.


TMDirector

public TMDirector(Workspace workspace)
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.

Parameters:
workspace - The workspace of this object.

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.

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 NamedObj
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 void fireAt(Actor actor,
                   double time)
            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.
Throws:
IllegalActionException - If requested time is in the past.

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 Executable
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.

preinitialize

public void preinitialize()
                   throws IllegalActionException
In addition to the preinitialization implemented in the super class, create the interrupt event queue and the TM event queue.

Specified by:
preinitialize in interface Executable
Overrides:
preinitialize in class Director
Throws:
IllegalActionException - If thrown by the super class.

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 base class.

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.

_disableActor

protected void _disableActor(Actor actor)
Disable the specified actor. All events destinated 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.