ptolemy.actor
Class Director

java.lang.Object
  ptolemy.kernel.util.NamedObj
      ptolemy.kernel.util.Attribute
          ptolemy.actor.Director

All Implemented Interfaces:

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

Direct Known Subclasses:

CaseDirector, CIDirector, DDFDirector, DEDirector, DistributedDirector, DoNothingDirector, FSMDirector, FSMDirector, IterateOverArray.IterateDirector, ModelExecutor.Wrapper.WrapperDirector, PetriNetDirector, ProcessDirector, PteraDirector, PtinyOSDirector, RealTimeComposite.RealTimeDirector, StaticSchedulingDirector, TesterDirector, ThreadedComposite.ThreadedDirector, TMDirector, TransformationRule.TransformationDirector

public class Director
extends Attribute
implements Executable

A Director governs the execution within a CompositeActor. A composite actor that contains a director is said to be opaque, and the execution model within the composite actor is determined by the contained director. This director is called the local director of a composite actor. A composite actor is also aware of the director of its container, which is referred to as its executive director. A director may also be contained by a CompositeEntity that is not a CompositeActor, in which case it acts like any other entity within that composite.

A top-level composite actor is generally associated with a manager as well as a local director. The Manager has overall responsibility for executing the application, and is often associated with a GUI. Top-level composite actors have no executive director and getExecutiveDirector() will return null.

A local director is responsible for invoking the actors contained by the composite. If there is no local director, then the executive director is given the responsibility. The getDirector() method of CompositeActor, therefore, returns the local director, if there is one, and otherwise returns the executive director. Thus, it returns whichever director is responsible for executing the contained actors, or null if there is none. Whatever it returns is called simply the director (vs. local director or executive director).

A director implements the action methods (preinitialize(), initialize(), prefire(), fire(), postfire(), iterate(), and wrapup()). In this base class, default implementations are provided that may or may not be useful in specific domains. In general, these methods will perform domain-dependent actions, and then call the respective methods in all contained actors.

The director also provides methods to optimize the iteration portion of an execution. This is done by setting the workspace to be read-only during an iteration. In this base class, the default implementation results in a read/write workspace. Derived classes (e.g. domain specific directors) should override the _writeAccessRequired() method to report that write access is not required. If none of the directors in a simulation require write access, then it is safe to set the workspace to be read-only, which will result in faster execution.

This class also specifies a parameter timeResolution. This is a double with default 1E-10, which is 10^-10. All time values are rounded to the nearest multiple of this value. If the value is changed during a run, an exception is thrown. This is a shared parameter, which means that all instances of Director in the model will have the same value for this parameter. Changing one of them changes all of them.

The timeResolution parameter is not visible to the user by default. Subclasses can make it visible by calling

 timeResolution.setVisibility(Settable.FULL);
 

in their constructors.

Since:

Ptolemy II 0.2

Version:

$Id: Director.java 59167 2010-09-21 17:08:02Z cxh $

Author:

Mudit Goel, Edward A. Lee, Lukito Muliadi, Steve Neuendorffer, John Reekie

See Also:

Serialized Form

Accepted Rating:

Yellow (neuendor)

Proposed Rating:

Green (eal)

Nested Class Summary

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

NamedObj.ContainedObjectsIterator

Field Summary

protected java.util.Set	_actorsFinishedExecution Set of actors that have returned false from postfire(), indicating that they do not wish to be iterated again.
protected Time	_currentTime The current time of the model.
protected boolean	_finishRequested Indicator that finish() has been called.
protected java.util.List<Initializable>	_initializables List of objects whose (pre)initialize() and wrapup() methods should be slaved to these.
protected boolean	_stopRequested Indicator that a stop has been requested by a call to stop().
private double	_timeResolution Time resolution cache, with a reasonable default value.
SharedParameter	timeResolution The time precision used by this director.

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

Director()
Construct a director in the default workspace with an empty string as its name.

Director(CompositeEntity container, java.lang.String name)
Construct a director in the given container with the given name.

Director(Workspace workspace)
Construct a director in the workspace with an empty name.

Method Summary

private void	_addIcon()
private void	_createReceivers() Create receivers for all contained actors.
protected java.lang.String	_description(int detail, int indent, int bracket) Return a description of the object.
protected Time	_fireContainerAt(Time time) Request a firing of the container of this director at the specified time and throw an exception if the executive director does not agree to do it at the requested time.
private void	_initializeParameters()
protected boolean	_isEmbedded() Return true if this director is embedded inside an opaque composite actor contained by another composite actor.
protected boolean	_isTopLevel() Return true if this is a top-level director.
protected boolean	_transferInputs(IOPort port) Transfer at most one data token from the given input port of the container to the ports it is connected to on the inside.
protected boolean	_transferOutputs(IOPort port) Transfer at most one data token from the given output port of the container to the ports it is connected to on the outside.
void	addInitializable(Initializable initializable) Add the specified object to the list of objects whose preinitialize(), initialize(), and wrapup() methods should be invoked upon invocation of the corresponding methods of this object.
void	attributeChanged(Attribute attribute) Override the base class to update local variables.
void	createSchedule() Create the schedule for this director, if necessary.
Dependency	defaultDependency() Return a default dependency to use between input input ports and output ports.
void	finish() Request that after the current iteration finishes postfire() returns false, indicating to the environment that no more iterations should be invoked.
void	fire() Iterate all the deeply contained actors of the container of this director exactly once.
void	fireAt(Actor actor, double time) Deprecated. Instead of using double as time argument, use a time object instead. As of Ptolemy 4.1, replaced by fireAt(Actor, Time)
Time	fireAt(Actor actor, Time time) Request a firing of the given actor at the given model time.
Time	fireAtCurrentTime(Actor actor) Request a firing of the given actor at the current model time.
CausalityInterface	getCausalityInterface() Return a causality interface for the composite actor that contains this director.
double	getCurrentTime() Deprecated. As of Ptolemy II 4.1, replaced by getModelTime()
double	getErrorTolerance() Return the error tolerance, if any, of this director.
Time	getGlobalTime() Return the global time for this model.
Time	getModelNextIterationTime() Return the next time of interest in the model being executed by this director or the director of any enclosing model up the hierarchy.
Time	getModelStartTime() Get the start time of the model.
Time	getModelStopTime() Get the stop time of the model.
Time	getModelTime() Return the current time object of the model being executed by this director.
double	getNextIterationTime() Deprecated. As of Ptolemy II 4.1, replaced by getModelNextIterationTime()
double	getStartTime() Deprecated. As of Ptolemy II 4.1, replaced by getModelStartTime()
double	getStopTime() Deprecated. As of Ptolemy II 4.1, replaced by getModelStopTime()
double	getTimeResolution() Get the time resolution of the model.
boolean	implementsStrictActorSemantics() Return true if this director assumes and exports the strict actor semantics, as described in this paper: A.
void	initialize() Initialize the model controlled by this director.
void	initialize(Actor actor) Initialize the given actor.
void	invalidateResolvedTypes() Indicate that resolved types in the model may no longer be valid.
void	invalidateSchedule() Indicate that a schedule for the model may no longer be valid, if there is a schedule.
boolean	isFireFunctional() Return false.
boolean	isStopRequested() Return true if stop has been requested.
boolean	isStrict() Return true.
int	iterate(int count) Invoke a specified number of iterations of this director.
Receiver	newReceiver() Return a new receiver of a type compatible with this director.
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() Validate the attributes and then invoke the preinitialize() methods of all its deeply contained actors.
void	preinitialize(Actor actor) Preintialize the actor.
void	removeInitializable(Initializable initializable) Remove the specified object from the list of objects whose preinitialize(), initialize(), and wrapup() methods should be invoked upon invocation of the corresponding methods of this object.
void	requestInitialization(Actor actor) Queue an initialization request with the manager.
void	setContainer(NamedObj container) Specify the container.
void	setCurrentTime(double newTime) Deprecated. As of Ptolemy 4.1, replaced by setModelTime(ptolemy.actor.util.Time)
void	setModelTime(Time newTime) Set a new value to the current time of the model, where the new time must be no earlier than the current time.
void	stop() Request that the director cease execution altogether.
void	stopFire() Request that execution of the current iteration stop.
java.lang.String[]	suggestedModalModelDirectors() Return an array of suggested directors to be used with ModalModel.
boolean	supportMultirateFiring() Return a boolean to indicate whether a ModalModel under control of this director supports multirate firing.
void	terminate() Terminate any currently executing model with extreme prejudice.
boolean	transferInputs(IOPort port) Transfer data from an input port of the container to the ports it is connected to on the inside.
boolean	transferOutputs(IOPort port) Transfer data from an output port of the container to the ports it is connected to on the outside.
void	wrapup() Invoke the wrapup() method of all the actors contained in the director's container.

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

Field Detail

timeResolution

public SharedParameter timeResolution

The time precision used by this director. All time values are rounded to the nearest multiple of this number. This is a double that defaults to "1E-10" which is 10^-10. This is a shared parameter, meaning that changing one instance in a model results in all instances being changed.

_actorsFinishedExecution

protected java.util.Set _actorsFinishedExecution

Set of actors that have returned false from postfire(), indicating that they do not wish to be iterated again.

_currentTime

protected Time _currentTime

The current time of the model.

_finishRequested

protected boolean _finishRequested

Indicator that finish() has been called.

_initializables

protected transient java.util.List<Initializable> _initializables

List of objects whose (pre)initialize() and wrapup() methods should be slaved to these.

_stopRequested

protected boolean _stopRequested

Indicator that a stop has been requested by a call to stop().

_timeResolution

private double _timeResolution

Time resolution cache, with a reasonable default value.

Constructor Detail

Director

public Director()

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.

Director

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

Director

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

Method Detail

addInitializable

public void addInitializable(Initializable initializable)

Add the specified object to the list of objects whose preinitialize(), initialize(), and wrapup() methods should be invoked upon invocation of the corresponding methods of this object.

Specified by:

addInitializable in interface Initializable

Parameters:

initializable - The object whose methods should be invoked.

See Also:

removeInitializable(Initializable), CompositeActor.addPiggyback(Executable)

attributeChanged

public void attributeChanged(Attribute attribute)
                      throws IllegalActionException

Override the base class to update local variables.

Overrides:

attributeChanged in class NamedObj

Parameters:

attribute - The attribute that changed.

Throws:

IllegalActionException - If timeResolution is being changed and the model is executing (and not in preinitialize()).

createSchedule

public void createSchedule()
                    throws IllegalActionException

Create the schedule for this director, if necessary. In this base class nothing is done.

Throws:

IllegalActionException - If the schedule can't be created.

defaultDependency

public Dependency defaultDependency()

Return a default dependency to use between input input ports and output ports. Director subclasses may override this if need specialized dependency. This base class returns BooleanDependency.OTIMES_IDENTITY.

Returns:

A default dependency between input ports and output ports.

See Also:

Dependency, CausalityInterface, Actor.getCausalityInterface()

finish

public void finish()

Request that after the current iteration finishes postfire() returns false, indicating to the environment that no more iterations should be invoked. To support domains where actor firings do not necessarily terminate, such as PN, you may wish to call stopFire() as well to request that those actors complete their firings.

fire

public void fire()
          throws IllegalActionException

Iterate all the deeply contained actors of the container of this director exactly once. This method is not functional, since an iteration of the deeply contained actors may change state in their postfire() method. The actors are iterated in the order that they appear on the list returned by deepEntityList(), which is normally the order in which they were created.

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

In this base class, an attempt is made to fire each actor exactly once, in the order they were created. Prefire is called once, and if prefire returns true, then fire is called once, followed by postfire. The return value from postfire is ignored. If the container is not an instance of CompositeActor, however, then this method does nothing.

Specified by:

fire in interface Executable

Throws:

IllegalActionException - If any called method of one of the associated actors throws it.

fireAt

public void fireAt(Actor actor,
                   double time)
            throws IllegalActionException

Deprecated. Instead of using double as time argument, use a time object instead. As of Ptolemy 4.1, replaced by fireAt(Actor, Time)

Request a firing of the given actor at the given absolute time. This method is only intended to be called from within main simulation thread. Actors that create their own asynchronous threads should used the fireAtCurrentTime() method to schedule firings. This method calls fireAt(Actor, Time) method.

Parameters:

actor - The actor scheduled to be fired.

time - The scheduled time.

Throws:

IllegalActionException - If the operation is not permissible (e.g. the given time is in the past).

fireAt

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

Request a firing of the given actor at the given model time. This base class ignores the request and returns a Time with value Double.NEGATIVE_INFINITY, unless this director is embedded within a model (and has an executive director), in which case, this base class requests that the executive director fire the container of this director at the requested time.

The intent of this method is to request a firing of the actor at the specified time, but this implementation does not assure that. In particular, if there is no executive director, it completely ignores the request. If there is an executive director, then it is not required to do the firing at the specified time. In particular, derived classes may override this method and modify the time of the firing, for example to prevent attempts to fire an actor in the past.

Derived classes should override this method to return the time at which they expect to fire the specified actor. It is up to the actor to throw an exception if it is not acceptable for the time to differ from the requested time.

Note that it is not correct behavior for a director to override this method to simply fire the specified actor. The actor needs to be fired as part of the regular execution cycle of that director, and that needs to occur after this method has returned.

Parameters:

actor - The actor scheduled to be fired.

time - The requested time.

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

Request a firing of the given actor at the current model time. This base class simply calls fireAt(actor, getModelTime()) and returns whatever that returns. Note that fireAt() will modify the requested time if it happens to be in the past by the time it is to be posted on the event queue, which is exactly what we want. Note that the returned time may not match the value returned by getModelTime() prior to this call.

Note that it is not correct behavior for a director to override this method to simply fire the specified actor. The actor needs to be fired as part of the regular execution cycle of that director, and that needs to occur after this method has returned.

Parameters:

actor - The actor to be fired.

Returns:

The time at which the specified actor will be fired, which in this case is whatever fireAt() returns.

Throws:

IllegalActionException - If this method is called before the model is running.

See Also:

fireAt(Actor, Time)

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.

Returns:

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

getCurrentTime

public double getCurrentTime()

Deprecated. As of Ptolemy II 4.1, replaced by getModelTime()

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

Returns:

The current time value.

See Also:

setCurrentTime(double)

getErrorTolerance

public double getErrorTolerance()

Return the error tolerance, if any, of this director. By default, a director has no error tolerance, so this method returns 0.0. Some directors override this to allow computed values to be approximate with a specified precision.

Returns:

the error tolerance.

getGlobalTime

public Time getGlobalTime()
                   throws IllegalActionException

Return the global time for this model. The global time is defined to be the value returned by the @link{#getModelTime()} method of the top-level director in the model.

Returns:

The time of the top-level director in the model.

Throws:

IllegalActionException - If the top level is not an Actor.

getModelNextIterationTime

public Time getModelNextIterationTime()

Return the next time of interest in the model being executed by this director or the director of any enclosing model up the hierarchy. If this director is at the top level, then this default implementation simply returns the current time, since this director does not advance time. If this director is not at the top level, then return whatever the enclosing director returns.

This method is useful for domains that perform speculative execution (such as CT). Such a domain in a hierarchical model (i.e. CT inside DE) uses this method to determine how far into the future to execute.

Derived classes should override this method to provide an appropriate value, if possible. For example, the DEDirector class returns the time value of the next event in the event queue.

Returns:

The time of the next iteration.

See Also:

getModelTime()

getModelStartTime

public Time getModelStartTime()
                       throws IllegalActionException

Get the start time of the model. This base class returns a Time object with 0.0 as the value of the start time. Subclasses need to override this method to get a different start time. For example, CT director and DE director use the value of the startTime parameter to specify the real start time.

Returns:

The start time of the model.

Throws:

IllegalActionException - If the specified start time is invalid.

getModelStopTime

public Time getModelStopTime()
                      throws IllegalActionException

Get the stop time of the model. This base class returns a new Time object with Double.POSITIVE_INFINITY as the value of the stop time. Subclasses need to override this method to get a different stop time. For example, CT director and DE director use the value of the stopTime parameter to specify the real stop time.

Returns:

The stop time of the model.

Throws:

IllegalActionException - If the specified stop time is invalid.

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.

Returns:

The current time.

See Also:

setModelTime(Time)

getNextIterationTime

public double getNextIterationTime()

Deprecated. As of Ptolemy II 4.1, replaced by getModelNextIterationTime()

Return the next time of interest in the model being executed by this director. This method is useful for domains that perform speculative execution (such as CT). Such a domain in a hierarchical model (i.e. CT inside DE) uses this method to determine how far into the future to execute.

In this base class, we return the current time. Derived classes should override this method to provide an appropriate value, if possible.

Note that this method is not made abstract to facilitate the use of the test suite.

Returns:

The time of the next iteration.

getStartTime

public double getStartTime()
                    throws IllegalActionException

Deprecated. As of Ptolemy II 4.1, replaced by getModelStartTime()

Get the start time of the model. This base class returns a Time object with 0.0 as the value of the start time. Subclasses need to override this method to get a different start time. For example, CT director and DE director use the value of the startTime parameter to specify the real start time.

Returns:

The start time of the model.

Throws:

IllegalActionException - If the specified start time is invalid.

getStopTime

public double getStopTime()
                   throws IllegalActionException

Deprecated. As of Ptolemy II 4.1, replaced by getModelStopTime()

Get the stop time of the model. This base class returns a new Time object with Double.MAX_VALUE as the value of the stop time. Subclasses need to override this method to get a different stop time. For example, CT director and DE director use the value of the stopTime parameter to specify the real stop time.

Returns:

The stop time of the model.

Throws:

IllegalActionException - If the specified stop time is invalid.

getTimeResolution

public final double getTimeResolution()

Get the time resolution of the model. The time resolution is the value of the timeResolution parameter. This is the smallest time unit for the model.

Returns:

The time resolution of the model.

implementsStrictActorSemantics

public boolean implementsStrictActorSemantics()

Return true if this director assumes and exports the strict actor semantics, as described in this paper:

A. Goderis, C. Brooks, I. Altintas, E. A. Lee, and C. Goble, "Heterogeneous Composition of Models of Computation," EECS Department, University of California, Berkeley, Tech. Rep. UCB/EECS-2007-139, Nov. 2007. http://www.eecs.berkeley.edu/Pubs/TechRpts/2007/EECS-2007-139.html

In particular, a director that implements this interface guarantees that it will not invoke the postfire() method of an actor until all its inputs are known at the current tag. Moreover, it it will only do so in its own postfire() method, and in its prefire() and fire() methods, it does not change its own state. Thus, such a director can be used within a model of computation that has a fixed-point semantics, such as SRDirector and ContinuousDirector. This base class returns false.

Returns:

True if the director assumes and exports strict actor semantics.

initialize

public void initialize()
                throws IllegalActionException

Initialize the model controlled by this director. Set the current time to the start time or the current time of the executive director, and then invoke the initialize() method of this director on each actor that is controlled by this director. If the container is not an instance of CompositeActor, do nothing. This method should typically be invoked once per execution, after the preinitialization phase, but before any iteration. It may be invoked in the middle of an execution, if reinitialization is desired. Since type resolution has been completed and the current time is set, the initialize() method of a contained actor may produce output or schedule events. If stop() is called during this methods execution, then stop initializing actors immediately. This method is not synchronized on the workspace, so the caller should be.

Specified by:

initialize in interface Initializable

Throws:

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

initialize

public void initialize(Actor actor)
                throws IllegalActionException

Initialize the given actor. 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.

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.

invalidateResolvedTypes

public void invalidateResolvedTypes()

Indicate that resolved types in the model may no longer be valid. This will force type resolution to be redone on the next iteration. This method simply defers to the manager, notifying it. If there is no container, or the container is not an instance of CompositeActor, or if it has no manager, do nothing.

invalidateSchedule

public void invalidateSchedule()

Indicate that a schedule for the model may no longer be valid, if there is a schedule. This method should be called when topology changes are made, or for that matter when any change that may invalidate the schedule is made. In this base class, the method does nothing. In derived classes, it will cause any static schedule information to be recalculated in the prefire method of the director.

isFireFunctional

public boolean isFireFunctional()

Return false. This director iterates actors in its fire() method, which includes an invocation of their postfire() methods, so its fire method changes the state of the model.

Specified by:

isFireFunctional in interface Executable

Returns:

False.

isStrict

public boolean isStrict()
                 throws IllegalActionException

Return true. The transferInputs() method does not check whether the inputs are known before calling hasToken(), and consequently will throw an exception if inputs are not known. Thus, this director requires that inputs be known in order to be able to iterate. Derived classes that can tolerate unknown inputs should override this method to return false.

Specified by:

isStrict in interface Executable

Returns:

True.

Throws:

IllegalActionException - Thrown by subclass.

isStopRequested

public boolean isStopRequested()

Return true if stop has been requested.

Returns:

True if stop() has been called.

See Also:

stop()

iterate

public int iterate(int count)
            throws IllegalActionException

Invoke a specified number of iterations of this director. An iteration is equivalent to invoking prefire(), fire(), and postfire(), in that order. In an iteration, if prefire() returns true, then fire() will be called once, followed by postfire(). Otherwise, if prefire() returns false, fire() and postfire() are not invoked, and this method returns NOT_READY. If postfire() returns false, then no more iterations are invoked, and this method returns STOP_ITERATING. Otherwise, it returns COMPLETED. Also, if the stop() is called during this execution, then immediately stop iterating and return STOP_ITERATING.

This base class method actually invokes prefire(), fire(), and postfire(), as described above, but a derived class may override the method to execute more efficient code.

Specified by:

iterate in interface Executable

Parameters:

count - The number of iterations to perform.

Returns:

NOT_READY, STOP_ITERATING, or COMPLETED.

Throws:

IllegalActionException - If iterating is not permitted, or if prefire(), fire(), or postfire() throw it.

newReceiver

public Receiver newReceiver()

Return a new receiver of a type compatible with this director. In this base class, this returns an instance of Mailbox.

Returns:

A new Mailbox.

postfire

public boolean postfire()
                 throws IllegalActionException

Return true if the director wishes to be scheduled for another iteration. This method is called by the container of this director to see whether the director wishes to execute anymore. It should not, in general, call postfire() on the contained actors.

In this base class, return the false if stop() has been called since preinitialize(), and true otherwise. Derived classes that override this method need to respect this semantics. The protected variable _stopRequested indicates whether stop() has been called.

Specified by:

postfire in interface Executable

Returns:

True to continue execution, and false otherwise.

Throws:

IllegalActionException - Not thrown in this base class.

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. It does not call prefire() on the contained actors. If this director is not at the top level of the hierarchy, and the current time of the enclosing model is greater than the current time of this director, then this base class updates current time to match that of the enclosing model.

In this base class, assume that the director is always ready to be fired, and so return true. Domain directors should probably override this method to provide domain-specific behavior. However, they should call super.prefire() if they wish to propagate time as done here.

Specified by:

prefire in interface Executable

Returns:

True.

Throws:

IllegalActionException - Not thrown in this base class.

preinitialize

public void preinitialize()
                   throws IllegalActionException

Validate the attributes and then invoke the preinitialize() methods of all its deeply contained actors. This method is invoked once per execution, before any iteration, and before the initialize() method. Time is not set during this stage. So preinitialize() method of actors should not make use of time. They should wait until the initialize phase of the execution.

This method also resets the protected variable _stopRequested to false, so if a derived class overrides this method, then it should also do that.

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

Specified by:

preinitialize in interface Initializable

Throws:

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

preinitialize

public void preinitialize(Actor actor)
                   throws IllegalActionException

Preintialize the actor. This method is used by directors that want to instrument calls to preinitialize. preinitialize() calls this method.

Parameters:

actor - The actor to be preinitialized.

Throws:

IllegalActionException - If thrown while the actor is being preinitialized.

See Also:

preinitialize()

removeInitializable

public void removeInitializable(Initializable initializable)

Remove the specified object from the list of objects whose preinitialize(), initialize(), and wrapup() methods should be invoked upon invocation of the corresponding methods of this object. If the specified object is not on the list, do nothing.

Specified by:

removeInitializable in interface Initializable

Parameters:

initializable - The object whose methods should no longer be invoked.

See Also:

addInitializable(Initializable), CompositeActor.removePiggyback(Executable)

requestInitialization

public void requestInitialization(Actor actor)

Queue an initialization request with the manager. The specified actor will be initialized at an appropriate time, between iterations, by calling its preinitialize() and initialize() methods. This method is called by CompositeActor when an actor sets its container to that composite actor. Typically, that will occur when a model is first constructed, and during the execute() method of a ChangeRequest. In this base class, the request is delegated to the manager. If there is no manager, or if the container is not an instance of CompositeActor, then do nothing.

Parameters:

actor - The actor to initialize.

setContainer

public void setContainer(NamedObj container)
                  throws IllegalActionException,
                         NameDuplicationException

Specify the container. If the specified container is an instance of CompositeActor, then this becomes the active director for that composite. Otherwise, this is an attribute like any other within the container. If the container is not in the same workspace as this director, throw an exception. If this director is already an attribute of the container, then this has the effect only of making it the active director. If this director already has a container, remove it from that container first. Otherwise, remove it from the directory of the workspace, if it is present. If the argument is null, then remove it from its container. This director is not added to the workspace directory, so calling this method with a null argument could result in this director being garbage collected.

If this method results in removing this director from a container that is a CompositeActor, then this director ceases to be the active director for that CompositeActor. Moreover, if the composite actor contains any other directors, then the most recently added of those directors becomes the active director.

This method is write-synchronized to the workspace and increments its version number.

Overrides:

setContainer in class Attribute

Parameters:

container - The proposed container.

Throws:

IllegalActionException - If the action would result in a recursive containment structure, or if this director and container are not in the same workspace, or if the protected method _checkContainer() throws it.

NameDuplicationException - If the name of this director collides with a name already in the container. This will not be thrown if the container argument is an instance of CompositeActor.

See Also:

Attribute.getContainer()

setCurrentTime

public void setCurrentTime(double newTime)
                    throws IllegalActionException

Deprecated. As of Ptolemy 4.1, replaced by setModelTime(ptolemy.actor.util.Time)

Set a new value to the current time of the model, where the new time must be no earlier than the current time. Derived classes will likely override this method to ensure that the time is valid.

Parameters:

newTime - The new current simulation time.

Throws:

IllegalActionException - If the new time is less than the current time returned by getCurrentTime().

See Also:

getCurrentTime()

setModelTime

public void setModelTime(Time newTime)
                  throws IllegalActionException

Set a new value to the current time of the model, where the new time must be no earlier than the current time. Derived classes will likely override this method to ensure that the time is valid.

Parameters:

newTime - The new current simulation time.

Throws:

IllegalActionException - If the new time is less than the current time returned by getCurrentTime().

See Also:

getModelTime()

stop

public void stop()

Request that the director cease execution altogether. This causes a call to stop() on all actors contained by the container of this director, and sets a flag so that the next call to postfire() returns false.

Specified by:

stop in interface Executable

stopFire

public void stopFire()

Request that execution of the current iteration stop. In this base class, the request is simply passed on to all actors that are deeply contained by the container of this director. For most domains, an iteration is a finite computation, so nothing further needs to be done here. However, for some process-oriented domains, the fire() method of the director is an unbounded computation. Those domains should override this method so that when it is called, it does whatever it needs to do to get the fire() method to return. Typically, it will set flags that will cause all executing threads to suspend. These domains should suspend execution in such a way that if the fire() method is called again, execution will resume at the point where it was suspended. However, they should not assume the fire() method will be called again. It is possible that the wrapup() method will be called next. If the container is not an instance of CompositeActor, then this method does nothing.

Specified by:

stopFire in interface Executable

suggestedModalModelDirectors

public java.lang.String[] suggestedModalModelDirectors()

Return an array of suggested directors to be used 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. This base class delegates to the executive director, if there is one, and otherwise returns an array with only one element, "ptolemy.domains.fsm.kernel.FSMDirector".

Returns:

An array of suggested directors to be used with ModalModel.

supportMultirateFiring

public boolean supportMultirateFiring()

Return a boolean to indicate whether a ModalModel under control of this director supports multirate firing. In this class, false is always returned. Subclasses may override this method to return true.

Returns:

False indicating a ModalModel under control of this director does not support multirate firing.

terminate

public void terminate()

Terminate any currently executing model with extreme prejudice. This method is not intended to be used as a normal route of stopping execution. To normally stop execution, call the finish() method instead. This method should be called only when execution fails to terminate by normal means due to certain kinds of programming errors (infinite loops, threading errors, etc.). There is no assurance that the topology will be in a consistent state after this method returns. The topology should probably be recreated before attempting any further operations.

This base class recursively calls terminate() on all actors deeply contained by the container of this director. Derived classes should override this method to release all resources in use and kill any sub-threads. Derived classes should not synchronize this method because it should execute as soon as possible. If the container is not an instance of CompositeActor, then this method does nothing.

Specified by:

terminate in interface Executable

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. The implementation in this base class transfers at most one token. Derived classes may override this method to transfer a domain-specific number of tokens.

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.

transferOutputs

public boolean transferOutputs(IOPort port)
                        throws IllegalActionException

Transfer data from an output port of the container to the ports it is connected to on the outside. The implementation in this base class transfers at most one token, but derived classes may transfer more than one token.

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

wrapup

public void wrapup()
            throws IllegalActionException

Invoke the wrapup() method of all the actors contained in the director's container. In this base class wrapup() is called on the associated actors in the order of their creation. If the container is not an instance of CompositeActor, then this method does nothing.

This method should be invoked once per execution. None of the other action methods should be invoked after it in the execution. This method is not synchronized on the workspace, so the caller should be.

Specified by:

wrapup in interface Initializable

Throws:

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

_description

protected java.lang.String _description(int detail,
                                        int indent,
                                        int bracket)
                                 throws IllegalActionException

Return a description of the object. The level of detail depends on the argument, which is an or-ing of the static final constants defined in the NamedObj class. Lines are indented according to to the level argument using the protected method _getIndentPrefix(). Zero, one or two brackets can be specified to surround the returned description. If one is specified it is the the leading bracket. This is used by derived classes that will append to the description. Those derived classes are responsible for the closing bracket. An argument other than 0, 1, or 2 is taken to be equivalent to 0. This method is read-synchronized on the workspace.

Overrides:

_description in class NamedObj

Parameters:

detail - The level of detail.

indent - The amount of indenting.

bracket - The number of surrounding brackets (0, 1, or 2).

Returns:

A description of the object.

Throws:

IllegalActionException

_fireContainerAt

protected Time _fireContainerAt(Time time)
                         throws IllegalActionException

Request a firing of the container of this director at the specified time and throw an exception if the executive director does not agree to do it at the requested time. If there is no executive director (this director is at the top level), then ignore the request. This is a convenience method provided because several directors need it.

Parameters:

time - The requested time.

Returns:

The time that the executive director indicates it will fire this director, or an instance of Time with value Double.NEGATIVE_INFINITY if there is no executive director.

Throws:

IllegalActionException - If the director does not agree to fire the actor at the specified time, or if there is no director.

_isEmbedded

protected boolean _isEmbedded()

Return true if this director is embedded inside an opaque composite actor contained by another composite actor.

Returns:

True if this directory is embedded inside an opaque composite actor contained by another composite actor.

_isTopLevel

protected boolean _isTopLevel()

Return true if this is a top-level director. Parts of this method is read synchronized on the workspace.

Returns:

True if this director is at the top-level.

_transferInputs

protected boolean _transferInputs(IOPort port)
                           throws IllegalActionException

Transfer at most one data token from the given input port of the container to the ports it is connected to on the inside. This method delegates the operation to the IOPort, so that the subclass of IOPort, TypedIOPort, can override this method to perform run-time type conversion.

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.

See Also:

IOPort.transferInputs()

_transferOutputs

protected boolean _transferOutputs(IOPort port)
                            throws IllegalActionException

Transfer at most one data token from the given output port of the container to the ports it is connected to on the outside.

Parameters:

port - The port to transfer tokens from.

Returns:

True if the port has an inside token that was successfully transferred. Otherwise return false (or throw an exception).

Throws:

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

_addIcon

private void _addIcon()

_createReceivers

private void _createReceivers()
                       throws IllegalActionException

Create receivers for all contained actors.

Throws:

IllegalActionException - If any port of a contained actor throws it when its receivers are created.

See Also:

Actor.createReceivers()

_initializeParameters

private void _initializeParameters()