Package ptolemy.domains.de.kernel

Class DEDirector

java.lang.Object

ptolemy.kernel.util.NamedObj

ptolemy.kernel.util.Attribute

ptolemy.actor.Director

ptolemy.domains.de.kernel.DEDirector

All Implemented Interfaces:

java.lang.Cloneable, Executable, Initializable, SuperdenseTimeDirector, Changeable, Debuggable, DebugListener, Derivable, ModelErrorHandler, MoMLExportable, Moveable, Nameable

Direct Known Subclasses:

AbstractATCDirector, MetroIIDEDirector, MetroIIDEDirectorForPtides, PtidesDirector, QSSDirector, TCSDirector, WirelessDirector

public class DEDirector
extends Director
implements SuperdenseTimeDirector

This director implements the discrete-event (DE) model of computation (MoC). It should be used as the local director of a CompositeActor that is to be executed according to the DE MoC. This director maintains a totally ordered set of events and processes these events in the order defined on their tags and depths.

An event is associated with a tag, which is a tuple of timestamp and microstep. A timestamp indicates the model time when this event occurs. It is an object of the Time class. A microstep is an integer which represents the index of the sequence of execution phases when this director processes events with the same timestamp. Two tags are equal if they have the same timestamp and microstep. If two events have the same tag, they are called simultaneous events.

Microsteps can only be increased by calling the fireAt() method. For example, when an actor requests to be fired again at the current model time, a new event with the same timestamp but a bigger microstep (incremented by 1) will be generated.

An event is also associated with a depth reflecting its priority, based on which a DE director chooses the execution order for simultaneous events. A depth is an integer and a larger value of depth indicates a lower priority. The depth of an event is determined by topologically sorting all the ports of actors according to their data dependencies over which there is no time delay.

The order of events is defined as follows. An event A is said to be earlier than another event B if A's timestamp is smaller than B's; or if A's timestamp is the same as B's, and A's microstep is smaller than B's; or if A's tag is the same as B's, and A's depth is smaller than B's. By giving events this well-defined order, this director can handle simultaneous events in a deterministic way.

The bottleneck in a typical DE simulator is in the maintenance of the global event queue. This director uses the calendar queue as the global event queue. This is an efficient algorithm with O(1) time complexity in both enqueue and dequeue operations. Sorting in the CalendarQueue class is done according to the order defined above.

The complexity of the calendar algorithm is sensitive to the length of the event queue. When the size of the event queue becomes too long or changes very often, the simulation performance suffers from the penalties of queuing and dequeuing events. A few mechanisms are implemented to reduce such penalties by keeping the event queue short. The first mechanism is to only store in the event queue pure events and the trigger events with the same timestamp and microstep as those of the director. See DEEvent for explanation of these two types of events. What is more, no duplicate trigger events are allowed in the event queue. Another mechanism is that in a hierarchical model, each level keeps a local event queue. A lower level only reports the earliest event to its upper level to schedule a future firing. The last mechanism is to maintain a list which records all actors that are disabled. Any triggers sent to the actors in this list are discarded.

In the initialize() method, depths of actors and IO ports are statically analyzed and calculated. They are not calculated in the preinitialize() method because hierarchical models may change their structures during their preinitialize() method. For example, a modal model does not specify its initial state (and its refinement) until the end of its preinitialize() method. See FSMActor. In order to support mutation, this director recalculates the depths at the beginning of its next iteration.

There are two types of depths: one is associated with IO ports, which reflects the order of trigger events; the other one is associated with actors, which is for pure events. The relationship between the depths of IO ports and actors is that the depth of an actor is the smallest of the depths of its IO ports. Pure events can only be produced by calling the fireAt() method, and trigger events can only be produced by actors that produce outputs. See DEReceiver.put(Token).

Directed loops of IO ports with no delay will trigger an exception. These are called causality loops. Such loops can be broken with actors whose output ports do not have an immediate dependence on their input ports, such as the TimeDelay actor. Notice that the TimeDelay actor breaks a causality loop even if the time delay is set to 0.0. This is because DE uses a superdense notion of time. The output is interpreted as being strictly later than the input even though its time value is the same. Whether a causality loop exists is determined by the CausalityInterface returned by each actor's getCausalityInterface() method.

An input port in a DE model contains an instance of DEReceiver. When a token is put into a DEReceiver, that receiver posts a trigger event to the director. This director sorts trigger events in a global event queue.

An iteration, in the DE domain, is defined as processing all the events whose tags are equal to the current tag of the director (also called the model tag). At the beginning of the fire() method, this director dequeues a subset of the earliest events (the ones with smallest timestamp, microstep, and depth) that have the same destination actor from the global event queue. Then, this director fires that actor. This actor must consume tokens from its input port(s), and usually produces new events on its output port(s). These new events will trigger the destination actors to fire. It is important that the actor actually consumes tokens from its inputs, even if the tokens are solely used to trigger reactions, because the actor will be fired repeatedly until there are no more tokens in its input ports with the same tag, or until the actor returns false in its prefire() method. The director then keeps dequeuing and processing the earliest events from the event queue until no more events have the same tag.

Note that each time this director fires an actor, it also invokes postfire() on that actor. Note that under this policy, it is possible for an actor to be fired and postfired multiple times in an iteration. This does not really correctly implement superdense time semantics, but it is an approximation that will reject some models that should be able to be executed. An actor like the TimeDelay will be fired (and postfired) multiple times at a superdense time index if it is in a feedback loop.

A model starts from the time specified by startTime. This is blank by default, which indicates that the start time is the current time of the enclosing director, if there is one, and 0.0 otherwise. The stop time of the execution can be set using the stopTime parameter. The parameter has a default value Infinity, which means the execution runs forever.

Execution of a DE model ends when the timestamp of the earliest event exceeds the stop time. This stopping condition is checked inside the postfire() method of this director. By default, execution also ends when the global event queue becomes empty. Sometimes, the desired behaviour is for the director to wait on an empty queue until another thread makes new events available. For example, a DE actor may produce events when a user hits a button on the screen. To prevent ending the execution when there are no more events, set the stopWhenQueueIsEmpty parameter to false.

Parameters isCQAdaptive, minBinCount, and binCountFactor, are used to configure the calendar queue. Changes to these parameters are ignored when the model is running.

If the parameter synchronizeToRealTime is set to true, then the director will not process events until the real time elapsed since the model started matches the timestamp of the event. This ensures that the director does not get ahead of real time. However, of course, this does not ensure that the director keeps up with real time.

This director tolerates changes to the model during execution. The change should be queued with a component in the hierarchy using requestChange(). While invoking those changes, the method invalidateSchedule() is expected to be called, notifying the director that the topology it used to calculate the priorities of the actors is no longer valid. This will result in the priorities (depths of actors) being recalculated the next time prefire() is invoked.

Limitations: According to [1], at each microstep, DE should perform a fixed point iteration. This implementation does not do that, and consequently, this director is not able to execute all correctly constructed DE models. For an example, see $PTII/ptolemy/domains/de/test/auto/DEFixedPointLimitation.xml. That example has a DE opaque composite actor in a feedback loop. In principle, there should be no causality loop. The actor output should be able to be produced without knowing the input. However, the inside director has to guarantee that when it fires any of its contained actors, all inputs of a given microstep are available to that actor. As a consequence, the opaque actor also needs to know all of its inputs at the current microstep. Hence, a causality loop is reported. We encourage the reader to make a variant of this director that can handle such models.

References:
[1] Lee, E. A. and H. Zheng (2007). Leveraging Synchronous Language Principles for Heterogeneous Modeling and Design of Embedded Systems. EMSOFT, Salzburg, Austria, October, ACM.

Since:

Ptolemy II 0.2

Version:

$Id$

Author:

Lukito Muliadi, Edward A. Lee, Jie Liu, Haiyang Zheng

Pt.AcceptedRating:

Yellow (hyzheng)

Pt.ProposedRating:

Green (hyzheng)

Nested Class Summary

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

NamedObj.ContainedObjectsIterator

Field Summary

Fields

Modifier and Type	Field	Description
protected java.util.List<Actor>	_actorsFinished	Actors that just got granted all the resources they needed for execution but have not actually been fired yet.
protected java.util.HashMap<Actor,java.util.List<DEEvent>>	_actorsInExecution	Actors and their matching events currently in execution and waiting for resources.
protected java.util.Set<Actor>	_disabledActors	The set of actors that have returned false in their postfire() methods.
protected DEEventQueue	_eventQueue	The queue used for sorting events.
protected java.lang.Object	_eventQueueLock	The lock for the queue.
protected boolean	_isInitializing	A local boolean variable indicating whether this director is in initialization phase execution.
protected int	_microstep	The current microstep.
protected boolean	_noMoreActorsToFire	Set to true when it is time to end the execution.
protected boolean	_stopFireRequested	Flag that stopFire() has been called.
Parameter	binCountFactor	The factor when adjusting the bin number.
Parameter	enforceMicrostepSemantics	A flag indicating whether this director should enforce microstep semantics, throwing an exception when actors deliver events at microstep 0.
Parameter	isCQAdaptive	Specify whether the calendar queue adjusts its bin number at run time.
Parameter	minBinCount	The minimum (initial) number of bins in the calendar queue.
Parameter	stopWhenQueueIsEmpty	Specify whether the execution stops when the queue is empty.
Parameter	synchronizeToRealTime	Specify whether the execution should synchronize to the real time.

Fields inherited from class ptolemy.actor.Director

_actorsFinishedExecution, _aspectForActor, _aspectsPresent, _defaultMicrostep, _executionAspects, _finishRequested, _initializables, _nextScheduleTime, _stopRequested, _tokenSentToCommunicationAspect, _zeroTime, localClock, startTime, stopTime

Fields inherited from class ptolemy.kernel.util.NamedObj

_changeListeners, _changeLock, _changeRequests, _debugging, _debugListeners, _deferChangeRequests, _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

Constructors

Constructor	Description
DEDirector()	Construct a director in the default workspace with an empty string as its name.
DEDirector(CompositeEntity container, java.lang.String name)	Construct a director in the given container with the given name.
DEDirector(Workspace workspace)	Construct a director in the workspace with an empty name.

Method Summary

Modifier and Type	Method	Description
protected void	_actorFired()	Perform book keeping procedures after an actor firing.
protected boolean	_checkForNextEvent()	Enforces a firing of a DE director only handles events with the same tag.
protected void	_disableActor(Actor actor)	Disable the specified actor.
protected void	_enqueueEvent(Actor actor, Time time, int defaultMicrostep)	Put a pure event into the event queue to schedule the given actor to fire at the specified timestamp.
protected void	_enqueueTriggerEvent(IOPort ioPort)	Put a trigger event into the event queue.
protected int	_fire()	Advance the current model tag to that of the earliest event in the event queue, and fire all actors that have requested or are triggered to be fired at the current tag.
protected int	_getDepthOfActor(Actor actor)	Return the depth of an actor.
protected int	_getDepthOfIOPort(IOPort ioPort)	Return the depth of an ioPort.
protected Actor	_getNextActorToFire()	Dequeue the events that have the smallest tag from the event queue.
protected void	_issueExecutionAspectWarning()	In DE, a warning is issued when execution aspects are used because these might change the DE semantics of the execution.
protected void	_noActorToFire()	There are no actor to fire.
protected void	_requestFiring()	Request that the container of this director be refired in some future time specified by the first event of the local event queue.
protected boolean	_schedule(NamedObj actor, Time timestamp)	Schedule an actor for execution on a ExecutionAspect.
void	addDebugListener(DebugListener listener)	Append the specified listener to the current set of debug listeners.
void	attributeChanged(Attribute attribute)	Update the director parameters when attributes are changed.
void	cancelFireAt(Actor actor, Time time)	Cancel a requested firing of the given actor at the given model time microstep 1.
void	cancelFireAt(Actor actor, Time time, int index)	Cancel a requested firing of the given actor at the given model time with the given microstep.
java.lang.Object	clone(Workspace workspace)	Clone the object into the specified workspace.
java.lang.String	describePriorities()	Return a string that describes the depths of actors and their ports.
void	fire()	Fire actors according to events in the event queue.
Time	fireAt(Actor actor, Time time)	Schedule an actor to be fired at the specified time by posting a pure event to the director, and return the time at which the specified actor will be fired.
Time	fireAt(Actor actor, Time time, int index)	Request a firing of the given actor at the given model time with the given microstep.
Time	fireAtCurrentTime(Actor actor)	Fire the actor actor at the current model time or, if synchronizeToRealTime is enabled and we are past the initialization phase of execution, then fire the actor at the model time that corresponds to the current real time.
void	fireAtRelativeTime(Actor actor, Time time)	Schedule an actor to be fired in the specified time relative to the current model time.
CausalityInterface	getCausalityInterface()	Return a causality interface for the composite actor that contains this director.
int	getIndex()	Return a superdense time index for the current time, where the index is equal to the microstep.
int	getMicrostep()	Get the current microstep.
Time	getModelNextIterationTime()	Return the timestamp of the next event in the queue.
Time	getNextEventTime()	Return the timestamp of the next event in the queue.
double	getStartTime()	Deprecated. As Ptolemy II 4.1, use Director.getModelStartTime() instead.
double	getStopTime()	Deprecated. As Ptolemy II 4.1, use Director.getModelStopTime() instead.
void	initialize()	Initialize all the contained actors by invoke the initialize() method of the super class.
void	invalidateSchedule()	Indicate that a schedule for the model may no longer be valid.
java.lang.Object	mutexLockObject()	Return the object to use to obtain a mutex lock on this director.
Receiver	newReceiver()	Return a new receiver of the type DEReceiver.
boolean	postfire()	Return false if there are no more actors to be fired or the stop() method has been called.
boolean	prefire()	Set the model time to the outside time if this director is not at the top level.
void	preinitialize()	Set the current timestamp to the model start time, invoke the preinitialize() methods of all actors deeply contained by the container.
void	removeDebugListener(DebugListener listener)	Unregister a debug listener.
void	resumeActor(NamedObj actor)	Resume the execution of an actor that was previously blocked because it didn't have all the resources it needed for execution.
void	setIndex(int index)	Set the superdense time index.
void	stop()	Request the execution of the current iteration to stop.
void	stopFire()	Request the execution of the current iteration to complete.
java.lang.String[]	suggestedModalModelDirectors()	Return an array of suggested directors to use with ModalModel.
boolean	transferInputs(IOPort port)	Transfer data from an input port of the container to the ports it is connected to on the inside.
void	wrapup()	Invoke the wrapup method of the super class.

Methods inherited from class ptolemy.actor.Director

_actorFinished, _consultTimeRegulators, _description, _isEmbedded, _isTopLevel, _transferInputs, _transferOutputs, addInitializable, createSchedule, defaultDependency, delayDependency, elapsedTimeSinceStart, finish, fireAt, fireContainerAt, fireContainerAt, getCurrentTime, getDeadline, getEnvironmentTime, getExecutionAspect, getGlobalTime, getModelStartTime, getModelStopTime, getModelTime, getNextIterationTime, getTimeResolution, implementsStrictActorSemantics, initialize, invalidateResolvedTypes, isEmbedded, isFireFunctional, isStopRequested, isStrict, iterate, notifyTokenSentToCommunicationAspect, preinitialize, removeInitializable, requestInitialization, resume, scheduleContainedActors, setContainer, setCurrentTime, setEmbedded, setModelTime, setTimeResolution, supportMultirateFiring, suspend, terminate, transferOutputs, transferOutputs

Methods inherited from class ptolemy.kernel.util.Attribute

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

Methods inherited from class ptolemy.kernel.util.NamedObj

_addAttribute, _adjustOverride, _attachText, _cloneFixAttributeFields, _containedDecorators, _copyChangeRequestList, _debug, _debug, _debug, _debug, _debug, _executeChangeRequests, _exportMoMLContents, _getIndentPrefix, _isMoMLSuppressed, _markContentsDerived, _notifyHierarchyListenersAfterChange, _notifyHierarchyListenersBeforeChange, _propagateValue, _removeAttribute, _splitName, _stripNumericSuffix, _validateSettables, addChangeListener, addHierarchyListener, attributeDeleted, attributeList, attributeList, attributeTypeChanged, clone, containedObjectsIterator, decorators, 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, notifyOfNameChange, propagateExistence, propagateValue, propagateValues, removeAttribute, removeChangeListener, removeHierarchyListener, 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

Field Detail

binCountFactor

public Parameter binCountFactor

The factor when adjusting the bin number. This parameter must contain an IntToken. Changes to this parameter are ignored when the model is running. The value defaults to 2.

enforceMicrostepSemantics

public Parameter enforceMicrostepSemantics

A flag indicating whether this director should enforce microstep semantics, throwing an exception when actors deliver events at microstep 0. Such events can arise from attempting to deliver to the DE domain a continuous signal from the Continuous domain. This is a boolean that defaults to false.

isCQAdaptive

public Parameter isCQAdaptive

Specify whether the calendar queue adjusts its bin number at run time. This parameter must contain a BooleanToken. If this parameter is true, the calendar queue will adapt its bin number with respect to the distribution of events. Changes to this parameter are ignored when the model is running. The value defaults to true.

minBinCount

public Parameter minBinCount

The minimum (initial) number of bins in the calendar queue. This parameter must contain an IntToken. Changes to this parameter are ignored when the model is running. The value defaults to 2.

stopWhenQueueIsEmpty

public Parameter stopWhenQueueIsEmpty

Specify whether the execution stops when the queue is empty. This parameter must contain a BooleanToken. If this parameter is true, the execution of the model will be stopped when the queue is empty. The value defaults to true.

synchronizeToRealTime

public Parameter synchronizeToRealTime

Specify whether the execution should synchronize to the real time. This parameter must contain a BooleanToken. If this parameter is true, then do not process events until the elapsed real time matches the time stamp of the events. The value defaults to false.

_actorsInExecution

protected java.util.HashMap<Actor,java.util.List<DEEvent>> _actorsInExecution

Actors and their matching events currently in execution and waiting for resources.

_actorsFinished

protected java.util.List<Actor> _actorsFinished

Actors that just got granted all the resources they needed for execution but have not actually been fired yet. After the actor is fired, it is removed from this list.

_disabledActors

protected java.util.Set<Actor> _disabledActors

The set of actors that have returned false in their postfire() methods. Events destined for these actors are discarded and the actors are never fired.

_eventQueue

protected DEEventQueue _eventQueue

The queue used for sorting events.

_eventQueueLock

protected java.lang.Object _eventQueueLock

The lock for the queue.

_isInitializing

protected boolean _isInitializing

A local boolean variable indicating whether this director is in initialization phase execution.

_microstep

protected int _microstep

The current microstep.

_noMoreActorsToFire

protected boolean _noMoreActorsToFire

Set to true when it is time to end the execution.

_stopFireRequested

protected boolean _stopFireRequested

Flag that stopFire() has been called.

Constructor Detail

DEDirector

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

Throws:

NameDuplicationException - If construction of Time objects fails.

IllegalActionException - If construction of Time objects fails.

DEDirector

public DEDirector(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.

Parameters:

workspace - The workspace of this object.

Throws:

NameDuplicationException - If construction of Time objects fails.

IllegalActionException - If construction of Time objects fails.

DEDirector

public DEDirector(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 container not a CompositeActor and the name collides with an entity in the container.

Method Detail

addDebugListener

public void addDebugListener(DebugListener listener)

Append the specified listener to the current set of debug listeners. If an event queue has been created, register the listener to that queue.

Specified by:

addDebugListener in interface Debuggable

Overrides:

addDebugListener in class NamedObj

Parameters:

listener - The listener to be added to the list of listeners to which debug messages are sent.

See Also:

removeDebugListener(DebugListener)

attributeChanged

public void attributeChanged(Attribute attribute)
                      throws IllegalActionException

Update the director parameters when attributes are changed. Changes to isCQAdaptive, minBinCount, and binCountFactor parameters will only be effective on the next time when the model is executed.

Overrides:

attributeChanged in class Director

Parameters:

attribute - The changed parameter.

Throws:

IllegalActionException - If the parameter set is not valid. Not thrown in this class.

cancelFireAt

public void cancelFireAt(Actor actor,
                         Time time)
                  throws IllegalActionException

Cancel a requested firing of the given actor at the given model time microstep 1.

Parameters:

actor - The actor scheduled to be fired.

time - The requested time.

Throws:

IllegalActionException - If cancelling a firing is not supported by the current event queue.

cancelFireAt

public void cancelFireAt(Actor actor,
                         Time time,
                         int index)
                  throws IllegalActionException

Cancel a requested firing of the given actor at the given model time with the given microstep.

Parameters:

actor - The actor scheduled to be fired.

time - The requested time.

index - The microstep.

Throws:

IllegalActionException - If cancelling a firing is not supported by the current event queue.

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 attribute with no container.

Overrides:

clone in class Director

Parameters:

workspace - The workspace for the cloned object.

Returns:

The new Attribute.

Throws:

java.lang.CloneNotSupportedException - Not thrown in this base class

See Also:

NamedObj.exportMoML(Writer, int, String), NamedObj.setDeferringChangeRequests(boolean)

describePriorities

public java.lang.String describePriorities()
                                    throws IllegalActionException

Return a string that describes the depths of actors and their ports. These depths are used to prioritize firings, where lower depths result in higher priorities.

Returns:

A string that describes the depths of actors and their ports.

Throws:

IllegalActionException - If there is a causality loop.

fire

public void fire()
          throws IllegalActionException

Fire actors according to events in the event queue. The actual selecting which events to process is done in _fire(). _fire() will return whether the previous firing was successful. According to this information, it is decided whether _fire() should be called again in order to keep processing events. After each actor firing, book keeping procedures are called, to keep track of the current state of the scheduler. The model time of the next events are also checked to see if we have produced an event of smaller timestamp.

Specified by:

fire in interface Executable

Overrides:

fire in class Director

Throws:

IllegalActionException - If we couldn't process an event or if an event of smaller timestamp is found within the event queue.

See Also:

_fire()

fireAt

public Time fireAt(Actor actor,
                   Time time)
            throws IllegalActionException

Schedule an actor to be fired at the specified time by posting a pure event to the director, and return the time at which the specified actor will be fired. If the requested time is in the past relative to the current time, then it will be increased to match current time. The caller to this method is responsible for throwing an exception if it is not acceptable for that time to differ from the requested time.

If this director is embedded within another model (the container has an executive director), and this method is being called between iterations of this director (which can only occur from a thread different from the one firing this director), then this method also delegates a request to the executive director to fire the container of this director at the requested time. If the executive director returns a value different from the specified time, then this method will use that revised value to schedule the firing of the specified actor, and will return that value.

A subtle corner case can occur in a multithreaded execution that will trigger an exception. In particular, it is possible for this director to delegate a request to its executive director, and for that request to be honored before it has posted the event on its own local event queue. This situation is avoided, for example, by putting this director within a ThreadedComposite actor. If this situation occurs, an exception will be thrown.

Overrides:

fireAt in class Director

Parameters:

actor - The scheduled actor to fire.

time - The scheduled time to fire.

Returns:

The time at which the actor will be fired, which matches the argument.

Throws:

IllegalActionException - If the event queue is not ready, or if a threading error occurs that would result in returning a time value that is already in the past.

See Also:

Director.fireAtCurrentTime(Actor)

fireAt

public Time fireAt(Actor actor,
                   Time time,
                   int index)
            throws IllegalActionException

Request a firing of the given actor at the given model time with the given microstep. Most actors will not want to use this method, but if you need for a firing to occur at microstep 0, then use this method to trigger that firing. Note that any actor that fires at microstep 0 is expected to not produce any output events at that firing.

Overrides:

fireAt in class Director

Parameters:

actor - The actor scheduled to be fired.

time - The requested time.

index - The microstep.

Returns:

An instance of Time with value NEGATIVE_INFINITY, or if there is an executive director, the time at which the container of this director will next be fired in response to this request.

Throws:

IllegalActionException - If there is an executive director and it throws it. Derived classes may choose to throw this exception for other reasons.

See Also:

fireAtCurrentTime(Actor)

fireAtCurrentTime

public Time fireAtCurrentTime(Actor actor)
                       throws IllegalActionException

Fire the actor actor at the current model time or, if synchronizeToRealTime is enabled and we are past the initialization phase of execution, then fire the actor at the model time that corresponds to the current real time. This model time is computed by subtracting the model start time recorded by this director at the beginning of the simulation from the system time and dividing by 1000, as the default unit of time is seconds.

Overrides:

fireAtCurrentTime in class Director

Parameters:

actor - The actor to be fired.

Returns:

The model time the actor will be fired at.

Throws:

IllegalActionException - If thrown while creating a Time object or while calling fireAt.

See Also:

Director.fireAt(Actor, Time)

fireAtRelativeTime

public void fireAtRelativeTime(Actor actor,
                               Time time)
                        throws IllegalActionException

Schedule an actor to be fired in the specified time relative to the current model time.

Parameters:

actor - The scheduled actor to fire.

time - The scheduled time to fire.

Throws:

IllegalActionException - If the specified time contains a negative time value, or event queue is not ready.

getCausalityInterface

public CausalityInterface getCausalityInterface()

Return a causality interface for the composite actor that contains this director. This base class returns an instance of CausalityInterfaceForComposites, but subclasses may override this to return a domain-specific causality interface.

Overrides:

getCausalityInterface in class Director

Returns:

A representation of the dependencies between input ports and output ports of the container.

getMicrostep

public int getMicrostep()

Get the current microstep.

Returns:

microstep of the current time.

See Also:

getIndex(), setIndex(int), SuperdenseTimeDirector

getModelNextIterationTime

public Time getModelNextIterationTime()
                               throws IllegalActionException

Return the timestamp of the next event in the queue. The next iteration time, for example, is used to estimate the run-ahead time, when a continuous time composite actor is embedded in a DE model. If there is no event in the event queue, a positive infinity object is returned.

Overrides:

getModelNextIterationTime in class Director

Returns:

The time stamp of the next event in the event queue.

Throws:

IllegalActionException - If Time object cannot be created.

See Also:

Director.getModelTime()

getNextEventTime

public Time getNextEventTime()

Return the timestamp of the next event in the queue. This is different from getModelNextIterationTime as it just considers the local event queue and not that of directors higher up in the model hierarchy.

Returns:

The timestamp of the next event in the local event queue.

getStartTime

@Deprecated
public final double getStartTime()
                          throws IllegalActionException

Deprecated.

As Ptolemy II 4.1, use Director.getModelStartTime() instead.

Return the start time parameter value.

When the start time is too big, the double representation loses the specified time resolution. To avoid this loss, use the Director.getModelStartTime() instead.

Overrides:

getStartTime in class Director

Returns:

the start time.

Throws:

IllegalActionException - If the enclosing director throws it.

getStopTime

@Deprecated
public final double getStopTime()
                         throws IllegalActionException

Deprecated.

As Ptolemy II 4.1, use Director.getModelStopTime() instead.

Return the stop time.

When the stop time is too big, the double representation loses the specified time resolution. To avoid this loss, use the Director.getModelStopTime() instead.

Overrides:

getStopTime in class Director

Returns:

the stop time.

Throws:

IllegalActionException - If getModelStopTime() throws it.

getIndex

public int getIndex()

Return a superdense time index for the current time, where the index is equal to the microstep.

Specified by:

getIndex in interface SuperdenseTimeDirector

Returns:

A superdense time index.

See Also:

setIndex(int), SuperdenseTimeDirector

initialize

public void initialize()
                throws IllegalActionException

Initialize all the contained actors by invoke the initialize() method of the super class. If any events are generated during the initialization, and the container is not at the top level, request a refiring.

The real start time of the model is recorded when this method is called. This method is not synchronized on the workspace, so the caller should be.

Specified by:

initialize in interface Initializable

Overrides:

initialize in class Director

Throws:

IllegalActionException - If the initialize() method of the super class throws it.

invalidateSchedule

public void invalidateSchedule()

Indicate that a schedule for the model may no longer be valid. This forces the actor depths to be recalculated the next time they are accessed.

Overrides:

invalidateSchedule in class Director

mutexLockObject

public java.lang.Object mutexLockObject()

Return the object to use to obtain a mutex lock on this director. This class overrides the base class to return the event queue lock object.

Overrides:

mutexLockObject in class Director

Returns:

An object to use to obtain a lock on this director.

newReceiver

public Receiver newReceiver()

Return a new receiver of the type DEReceiver.

Overrides:

newReceiver in class Director

Returns:

A new DEReceiver.

postfire

public boolean postfire()
                 throws IllegalActionException

Return false if there are no more actors to be fired or the stop() method has been called. Otherwise, if the director is an embedded director and the local event queue is not empty, request the executive director to refire the container of this director at the timestamp of the first event in the event queue.

Specified by:

postfire in interface Executable

Overrides:

postfire in class Director

Returns:

True If this director will be fired again.

Throws:

IllegalActionException - If the postfire method of the super class throws it, or the stopWhenQueueIsEmpty parameter does not contain a valid token, or refiring can not be requested.

prefire

public boolean prefire()
                throws IllegalActionException

Set the model time to the outside time if this director is not at the top level. Check the time of the next event to decide whether to fire. Return true if there are inputs to this composite actor, or the time of the next event is equal to the current model time. Otherwise, return false.

Note that microsteps are not synchronized.

Throw an exception if the current model time is greater than the next event time.

Specified by:

prefire in interface Executable

Overrides:

prefire in class Director

Returns:

True if the composite actor is ready to fire.

Throws:

IllegalActionException - If there is a missed event, or the prefire method of the super class throws it, or can not query the tokens of the input ports of the container of this director.

preinitialize

public void preinitialize()
                   throws IllegalActionException

Set the current timestamp to the model start time, invoke the preinitialize() methods of all actors deeply contained by the container.

This method should be invoked once per execution, before any iteration. Actors cannot produce output data in their preinitialize() methods. If initial events are needed, e.g. pure events for source actor, the actors should do so in their initialize() method.

This method is not synchronized on the workspace, so the caller should be.

Specified by:

preinitialize in interface Initializable

Overrides:

preinitialize in class Director

Throws:

IllegalActionException - If the preinitialize() method of the container or one of the deeply contained actors throws it, or the parameters, minBinCount, binCountFactor, and isCQAdaptive, do not have valid tokens.

removeDebugListener

public void removeDebugListener(DebugListener listener)

Unregister a debug listener. If the specified listener has not been previously registered, then do nothing.

Specified by:

removeDebugListener in interface Debuggable

Overrides:

removeDebugListener in class NamedObj

Parameters:

listener - The listener to remove from the list of listeners to which debug messages are sent.

See Also:

addDebugListener(DebugListener)

resumeActor

public void resumeActor(NamedObj actor)
                 throws IllegalActionException

Resume the execution of an actor that was previously blocked because it didn't have all the resources it needed for execution. This method puts an event into the queue for the current time.

Overrides:

resumeActor in class Director

Parameters:

actor - The actor that resumes execution.

Throws:

IllegalActionException - Not thrown here but in derived classes.

setIndex

public void setIndex(int index)
              throws IllegalActionException

Set the superdense time index. This should only be called by an enclosing director.

Specified by:

setIndex in interface SuperdenseTimeDirector

Parameters:

index - The index of the superdense time object. Events that occur at the same time have different indicies.

Throws:

IllegalActionException - Not thrown in this base class.

See Also:

getIndex(), SuperdenseTimeDirector

stop

public void stop()

Request the execution of the current iteration to stop. This is similar to stopFire(), except that the current iteration is not allowed to complete. This is useful if there is actor in the model that has a bug where it fails to consume inputs. An iteration will never terminate if such an actor receives an event. If the director is paused waiting for events to appear in the event queue, then it stops waiting, and calls stopFire() for all actors that are deeply contained by the container of this director.

Specified by:

stop in interface Executable

Overrides:

stop in class Director

stopFire

public void stopFire()

Request the execution of the current iteration to complete. If the director is paused waiting for events to appear in the event queue, then it stops waiting, and calls stopFire() for all actors that are deeply contained by the container of this director.

Specified by:

stopFire in interface Executable

Overrides:

stopFire in class Director

suggestedModalModelDirectors

public java.lang.String[] suggestedModalModelDirectors()

Return an array of suggested directors to use with ModalModel. Each director is specified by its full class name. The first director in the array will be the default director used by a modal model.

Overrides:

suggestedModalModelDirectors in class Director

Returns:

An array of suggested directors to be used with ModalModel.

See Also:

Director.suggestedModalModelDirectors()

transferInputs

public boolean transferInputs(IOPort port)
                       throws IllegalActionException

Transfer data from an input port of the container to the ports it is connected to on the inside. This transfers at most one token on each channel, and overrides the base class to temporarily set the microstep to match or exceed that of the enclosing director if the enclosing director implements SuperdenseTimeDirector. Otherwise, it sets the microstep to match or exceed 1 to ensure that inputs are interpreted as discrete values.

Overrides:

transferInputs in class Director

Parameters:

port - The port to transfer tokens from.

Returns:

True if at least one data token is transferred.

Throws:

IllegalActionException - If the port is not an opaque input port.

wrapup

public void wrapup()
            throws IllegalActionException

Invoke the wrapup method of the super class. Reset the private state variables.

Specified by:

wrapup in interface Initializable

Overrides:

wrapup in class Director

Throws:

IllegalActionException - If the wrapup() method of one of the associated actors throws it.

_actorFired

protected void _actorFired()
                    throws IllegalActionException

Perform book keeping procedures after an actor firing. In this base class, do nothing.

Throws:

IllegalActionException - Not thrown in this base class. Derived classes may throw it if book keeping procedures are not successful.

_checkForNextEvent

protected boolean _checkForNextEvent()
                              throws IllegalActionException

Enforces a firing of a DE director only handles events with the same tag. Checks what is the model time of the earliest event in the event queue.

Returns:

true if the earliest event in the event queue is at the same model time as the event that was just processed. Else if that event's timestamp is in the future, return false.

Throws:

IllegalActionException - If model time is set backwards.

_disableActor

protected void _disableActor(Actor actor)

Disable the specified actor. All events destined to this actor will be ignored. If the argument is null, then do nothing.

Parameters:

actor - The actor to disable.

_enqueueEvent

protected void _enqueueEvent(Actor actor,
                             Time time,
                             int defaultMicrostep)
                      throws IllegalActionException

Put a pure event into the event queue to schedule the given actor to fire at the specified timestamp.

The default microstep for the queued event is equal to one, unless the time is equal to the current time, where the microstep will be the current microstep plus one.

The depth for the queued event is the minimum of the depths of all the ports of the destination actor.

If there is no event queue or the given actor is disabled, then this method does nothing.

Parameters:

actor - The actor to be fired.

time - The timestamp of the event.

defaultMicrostep - If the requested firing time is in the future, then use this defaultMicrostep for the microstep.

Throws:

IllegalActionException - If the time argument is less than the current model time, or the depth of the actor has not be calculated, or the new event can not be enqueued.

_enqueueTriggerEvent

protected void _enqueueTriggerEvent(IOPort ioPort)
                             throws IllegalActionException

Put a trigger event into the event queue. A trigger event is an event destined for the specified port that will convey data to that port at the current time and microstep. The depth for the queued event is the depth of the destination IO port. The microstep of the enqueued event will be the greater of the current microstep and 1. That is, an event destined for a port is never queued with microstep less than 1.

If the event queue is not ready or the actor containing the destination port is disabled, do nothing.

Parameters:

ioPort - The destination IO port.

Throws:

IllegalActionException - If the time argument is not the current time, or the depth of the given IO port has not be calculated, or the new event can not be enqueued.

_fire

protected int _fire()
             throws IllegalActionException

Advance the current model tag to that of the earliest event in the event queue, and fire all actors that have requested or are triggered to be fired at the current tag. If synchronizeToRealTime is true, then before firing, wait until real time matches or exceeds the timestamp of the event. Note that the default unit for time is seconds.

Each actor is fired repeatedly (prefire(), fire()), until either it has no more input tokens, or its prefire() method returns false. Note that if the actor fails to consume its inputs, then this can result in an infinite loop. Each actor that is fired is then postfired once at the conclusion of the iteration.

If there are no events in the event queue, then the behavior depends on the stopWhenQueueIsEmpty parameter. If it is false, then this thread will stall until events become available in the event queue. Otherwise, time will advance to the stop time and the execution will halt.

Returns:

0 if firing was successful, and the next event in event queue should be checked for processing; -1 if there's no actor to fire, and we should not keep firing; 1 if there's no actor to fire, but the next event should be checked for processing.

Throws:

IllegalActionException - If the firing actor throws it, or event queue is not ready, or an event is missed, or time is set backwards.

_getDepthOfActor

protected int _getDepthOfActor(Actor actor)
                        throws IllegalActionException

Return the depth of an actor.

Parameters:

actor - An actor whose depth is requested.

Returns:

An integer indicating the depth of the given actor.

Throws:

IllegalActionException - If the actor depth has not been computed (this should not occur if the ioPort is under the control of this director).

_getDepthOfIOPort

protected int _getDepthOfIOPort(IOPort ioPort)
                         throws IllegalActionException

Return the depth of an ioPort.

Parameters:

ioPort - A port whose depth is requested.

Returns:

An integer representing the depth of the specified ioPort.

Throws:

IllegalActionException - If the ioPort does not have a depth (this should not occur if the ioPort is under the control of this director).

_getNextActorToFire

protected Actor _getNextActorToFire()
                             throws IllegalActionException

Dequeue the events that have the smallest tag from the event queue. Return their destination actor. Advance the model tag to their tag. If the timestamp of the smallest tag is greater than the stop time then return null. If there are no events in the event queue, and the stopWhenQueueIsEmpty parameter is set to true, then return null. Both cases will have the effect of stopping the simulation.

If the stopWhenQueueIsEmpty parameter is false and the queue is empty, then stall the current thread by calling wait() on the _eventQueue until there are new events available. If the synchronizeToRealTime parameter is true, then this method may suspend the calling thread by using Object.wait(long) to let elapsed real time catch up with the current model time.

Returns:

The next actor to be fired, which can be null.

Throws:

IllegalActionException - If event queue is not ready, or an event is missed, or time is set backwards.

_issueExecutionAspectWarning

protected void _issueExecutionAspectWarning()
                                     throws IllegalActionException

In DE, a warning is issued when execution aspects are used because these might change the DE semantics of the execution. In Ptides, this is not the case.

Throws:

IllegalActionException - If thrown by getExecutionAspect().

_noActorToFire

protected void _noActorToFire()
                       throws IllegalActionException

There are no actor to fire. In this base class, do nothing. Subclasses may override this method in case there is no actor to fire.

Throws:

IllegalActionException - Not thrown in this base class. Derived classes may throw it if unable to get the next actuation event.

_schedule

protected boolean _schedule(NamedObj actor,
                            Time timestamp)
                     throws IllegalActionException

Schedule an actor for execution on a ExecutionAspect. If the actor can execute this method returns true. If resources are not available this method returns false.

Overrides:

_schedule in class Director

Parameters:

actor - The actor.

timestamp - The time the actor requests to be scheduled.

Returns:

True if actor was scheduled and can be fired.

Throws:

IllegalActionException - Thrown if parameters cannot be read, actor cannot be scheduled or container cannot be fired at future time.

_requestFiring

protected void _requestFiring()
                       throws IllegalActionException

Request that the container of this director be refired in some future time specified by the first event of the local event queue. This method is used when the director is embedded inside an opaque composite actor. If the queue is empty, then throw an IllegalActionException.

Throws:

IllegalActionException - If the queue is empty, or if the executive director does not respect the fireAt() call.