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.
@author Mudit Goel, Edward A. Lee, Lukito Muliadi, Steve Neuendorffer, John Reekie
@version $Id: Director.java 70402 2014-10-23 00:52:20Z cxh $
@since Ptolemy II 0.2
@Pt.ProposedRating Green (eal)
@Pt.AcceptedRating Yellow (neuendor)
*/
public class Director extends Attribute implements Executable {
/** 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.
* @exception NameDuplicationException If construction of Time objects fails.
* @exception IllegalActionException If construction of Time objects fails.
*/
public Director() throws IllegalActionException, NameDuplicationException {
super();
_addIcon();
_initializeParameters();
}
/** 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.
*
* @param container The container.
* @param name The name of this director.
* @exception 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.
* @exception NameDuplicationException If the container already contains
* an entity with the specified name.
*/
public Director(CompositeEntity container, String name)
throws IllegalActionException, NameDuplicationException {
super(container, name);
_addIcon();
_initializeParameters();
}
/** 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.
* @param workspace The workspace of this object.
* @exception NameDuplicationException If construction of Time objects fails.
* @exception IllegalActionException If construction of Time objects fails.
*/
public Director(Workspace workspace) throws IllegalActionException,
NameDuplicationException {
super(workspace);
_addIcon();
_initializeParameters();
}
///////////////////////////////////////////////////////////////////
//// public parameters ////
/** The clock that keeps track of current time of the model. */
public LocalClock localClock;
/** The local time of model when this director is initialized.
* By default, this is blank, which
* indicates that the start time is the current time of the enclosing
* director when initialize() is invoked, or 0.0 if there is no
* enclosing director. This can be set to a double value to explicitly
* specify a start time.
* Note that if startTime is given a value
* that is different from the start time of the enclosing
* director, then local time may be ahead of or behind
* environment time during execution.
* Also note that some directors do not advance time (including
* PN and Rendezvous, for example), in which case, local time remains
* at the start time value throughout the execution.
*/
public Parameter startTime;
/** The stop time of the model. By default, this is blank, which
* means that no stop time is specified. If a stop time is specified,
* it must be a double, and when local time meets or exceeds the
* stop time, then {@link #postfire()} returns false.
*/
public Parameter stopTime;
///////////////////////////////////////////////////////////////////
//// public methods ////
/** Add the specified object to the set of objects whose
* preinitialize(), initialize(), and wrapup()
* methods should be invoked upon invocation of the corresponding
* methods of this object.
* @param initializable The object whose methods should be invoked.
* @see #removeInitializable(Initializable)
* @see ptolemy.actor.CompositeActor#addPiggyback(Executable)
*/
@Override
public void addInitializable(Initializable initializable) {
if (_initializables == null) {
_initializables = new LinkedHashSet
* 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.
*
* @exception IllegalActionException If any called method of one
* of the associated actors throws it.
*/
@Override
public void fire() throws IllegalActionException {
if (_debugging) {
_debug("Director: Called fire().");
}
Nameable container = getContainer();
if (container instanceof CompositeActor) {
Iterator actors = ((CompositeActor) container).deepEntityList()
.iterator();
int iterationCount = 1;
while (actors.hasNext() && !_stopRequested) {
Actor actor = (Actor) actors.next();
if (_debugging) {
_debug(new FiringEvent(this, actor,
FiringEvent.BEFORE_ITERATE, iterationCount));
}
if (actor.iterate(1) == Executable.STOP_ITERATING) {
if (_debugging) {
_debug("Actor requests halt: "
+ ((Nameable) actor).getFullName());
}
break;
}
if (_debugging) {
_debug(new FiringEvent(this, actor,
FiringEvent.AFTER_ITERATE, iterationCount));
}
}
}
}
/** 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 {@link #fireAt(Actor, Time)} method.
*
* @param actor The actor scheduled to be fired.
* @param time The scheduled time.
* @exception IllegalActionException If the operation is not
* permissible (e.g. the given time is in the past).
* @deprecated Instead of using double as time argument, use a
* time object instead. As of Ptolemy 4.1, replaced by
* {@link #fireAt(Actor, Time)}
*/
@Deprecated
public void fireAt(Actor actor, double time) throws IllegalActionException {
fireAt(actor, new Time(this, time));
}
/** Request a firing of the given actor at the given model
* time. This base class ignores the request and returns a Time
* with value equal to the current time, 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, adjusted by the current offset and drift of the local clock.
* It does this by delegating to {@link #fireContainerAt(Time, int)}
* with the microstep argument set to 1.
*
* 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.
*
* Note to authors of subclasses: Usually you should not
* override this method, but rather override
* {@link #fireAt(Actor, Time, int)}. However, we cannot make
* this method final because occasionally a domain will change the
* default starting microstep. E.g., DE does this.
* @param actor The actor scheduled to be fired.
* @param time The requested time.
* @return An instance of Time with the current time value, 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.
* @see #fireAtCurrentTime(Actor)
* @exception IllegalActionException If there is an executive director
* and it throws it. Derived classes may choose to throw this
* exception for other reasons.
*/
public Time fireAt(Actor actor, Time time) throws IllegalActionException {
// Unless the actor specifically requests a particular microstep,
// we assume it knows nothing about microsteps. We use microstep 1
// as the default, since this is the default for discrete events.
// The Continuous domain will specifically request a firing at
// microstep 0.
return fireAt(actor, time, 1);
}
/** Request a firing of the given actor at the given model
* time with the given microstep. This method behaves exactly
* like {@link #fireAt(Actor, Time)}, except that it also
* passes up to the executive director the microstep, if there
* is one.
* This default implementation just delegates to
* {@link #fireContainerAt(Time, int)}
* @param actor The actor scheduled to be fired.
* @param time The requested time.
* @param microstep The requested microstep.
* @return An instance of Time with the current time value, 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.
* @see #fireAtCurrentTime(Actor)
* @see #fireContainerAt(Time)
* @exception IllegalActionException If there is an executive director
* and it throws it. Derived classes may choose to throw this
* exception for other reasons.
*/
public Time fireAt(Actor actor, Time time, int microstep)
throws IllegalActionException {
return fireContainerAt(time, microstep);
}
/** 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.
* @param actor The actor to be fired.
* @return The time at which the specified actor will be fired,
* which in this case is whatever fireAt() returns.
* @see #fireAt(Actor, Time)
* @exception IllegalActionException If this method is called
* before the model is running.
*/
public Time fireAtCurrentTime(Actor actor) throws IllegalActionException {
return fireAt(actor, getModelTime());
}
/** 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.
* The requested microstep will be zero.
* @param time The requested time.
* @return The time that the executive director indicates it will fire this
* director, or an instance of Time with value equal to current time
* if there is no executive director.
* @exception IllegalActionException If the director does not
* agree to fire the actor at the specified time, or if there
* is no director.
*/
public Time fireContainerAt(Time time) throws IllegalActionException {
return fireContainerAt(time, _defaultMicrostep);
}
/** Request a firing of the container of this director at the specified time,
* adjusted by the current offset and drift of the local clock,
* and the specified microstep.
* 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 and return
* a Time with value equal to the current time.
* The microstep argument is used by directors that implement
* {@link SuperdenseTimeDirector}.
* @param time The requested time.
* @param microstep The requested microstep.
* @return The time that the executive director indicates it will fire this
* director, or an instance of Time with value equal to current time
* if there is no executive director.
* @exception IllegalActionException If the director does not
* agree to fire the actor at the specified time, or if there
* is no director.
*/
public Time fireContainerAt(Time time, int microstep)
throws IllegalActionException {
Actor container = (Actor) getContainer();
// Some composites, such as RunCompositeActor want to be treated
// as if they are at the top level even though they have an executive
// director, so be sure to check _isTopLevel().
if (container != null && !_isTopLevel()) {
Director director = container.getExecutiveDirector();
if (director != null) {
if (_debugging) {
_debug("**** Requesting that enclosing director refire me at "
+ time + " with microstep " + microstep);
}
// Translate the local time into an environment time.
Time environmentTime = localClock
.getEnvironmentTimeForLocalTime(time);
Time result = director.fireAt(container, environmentTime,
microstep);
if (!result.equals(environmentTime)) {
throw new IllegalActionException(this,
"Timing incompatibility error: "
+ director.getName()
+ " is unable to fire "
+ container.getName()
+ " at the requested time: " + time
+ ". It responds it will fire it at: "
+ result + ".");
}
// Translate the response from the environment into a local time.
return localClock.getLocalTimeForEnvironmentTime(result);
}
}
return localClock.getLocalTime();
}
/** Return true if the next actor in the model governed by this director
* can be scheduled. The base class always returns true, but derived
* classes might override this.
* @return True if next actor to be fired can be scheduled.
* @exception IllegalActionException not thrown here.
*/
public boolean scheduleContainedActors() throws IllegalActionException {
return true;
}
/** Return a causality interface for the composite actor that
* contains this director. This base class returns an
* instance of {@link CausalityInterfaceForComposites}, but
* subclasses may override this to return a domain-specific
* causality interface.
* @return A representation of the dependencies between input ports
* and output ports of the container.
*/
public CausalityInterface getCausalityInterface() {
return new CausalityInterfaceForComposites((Actor) getContainer(),
defaultDependency());
}
/** 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.
*
* @return The current time value.
* @deprecated As of Ptolemy II 4.1, replaced by
* {@link #getModelTime()}
* @see #setCurrentTime(double)
*/
@Deprecated
public double getCurrentTime() {
return getModelTime().getDoubleValue();
}
/** Compute the deadline for an actor firing. In this base class, the deadline
* is set to the maximum value.
* @param actor The actor.
* @param timestamp The timestamp of the event that triggered the firing.
* @return The deadline.
* @exception IllegalActionException Thrown in subclasses.
*/
public Time getDeadline(NamedObj actor, Time timestamp)
throws IllegalActionException {
return Time.POSITIVE_INFINITY;
}
/** Get current environment time.
* This is the current time of the enclosing executive
* director, if there is one, and null otherwise.
* @return Environment time or null if the associated director is the top level director.
*/
public Time getEnvironmentTime() {
if (getContainer() instanceof Actor) {
Actor container = (Actor) getContainer();
if (container != null && container.getContainer() != null) {
Director executiveDirector = container.getExecutiveDirector();
// Some composites, such as RunCompositeActor want to be treated
// as if they are at the top level even though they have an executive
// director, so be sure to check _isTopLevel().
if (executiveDirector != null && !_isTopLevel()) {
return executiveDirector.getModelTime();
}
}
}
return localClock.getLocalTime();
}
/** 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.
* @return the error tolerance.
*/
public double getErrorTolerance() {
return 0.0;
}
/** 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.
* @return The time of the top-level director in the model.
* @exception IllegalActionException If the top level is not an Actor.
*/
public Time getGlobalTime() throws IllegalActionException {
NamedObj toplevel = toplevel();
if (!(toplevel instanceof Actor)) {
throw new IllegalActionException(this,
"Cannot get a global time because the top level is not an actor."
+ " It is " + toplevel);
}
return ((Actor) toplevel).getDirector().getModelTime();
}
/** 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.
* @return The time of the next iteration.
* @exception IllegalActionException If time objects cannot be created.
* @see #getModelTime()
*/
public Time getModelNextIterationTime() throws IllegalActionException {
NamedObj container = getContainer();
// NOTE: the container may not be a composite actor.
// For example, the container may be an entity as a library,
// where the director is already at the top level.
if (container instanceof CompositeActor) {
Director executiveDirector = ((CompositeActor) container)
.getExecutiveDirector();
// Some composites, such as RunCompositeActor want to be treated
// as if they are at the top level even though they have an executive
// director, so be sure to check _isTopLevel().
if (executiveDirector != null && !_isTopLevel()) {
return executiveDirector.getModelNextIterationTime();
}
}
return getModelTime();
}
/** Return the start time parameter value, if it has been explicitly
* set. Otherwise, return the current time of the enclosing director,
* if there is one, and return a Time with value 0.0 otherwise.
* @return the start time parameter value.
* @exception IllegalActionException If the executive director throws it.
*/
public final Time getModelStartTime() throws IllegalActionException {
// This method is final for performance reason.
if (_startTime == null) {
if (isEmbedded() && getContainer() instanceof Actor) {
// The previous implementation assumes this method is only called
// during initialize. This is not a valid assumption.
// It is called when attributeChanged() on startTime, and also
// when cloning.
Director executiveDirector = ((Actor) getContainer())
.getExecutiveDirector();
// Some composites, such as RunCompositeActor want to be treated
// as if they are at the top level even though they have an executive
// director, so be sure to check _isTopLevel().
if (executiveDirector != null && !_isTopLevel()) {
return executiveDirector.getModelTime();
} else {
return _zeroTime;
}
} else {
return _zeroTime;
}
}
return _startTime;
}
/** Return the stop time parameter value, if it has been set,
* and otherwise, return a time with value Double.POSITIVE_INFINITY.
* @return the stop time parameter value.
*/
public final Time getModelStopTime() {
if (_stopTime != null) {
return _stopTime;
}
return Time.POSITIVE_INFINITY;
}
/** 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.
*
* @return The current time.
* @see #setModelTime(Time)
*/
public Time getModelTime() {
return localClock.getLocalTime();
}
/** 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.
* @return The time of the next iteration.
* @exception IllegalActionException If Time objects cannot be created.
* @deprecated As of Ptolemy II 4.1, replaced by
* {@link #getModelNextIterationTime}
*/
@Deprecated
public double getNextIterationTime() throws IllegalActionException {
return getModelNextIterationTime().getDoubleValue();
}
/** 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.
* @return The start time of the model.
* @deprecated As of Ptolemy II 4.1, replaced by
* {@link #getModelStartTime}
* @exception IllegalActionException If the specified start time
* is invalid.
*/
@Deprecated
public double getStartTime() throws IllegalActionException {
return 0.0;
}
/** 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.
* @return The stop time of the model.
* @deprecated As of Ptolemy II 4.1, replaced by
* {@link #getModelStopTime}
* @exception IllegalActionException If the specified stop time
* is invalid.
*/
@Deprecated
public double getStopTime() throws IllegalActionException {
return getModelStopTime().getDoubleValue();
}
/** 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.
* @return The time resolution of the model.
* @see #setTimeResolution(double)
*/
public final double getTimeResolution() {
// This method is final for performance reason.
return localClock.getTimeResolution();
}
/** 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.
* @return True if the director assumes and exports strict actor semantics.
*/
public boolean implementsStrictActorSemantics() {
return false;
}
/** 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.
*
* @exception IllegalActionException If the initialize() method of
* one of the associated actors throws it.
*/
@Override
public void initialize() throws IllegalActionException {
// Note that the inner director in gt.TransformationRule
// does not call super.initialize(), so changes made to this
// method may apply there.
if (_debugging) {
_debug("Called initialize().");
}
// First invoke initializable methods.
if (_initializables != null) {
for (Initializable initializable : _initializables) {
initializable.initialize();
}
}
_actorsFinishedExecution = new HashSet();
// Reset the flag that causes postfire() to return false.
_finishRequested = false;
localClock.resetLocalTime(getModelStartTime());
localClock.start();
if (_nextScheduleTime != null) {
_nextScheduleTime.clear();
}
_tokenSentToCommunicationAspect = false;
// Initialize the contained actors.
Nameable container = getContainer();
if (container instanceof CompositeActor) {
Iterator actors = ((CompositeActor) container).deepEntityList()
.iterator();
while (actors.hasNext() && !_stopRequested) {
Actor actor = (Actor) actors.next();
if (_debugging) {
_debug("Invoking initialize(): ",
((NamedObj) actor).getFullName());
}
initialize(actor);
}
}
}
/** 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.
* @param actor The actor that is to be initialized.
* @exception IllegalActionException If the actor is not
* acceptable to the domain. Not thrown in this base class.
*/
public void initialize(Actor actor) throws IllegalActionException {
// FIXME: Note that ProcessDirector does *not* invoke this
// method, so changes made here might apply to
// ProcessDirector.initialize(Actor).
if (_debugging) {
_debug("Initializing actor: " + ((Nameable) actor).getFullName()
+ ".");
}
actor.initialize();
if (getExecutionAspect((NamedObj) actor) != null) {
_aspectsPresent = true;
}
}
/** Resume the execution of an actor that was previously blocked because
* it didn't have all the resources it needed for execution. This method
* is called by {@link ActorExecutionAspect} actors.
*
* In this base class, the implementation is empty. Derived directors
* should override this method to handle resuming of actor execution.
* @param actor The actor that resumes execution.
* @exception IllegalActionException Not thrown here but in derived classes.
*/
public void resumeActor(NamedObj actor) throws IllegalActionException {
}
/** 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.
*/
public void invalidateResolvedTypes() {
Nameable container = getContainer();
if (container instanceof CompositeActor) {
Manager manager = ((CompositeActor) container).getManager();
if (manager != null) {
manager.invalidateResolvedTypes();
}
}
}
/** 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.
*/
public void invalidateSchedule() {
}
/** Return true if this director is embedded inside an opaque composite
* actor contained by another composite actor. Note that some classes,
* such as RunCompositeActor, may return false even if they are actually
* embedded, but they want to be treated as if they were not.
* @return True if this directory is embedded inside an opaque composite
* actor contained by another composite actor.
* @see #setEmbedded(boolean)
*/
public final boolean isEmbedded() {
return !_isTopLevel();
}
/** 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.
*
* @return False.
*/
@Override
public boolean isFireFunctional() {
return false;
}
/** 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.
*
* @return True.
* @exception IllegalActionException Thrown by subclass.
*/
@Override
public boolean isStrict() throws IllegalActionException {
return true;
}
/** Return true if stop has been requested.
* @return True if stop() has been called.
* @see #stop()
*/
public boolean isStopRequested() {
return _stopRequested;
}
/** 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.
*
* @param count The number of iterations to perform.
* @return NOT_READY, STOP_ITERATING, or COMPLETED.
* @exception IllegalActionException If iterating is not
* permitted, or if prefire(), fire(), or postfire() throw it.
*/
@Override
public int iterate(int count) throws IllegalActionException {
int n = 0;
while (n++ < count && !_stopRequested) {
if (prefire()) {
fire();
if (!postfire()) {
return Executable.STOP_ITERATING;
}
} else {
return Executable.NOT_READY;
}
}
if (_stopRequested) {
return Executable.STOP_ITERATING;
} else {
return Executable.COMPLETED;
}
}
/** Return the object to use to obtain a mutex lock on this director.
* This base class returns this director itself, but subclasses may
* return something else.
* @return An object to use to obtain a lock on this director.
*/
public Object mutexLockObject() {
return this;
}
/** Return a new receiver of a type compatible with this director.
* In this base class, this returns an instance of Mailbox.
* @return A new Mailbox.
*/
public Receiver newReceiver() {
return new Mailbox();
}
/** Notify this director that a token was sent to a communication
* aspect. Some directors need to perform specific actions but the
* base class just sets a boolean flag.
*/
public void notifyTokenSentToCommunicationAspect() {
_tokenSentToCommunicationAspect = true;
}
/** 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.
*
* @return True to continue execution, and false otherwise.
* @exception IllegalActionException Not thrown in this base class.
*/
@Override
public boolean postfire() throws IllegalActionException {
if (_debugging) {
_debug("Director: Called postfire().");
}
return !_stopRequested && !_finishRequested;
}
/** 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,
* then this base class synchronizes to environment time, making
* any necessary adjustments for drift or offset of the local clock.
*
* 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.
*
* @return True.
* @exception IllegalActionException Not thrown in this base class.
*/
@Override
public boolean prefire() throws IllegalActionException {
// FIXME: Note that ProcessDirector does *not*
// invoke this method, so changes made here might
// apply to ProcessDirector.prefire().
if (_debugging) {
_debug("Director: Called prefire().");
}
Time modifiedTime = _consultTimeRegulators(localClock
.getLocalTimeForCurrentEnvironmentTime());
setModelTime(modifiedTime);
if (_debugging) {
_debug("-- Setting current time to " + getModelTime());
}
return true;
}
/** 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.
*
* @exception IllegalActionException If the preinitialize() method of
* one of the associated actors throws it.
*/
@Override
public void preinitialize() throws IllegalActionException {
// Note that the inner director in gt.TransformationRule
// does not call super.preinitialize(), so changes made to this
// method may apply there.
if (_debugging) {
_debug(getFullName(), "Preinitializing ...");
}
// Support old models that set time resolution in director.
Attribute timeResolution = getAttribute("timeResolution");
if (timeResolution != null) {
double timeResolutionDouble = ((DoubleToken) ((Parameter) timeResolution)
.getToken()).doubleValue();
try {
timeResolution.setContainer(null);
} catch (NameDuplicationException e) {
// Can't happen.
e.printStackTrace();
}
localClock.globalTimeResolution.setToken("" + timeResolutionDouble);
}
_zeroTime = new Time(this, 0.0);
localClock.initialize();
// First invoke initializable methods.
if (_initializables != null) {
for (Initializable initializable : _initializables) {
initializable.preinitialize();
}
}
// validate all settable attributes.
Iterator attributes = attributeList(Settable.class).iterator();
while (attributes.hasNext()) {
Settable attribute = (Settable) attributes.next();
attribute.validate();
}
// In case the preinitialize() method of any actor
// access current time, set the start time. This is required
// for instance in DDF.
// The following will be repeated in initialize().
localClock.resetLocalTime(getModelStartTime());
localClock.start();
// preinitialize protected variables.
_stopRequested = false;
_finishRequested = false;
Nameable container = getContainer();
// Preinitialize all the contained actors.
if (container instanceof CompositeActor) {
// Populate any LazyTypedComposites.
// Needed by $PTII/ptolemy/cg/lib/test/auto/ModularCodeGen4.xml
Iterator entities = ((CompositeActor) toplevel()).entityList(
LazyComposite.class).iterator();
while (entities.hasNext()) {
// LazyTypedCompositeActor implements ptolemy.kernel.util.LazyComposite,
// which has a populate() method. We refer to the interface so
// as to avoid a dependency between Director and LazyTypedCompositeActor.
LazyComposite lazyComposite = (LazyComposite) entities.next();
lazyComposite.populate();
}
// Preinitialize all the contained actors.
Iterator actors = ((CompositeActor) container).deepEntityList()
.iterator();
while (actors.hasNext()) {
Actor actor = (Actor) actors.next();
if (_debugging) {
_debug("Invoking preinitialize(): ",
((NamedObj) actor).getFullName());
}
preinitialize(actor);
}
// Don't need to create receivers if the workspace hasn't changed since the last run.
// Note that we have to use the version recorded by the Manager on the last
// completion of preinitializeAndResolveTypes() because otherwise, if there
// are multiple directors, then the workspace version will always have changed
// since the last run, since creatingReceivers itself changes it.
Manager manager = ((Actor) container).getManager();
if (manager == null
|| manager.getPreinitializeVersion() != workspace()
.getVersion()) {
// This increments the workspace version.
_createReceivers();
}
}
_aspectsPresent = false;
_executionAspects = new ArrayList
* 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.
* @param container The proposed container.
* @exception 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.
* @exception 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.
*/
@Override
public void setContainer(NamedObj container) throws IllegalActionException,
NameDuplicationException {
try {
_workspace.getWriteAccess();
Nameable oldContainer = getContainer();
if (oldContainer instanceof CompositeActor
&& oldContainer != container) {
// Need to remove this director as the active one of the
// old container. Search for another director contained
// by the composite. If it contains more than one,
// use the most recently added one.
Director previous = null;
CompositeActor castContainer = (CompositeActor) oldContainer;
Iterator directors = castContainer.attributeList(
Director.class).iterator();
while (directors.hasNext()) {
Director altDirector = (Director) directors.next();
// Since we haven't yet removed this director, we have
// to be sure to not just set it to the active
// director again.
if (altDirector != this) {
previous = altDirector;
}
}
castContainer._setDirector(previous);
}
super.setContainer(container);
if (container instanceof CompositeActor) {
// Set cached value in composite actor.
((CompositeActor) container)._setDirector(this);
}
} finally {
_workspace.doneWriting();
}
}
/** 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.
*
* @param newTime The new current simulation time.
* @exception IllegalActionException If the new time is less than
* the current time returned by getCurrentTime().
* @deprecated As of Ptolemy 4.1, replaced by
* {@link #setModelTime}
* @see #getCurrentTime()
*/
@Deprecated
public void setCurrentTime(double newTime) throws IllegalActionException {
setModelTime(new Time(this, newTime));
}
/** With a false argument, force this director to behave as if it is
* a top-level director even if it is not. This is used by composite
* actors such as RunCompositeActor that need for the inside director
* to behave as if it is running at the top level.
* @param force False to force this director to behave as if it were
* not embedded.
* @see #isEmbedded()
*/
public final void setEmbedded(boolean force) {
if (!force) {
_notEmbeddedForced = true;
}
}
/** Set a new value to the current time of the model.
* @param newTime The new current simulation time.
* @exception IllegalActionException If the new time is less than
* the current time returned by getCurrentTime().
* @see #getModelTime()
*/
public void setModelTime(Time newTime) throws IllegalActionException {
localClock.setLocalTime(newTime);
}
/** Set time resolution.
* @param timeResolution The new time resolution.
* @see #getTimeResolution()
*/
public void setTimeResolution(double timeResolution) {
localClock.setTimeResolution(timeResolution);
}
/** 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.
*
* The stop() method requests immediate stopping. To give
* determinate stopping, call finish() so that the
* current iteration is completed. In multithreaded domains, Director.stopFire() is called
* to request that all actors conclude ongoing firings.
* 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.
* 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.
*
* @exception IllegalActionException If the wrapup() method of
* one of the associated actors throws it.
*/
@Override
public void wrapup() throws IllegalActionException {
// FIXME: Note that ProcessDirector and the inner director in
// gt TransformationRule do not invoke this method, so changes
// made here might apply to ProcessDirector.wrapup().
if (_debugging) {
_debug("Director: Called wrapup().");
}
// First invoke initializable methods.
if (_initializables != null) {
for (Initializable initializable : _initializables) {
initializable.wrapup();
}
}
Nameable container = getContainer();
if (container instanceof CompositeActor) {
Iterator actors = ((CompositeActor) container).deepEntityList()
.iterator();
while (actors.hasNext()) {
Actor actor = (Actor) actors.next();
actor.wrapup();
}
}
}
///////////////////////////////////////////////////////////////////
//// protected methods ////
/** Return true if the actor finished execution.
* @param actor The actor.
* @return True if the actor finished execution.
*/
protected boolean _actorFinished(NamedObj actor) {
return _aspectForActor.get(actor) != null
&& _aspectForActor.get(actor).lastScheduledActorFinished();
}
/** Consult all attributes contained by the container of this director
* that implement the {@link TimeRegulator} interface, if any, and return the
* smallest time returned by those regulators. If there are no such
* attributes, return the proposedTime argument.
* @param proposedTime The time proposed.
* @return The smallest time returned by a TimeRegulator, or the
* proposedTime if none.
* @exception IllegalActionException If a time regulator throws it.
*/
protected Time _consultTimeRegulators(Time proposedTime)
throws IllegalActionException {
Time returnValue = proposedTime;
List