ptolemy.domains.tm.kernel
Class TMDirector

java.lang.Object
  ptolemy.kernel.util.NamedObj
      ptolemy.kernel.util.Attribute
          ptolemy.actor.Director
              ptolemy.domains.tm.kernel.TMDirector

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable, Executable, Initializable, TimedDirector, Changeable, Debuggable, DebugListener, Derivable, ModelErrorHandler, MoMLExportable, Moveable, Nameable

public class TMDirector
extends Director
implements TimedDirector

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 57040 2010-01-27 20:52:32Z cxh $

Author:

Jie Liu, Edward A. Lee

See Also:

DEEvent, Serialized Form

Accepted Rating:

Yellow (janneck)

Proposed Rating:

Yellow (liuj)

Nested Class Summary

Nested classes/interfaces inherited from class ptolemy.kernel.util.NamedObj

NamedObj.ContainedObjectsIterator

Field Summary

private java.util.Set	_disabledActors
private CalendarQueue	_eventQueue
private DECQEventQueue	_interruptQueue
private Time	_nextIterationTime
private Time	_outsideTime
private boolean	_preemptive
private long	_realStartTime
protected java.util.LinkedList	_scheduleListeners The list of schedule listeners registered with this object.
private Time	_startTime
private Time	_stopTime
private boolean	_synchronizeToRealTime
Parameter	defaultTaskExecutionTime The default execution time of a task (i.e. actor).
Parameter	preemptive Indicating whether the execution of the actors is preemptable.
Parameter	startTime Starting time of the simulation.
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

_actorsFinishedExecution, _currentTime, _finishRequested, _initializables, _stopRequested, timeResolution

Fields inherited from class ptolemy.kernel.util.NamedObj

_changeListeners, _changeLock, _changeRequests, _debugging, _debugListeners, _elementName, _isPersistent, _verbose, _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.
private void	_initParameters()
private void	_requestFiringAt(Time time)
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.
Dependency	delayDependency(double delay) Return a boolean dependency representing a model-time delay of the specified amount.
void	fire() Execute the model for one iteration.
Time	fireAt(Actor actor, Time 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, _fireContainerAt, _isEmbedded, _isTopLevel, _transferInputs, _transferOutputs, addInitializable, createSchedule, defaultDependency, finish, fireAt, fireAtCurrentTime, getCausalityInterface, getCurrentTime, getErrorTolerance, getGlobalTime, getModelNextIterationTime, getModelStartTime, getModelStopTime, getModelTime, getNextIterationTime, getStartTime, getStopTime, getTimeResolution, implementsStrictActorSemantics, initialize, invalidateResolvedTypes, invalidateSchedule, isFireFunctional, isStopRequested, isStrict, iterate, preinitialize, removeInitializable, requestInitialization, setContainer, setCurrentTime, setModelTime, stop, stopFire, suggestedModalModelDirectors, supportMultirateFiring, terminate, transferInputs, transferOutputs, wrapup

Methods inherited from class ptolemy.kernel.util.Attribute

_checkContainer, _getContainedObject, _propagateExistence, clone, getContainer, moveDown, moveToFirst, moveToIndex, moveToLast, moveUp, setName, updateContent

Methods inherited from class ptolemy.kernel.util.NamedObj

_addAttribute, _adjustOverride, _attachText, _cloneFixAttributeFields, _debug, _debug, _debug, _debug, _debug, _exportMoMLContents, _getIndentPrefix, _isMoMLSuppressed, _markContentsDerived, _propagateValue, _recordDecoratedAttributes, _removeAttribute, _splitName, _stripNumericSuffix, _validateSettables, addChangeListener, addDebugListener, attributeList, attributeList, attributeTypeChanged, clone, containedObjectsIterator, deepContains, depthInHierarchy, description, description, event, executeChangeRequests, exportMoML, exportMoML, exportMoML, exportMoML, exportMoML, exportMoMLPlain, getAttribute, getAttribute, getAttributes, getChangeListeners, getClassName, getDecoratorAttribute, getDecoratorAttributes, getDerivedLevel, getDerivedList, getDisplayName, getElementName, getFullName, getModelErrorHandler, getName, getName, getPrototypeList, getSource, handleModelError, isDeferringChangeRequests, isOverridden, isPersistent, lazyContainedObjectsIterator, message, propagateExistence, propagateValue, propagateValues, removeChangeListener, removeDebugListener, requestChange, setClassName, setDeferringChangeRequests, setDerivedLevel, setDisplayName, setModelErrorHandler, setPersistent, setSource, sortContainedObjects, toplevel, toString, uniqueName, validateSettables, workspace

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface ptolemy.actor.TimedDirector

getModelTime, getTimeResolution

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

startTime

public Parameter startTime

Starting time of the simulation. The default value is 0.0, of type DoubleToken.

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

The list of schedule listeners registered with this object.

_eventQueue

private CalendarQueue _eventQueue

_interruptQueue

private DECQEventQueue _interruptQueue

_preemptive

private boolean _preemptive

_synchronizeToRealTime

private boolean _synchronizeToRealTime

_disabledActors

private java.util.Set _disabledActors

_outsideTime

private Time _outsideTime

_nextIterationTime

private Time _nextIterationTime

_realStartTime

private long _realStartTime

_startTime

private Time _startTime

_stopTime

private Time _stopTime

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.

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.

delayDependency

public Dependency delayDependency(double delay)

Return a boolean dependency representing a model-time delay of the specified amount.

Specified by:

delayDependency in interface TimedDirector

Parameters:

delay - A non-negative delay.

Returns:

A boolean dependency representing a delay.

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

Returns:

The same time argument passed in.

Throws:

IllegalActionException - If requested time is in the past.

See Also:

Director.fireAtCurrentTime(Actor)

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.

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 Initializable

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

_initParameters

private void _initParameters()

_requestFiringAt

private void _requestFiringAt(Time time)
                       throws IllegalActionException

Throws:

IllegalActionException