Package ptolemy.domains.ptera.kernel

Class PteraDirector

java.lang.Object

ptolemy.kernel.util.NamedObj

ptolemy.kernel.util.Attribute

ptolemy.actor.Director

ptolemy.domains.ptera.kernel.PteraDirector

All Implemented Interfaces:

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

public class PteraDirector
extends Director
implements ValueListener

A Ptera director implements the Event Relationship Graph semantics, and can be used by Ptera controllers (instances of PteraController) in Ptera modal models (instances of PteraModalModel). This director has an event queue where events can be scheduled and are ordered by their time stamps. Events are processed according to their time-stamp order. Actions of the events are executed when the events are processed.

Between events there may be scheduling relations. If an event schedules another to occur after a certain amount of model time, then the other event is placed in the event queue when the first event is processed. Scheduling relations may be guarded by boolean expressions.

Each Ptera controller transparently creates a Ptera director inside. For a Ptera controller that serves as refinement of an event in another Ptera controller, the Ptera director in it invokes the fireAt() method of the Ptera director in the containing Ptera controller. When multiple events are scheduled in one firing of the inner Ptera director, only one invocation of fireAt() is made in postfire() with the most imminent event as the parameter.

This director can be used in DE as a contained model of computation. It can also be used to control timed or untimed models of computation, such as DE, dataflow, and FSM.

Since:

Ptolemy II 8.0

Version:

$Id$

Author:

Thomas Huining Feng

See Also:

DEDirector

Pt.AcceptedRating:

Red (tfeng)

Pt.ProposedRating:

Yellow (tfeng)

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	PteraDirector.TimedEvent	The class to encapsulate information to be stored in an entry in the event queue.

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

NamedObj.ContainedObjectsIterator

Field Summary

Fields

Modifier and Type	Field	Description
StringAttribute	controllerName	Attribute specifying the name of the Ptera controller in the container of this director.
Parameter	LIFO	A Boolean parameter that decides whether simultaneous events should be placed in the event queue in the last-in-first-out (LIFO) fashion or not.

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
PteraDirector(CompositeEntity container, java.lang.String name)	Construct a director in the given container with the given name.

Method Summary

Modifier and Type	Method	Description
protected void	_insertInitialEvents()	Insert initial events into the event queue, and request firing from the director at the higher level, if any.
protected boolean	_isTopLevel()	Return whether this director is top-level.
void	attributeChanged(Attribute attribute)	React to a change in an attribute.
PteraDirector.TimedEvent	cancel(Event event)	Cancel an event that was previously scheduled in the event queue.
java.lang.Object	clone(Workspace workspace)	Clone the director into the specified workspace.
PteraDirector.TimedEvent	findFirst(Event event, boolean findRefinements)	Find the first occurrence of the given event in the event queue.
void	fire()	Fire the director and process the imminent events or the events that react to inputs if inputs are available.
Time	fireAt(Actor actor, Time time, int microstep)	Request a firing of the given actor at the given model time.
void	fireAt(Event event, Time time, Token arguments, java.util.List<NamedObj> triggers, boolean reset)	Request to process an event at the given model time.
void	fireAt(PteraDirector.TimedEvent timedEvent, java.util.List<NamedObj> triggers)	Request to process an event at the given model time.
PteraController	getController()	Return the Ptera controller has the same container as this director.
IllegalActionException	getModelException()	Return the exception (if any) that occurred when the refinement was fired.
Time	getModelTime()	Return the current time object of the model being executed by this director.
void	initialize()	Initialize the model controlled by this director.
void	initialize(Actor actor)	Initialize the given actor, unless it is a RefinementActor (which will be initialized when the event that it refines is fired).
boolean	postfire()	Return true if the director wishes to be scheduled for another iteration.
boolean	prefire()	Return true if the director is ready to fire.
void	preinitialize()	Invoke the preinitialize() method of the superclass.
void	stop()	Request that the director cease execution altogether.
void	stopFire()	Request the execution of the current iteration to complete.
void	valueChanged(Settable settable)	Monitor the change of a variable specified by the settable argument if the execution has started, and invokes fireAt() to request to fire all the events that are listening to that variable at the current model time.
void	wrapup()	Invoke the wrapup() method of the superclass, and clear the event queue.

Methods inherited from class ptolemy.actor.Director

_actorFinished, _consultTimeRegulators, _description, _isEmbedded, _schedule, _transferInputs, _transferOutputs, addInitializable, createSchedule, defaultDependency, delayDependency, elapsedTimeSinceStart, finish, fireAt, fireAt, fireAtCurrentTime, fireContainerAt, fireContainerAt, getCausalityInterface, getCurrentTime, getDeadline, getEnvironmentTime, getExecutionAspect, getGlobalTime, getModelNextIterationTime, getModelStartTime, getModelStopTime, getNextIterationTime, getStartTime, getStopTime, getTimeResolution, implementsStrictActorSemantics, invalidateResolvedTypes, invalidateSchedule, isEmbedded, isFireFunctional, isStopRequested, isStrict, iterate, mutexLockObject, newReceiver, notifyTokenSentToCommunicationAspect, preinitialize, removeInitializable, requestInitialization, resume, resumeActor, scheduleContainedActors, setContainer, setCurrentTime, setEmbedded, setModelTime, setTimeResolution, suggestedModalModelDirectors, supportMultirateFiring, suspend, terminate, transferInputs, 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, addDebugListener, 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, removeDebugListener, 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

LIFO

public Parameter LIFO

A Boolean parameter that decides whether simultaneous events should be placed in the event queue in the last-in-first-out (LIFO) fashion or not.

controllerName

public StringAttribute controllerName

Attribute specifying the name of the Ptera controller in the container of this director. This director must have a Ptera controller that has the same container as this director, otherwise an IllegalActionException will be thrown when action methods of this director are called.

Constructor Detail

PteraDirector

public PteraDirector(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. Create the timeResolution parameter.

Parameters:

container - The container.

name - The name of this director.

Throws:

IllegalActionException - If the name has a period in it, or the director is not compatible with the specified container, or if the time resolution parameter is malformed.

NameDuplicationException - If the container already contains an entity with the specified name.

Method Detail

attributeChanged

public void attributeChanged(Attribute attribute)
                      throws IllegalActionException

React to a change in an attribute. If the changed attribute is the controllerName attribute, then make note that this has changed.

Overrides:

attributeChanged in class Director

Parameters:

attribute - The attribute that changed.

Throws:

IllegalActionException - If thrown by the superclass attributeChanged() method.

cancel

public PteraDirector.TimedEvent cancel(Event event)
                                throws IllegalActionException

Cancel an event that was previously scheduled in the event queue. This method can be called by an event that has an outgoing canceling edge (a SchedulingRelation object with the canceling attribute set to true.

Parameters:

event - The event to be cancelled.

Returns:

The model time at which the cancelled event was previously scheduled, if that event is found in the event queue. If the event is not found, the return is null.

Throws:

IllegalActionException - If the refinement of the given event (if any) cannot be obtained.

clone

public java.lang.Object clone(Workspace workspace)
                       throws java.lang.CloneNotSupportedException

Clone the director into the specified workspace. This calls the base class and then sets the attribute public members to refer to the attributes of the new director.

Overrides:

clone in class Director

Parameters:

workspace - The workspace for the new director.

Returns:

A new director.

Throws:

java.lang.CloneNotSupportedException - If a derived class contains an attribute that cannot be cloned.

See Also:

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

findFirst

public PteraDirector.TimedEvent findFirst(Event event,
                                          boolean findRefinements)
                                   throws IllegalActionException

Find the first occurrence of the given event in the event queue. If findRefinements is true, then the refinements of the given event are also searched for.

Parameters:

event - The event.

findRefinements - Whether refinements of the given event should be searched for.

Returns:

The TimedEvent that contains the event or its refinement.

Throws:

IllegalActionException - If the refinements of the given event cannot be retrieved.

fire

public void fire()
          throws IllegalActionException

Fire the director and process the imminent events or the events that react to inputs if inputs are available. If refinements of events are being executed, fire() of those refinements are called to allow them to fire. Next, if there are events that react to inputs and inputs are available at some input ports, then those events are taken from the event queue and are processed. After these steps, if there are still events that are scheduled at the current model time in the event queue, those events are processed. If those events schedule new events to occur at exactly the same model time, then those newly scheduled events are also processed in the same firing.

Specified by:

fire in interface Executable

Overrides:

fire in class Director

Throws:

IllegalActionException - If inputs cannot be read at the input ports, the controller that contains this director cannot be found, or this exception is raised when firing a refinement or processing an event.

fireAt

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

Request a firing of the given actor at the given model time. This method puts the actor in the event queue in time-stamp order. The actor will be fired later when the model time reaches the scheduled time in a way similar to events being processed from the event queue.

Overrides:

fireAt in class Director

Parameters:

actor - The actor scheduled to be fired.

time - The scheduled time.

microstep - The microstep (ignored by this director).

Returns:

The time at which the actor passed as an argument will be fired.

Throws:

IllegalActionException - If the operation is not permissible (e.g. the given time is in the past), or if the executive director does not support fireAt() precisely (it does not agree to refire this Ptera model at the requested time).

See Also:

Director.fireAtCurrentTime(Actor), Director.fireContainerAt(Time)

fireAt

public void fireAt(Event event,
                   Time time,
                   Token arguments,
                   java.util.List<NamedObj> triggers,
                   boolean reset)
            throws IllegalActionException

Request to process an event at the given model time. This method puts the event in the event queue in time-stamp order. The event will be processed later when the model time reaches the scheduled time.

Parameters:

event - The event scheduled to be processed.

time - The scheduled time.

arguments - The arguments to the event, which must be either an ArrayToken or a RecordToken.

triggers - A list of ports and variables that triggers the event before its scheduled time is reached.

reset - Whether the refinement of the scheduled event should be reinitialized when the event is processed.

Throws:

IllegalActionException - If the operation is not permissible (e.g. the given time is in the past), or if the executive director does not support fireAt() precisely (it does not agree to refire this Ptera model at the requested time)

fireAt

public void fireAt(PteraDirector.TimedEvent timedEvent,
                   java.util.List<NamedObj> triggers)
            throws IllegalActionException

Request to process an event at the given model time. This method puts the event in the event queue in time-stamp order. The event will be processed later when the model time reaches the scheduled time.

Parameters:

timedEvent - The TimedEvent object to be scheduled.

triggers - A list of ports and variables that triggers the event before its scheduled time is reached.

Throws:

IllegalActionException - If the operation is not permissible (e.g. the given time is in the past), or if the executive director does not support fireAt() precisely (it does not agree to refire this Ptera model at the requested time)

getController

public PteraController getController()
                              throws IllegalActionException

Return the Ptera controller has the same container as this director. The name of the Ptera controller is specified by the controllerName attribute. The mode controller must have the same container as this director. This method is read-synchronized on the workspace. This method is a duplication of FSMDirector.getController(). However, due to the class hierarchy, there is no easy way to reuse the code.

Returns:

The mode controller of this director.

Throws:

IllegalActionException - If no controller is found.

getModelTime

public Time getModelTime()

Return the current time object of the model being executed by this director. This time can be set with the setModelTime() method. In this base class, time never increases, and there are no restrictions on valid times.

Overrides:

getModelTime in class Director

Returns:

The current time.

See Also:

Director.setModelTime(Time)

getModelException

public IllegalActionException getModelException()

Return the exception (if any) that occurred when the refinement was fired.

Returns:

The exception.

initialize

public void initialize()
                throws IllegalActionException

Initialize the model controlled by this director. The initialize() method of the superclass is called. After that, the initial schedule is computed. To initialize a schedule, the initial events are placed in the event queue.

Specified by:

initialize in interface Initializable

Overrides:

initialize in class Director

Throws:

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

initialize

public void initialize(Actor actor)
                throws IllegalActionException

Initialize the given actor, unless it is a RefinementActor (which will be initialized when the event that it refines is fired). This method is generally called by the initialize() method of the director, and by the manager whenever an actor is added to an executing model as a mutation. This method will generally perform domain-specific initialization on the specified actor and call its initialize() method. In this base class, only the actor's initialize() method of the actor is called and no domain-specific initialization is performed. Typical actions a director might perform include starting threads to execute the actor or checking to see whether the actor can be managed by this director. For example, a time-based domain (such as CT) might reject sequence based actors.

Overrides:

initialize in class Director

Parameters:

actor - The actor that is to be initialized.

Throws:

IllegalActionException - If the actor is not acceptable to the domain. Not thrown in this base class.

postfire

public boolean postfire()
                 throws IllegalActionException

Return true if the director wishes to be scheduled for another iteration. The postfire() method of the superclass is called. If it returns true, this director further checks whether there is still any event in the event queue. If so, it returns true. Otherwise, it returns false. If this director is top-level, it sets the model time to be the time stamp of the next event.

Specified by:

postfire in interface Executable

Overrides:

postfire in class Director

Returns:

True to continue execution, and false otherwise.

Throws:

IllegalActionException - If the executive director does not support fireAt() precisely (that is, it does not agree to refire this Ptera model at the requested time).

prefire

public boolean prefire()
                throws IllegalActionException

Return true if the director is ready to fire. This method is called by the container of this director to determine whether the director is ready to execute. If the prefire() method of the superclass returns true, it checks whether either of the following conditions is true: 1) some input ports have received tokens and there are events that are scheduled to react to inputs, and 2) some events have been scheduled at the current model time. If either condition is true, this method returns true.

Specified by:

prefire in interface Executable

Overrides:

prefire in class Director

Returns:

True if the director is ready to execute, or false otherwise.

Throws:

IllegalActionException - If the superclass throws it, or if the tokens at the input ports cannot be checked.

preinitialize

public void preinitialize()
                   throws IllegalActionException

Invoke the preinitialize() method of the superclass. If this director is directly associated with a modal model (i.e., not in any controller), then preinitialize() of the director in the controller of the modal model is also called.

Specified by:

preinitialize in interface Initializable

Overrides:

preinitialize in class Director

Throws:

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

stop

public void stop()

Request that the director cease execution altogether.

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

valueChanged

public void valueChanged(Settable settable)

Monitor the change of a variable specified by the settable argument if the execution has started, and invokes fireAt() to request to fire all the events that are listening to that variable at the current model time.

Specified by:

valueChanged in interface ValueListener

Parameters:

settable - The variable that has been changed.

wrapup

public void wrapup()
            throws IllegalActionException

Invoke the wrapup() method of the superclass, and clear the event queue.

Specified by:

wrapup in interface Initializable

Overrides:

wrapup in class Director

Throws:

IllegalActionException - If the wrapup() method of the superclass throws it.

_insertInitialEvents

protected void _insertInitialEvents()
                             throws IllegalActionException

Insert initial events into the event queue, and request firing from the director at the higher level, if any.

Throws:

IllegalActionException - If whether an event is initial event cannot be checked, or if the executive director does not support fireAt() precisely (it does not agree to refire this Ptera at the requested time).

_isTopLevel

protected boolean _isTopLevel()

Return whether this director is top-level. A Ptera director is top-level if _isTopLevel() of the superclass returns true, and this director is directly associated with a modal model.

Overrides:

_isTopLevel in class Director

Returns:

True if this director is top-level.