|
||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||
java.lang.Objectptolemy.kernel.util.NamedObj
ptolemy.kernel.util.Attribute
ptolemy.actor.Director
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.
| Yellow (neuendor) |
| Green (eal) |
| Nested Class Summary |
| Nested classes inherited from class ptolemy.kernel.util.NamedObj |
NamedObj.ContainedObjectsIterator |
| Field Summary | |
protected double |
_currentTime
The current time of the model. |
protected boolean |
_stopRequested
Indicator that a stop has been requested by a call to stop(). |
| Fields inherited from class ptolemy.kernel.util.NamedObj |
_changeListeners, _changeLock, _changeRequests, _debugging, _debugListeners, _elementName, _isPersistent, _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 | |
protected java.lang.String |
_description(int detail,
int indent,
int bracket)
Return a description of the object. |
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 |
_writeAccessRequired()
Return true if this director requires write access on the workspace during execution. |
boolean |
domainPolymorphicTransferInputs(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. |
boolean |
domainPolymorphicTransferOutputs(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 |
fire()
Invoke an iteration on all of the deeply contained actors of the container of this director. |
void |
fireAt(Actor actor,
double time)
Schedule a firing of the given actor at the given absolute time. |
void |
fireAtCurrentTime(Actor actor)
Schedule a firing of the given actor as soon as possible. |
double |
getCurrentTime()
Return the current time of the model being executed by this director. |
double |
getNextIterationTime()
Return the next time of interest in the model being executed by this director. |
double |
getTimeResolution()
Get the time resolution of the model. |
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. |
int |
iterate(int count)
Invoke a specified number of iterations of this director. |
boolean |
needWriteAccess()
Return true if this director, or any of its contained directors requires write access on the workspace during execution. |
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 |
requestInitialization(Actor actor)
Queue an initialization request with the manager. |
void |
setContainer(NamedObj container)
Specify the container. |
void |
setCurrentTime(double 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 |
setTimeResolution(double timeResolution)
Set the time resolution of the model. |
void |
stop()
Request that the director cease execution altogether. |
void |
stopFire()
Request that execution of the current iteration stop. |
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 |
_getContainedObject, _propagateExistence, clone, getContainer, setName |
| Methods inherited from class java.lang.Object |
equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait |
| Field Detail |
protected double _currentTime
protected boolean _stopRequested
| Constructor Detail |
public Director()
public Director(Workspace workspace)
workspace - The workspace of this object.
public Director(CompositeEntity container,
java.lang.String name)
throws IllegalActionException,
NameDuplicationException
container - The container.name - The name of this director.
IllegalActionException - If the name has a period in it, or
the director is not compatible with the specified container.
NameDuplicationException - If the container already contains
an entity with the specified name.| Method Detail |
public boolean domainPolymorphicTransferInputs(IOPort port)
throws IllegalActionException
port - The port to transfer tokens from.
IllegalActionException - If the port is not an opaque
input port.IOPort.transferInputs()
public boolean domainPolymorphicTransferOutputs(IOPort port)
throws IllegalActionException
port - The port to transfer tokens from.
IllegalActionException - If the port is not an opaque
output port.IOPort.transferOutputs()
public void fire()
throws IllegalActionException
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.
fire in interface ExecutableIllegalActionException - If any called method of one
of the associated actors throws it.
public void fireAt(Actor actor,
double time)
throws IllegalActionException
Note that this method is not made abstract to facilitate the use of the test suite.
actor - The actor scheduled to be fired.time - The scheduled time.
IllegalActionException - If the operation is not
permissible (e.g. the given time is in the past).
public void fireAtCurrentTime(Actor actor)
throws IllegalActionException
Note that this method is not made abstract to facilitate the use of the test suite.
actor - The actor to be fired.
IllegalActionException - If this method is called
before the model is running.public double getCurrentTime()
public double getNextIterationTime()
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.
public double getTimeResolution()
public void initialize()
throws IllegalActionException
initialize in interface ExecutableIllegalActionException - If the initialize() method of
one of the associated actors throws it.
public void initialize(Actor actor)
throws IllegalActionException
IllegalActionException - If the actor is not
acceptable to the domain. Not thrown in this base class.public void invalidateResolvedTypes()
public void invalidateSchedule()
public int iterate(int count)
throws IllegalActionException
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.
iterate in interface Executablecount - The number of iterations to perform.
IllegalActionException - If iterating is not
permitted, or if prefire(), fire(), or postfire() throw it.public final boolean needWriteAccess()
This method is called on the top level director by the manager at the start of an execution. If it returns false (indicating that none of the directors in the model need write access on the workspace), then the manager will set the workspace to be read only during each toplevel iteration of the model. Note that mutations can still occur, but they can only be performed by the manager.
InvalidStateException - If the director does not have
a container, or the container is not an instance of CompositeActor.public Receiver newReceiver()
public boolean postfire()
throws IllegalActionException
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.
postfire in interface ExecutableIllegalActionException - Not thrown in this base class.
public boolean prefire()
throws IllegalActionException
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.
prefire in interface ExecutableIllegalActionException - Not thrown in this base class.
public void preinitialize()
throws IllegalActionException
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.
preinitialize in interface ExecutableIllegalActionException - If the preinitialize() method of
one of the associated actors throws it.public void requestInitialization(Actor actor)
actor - The actor to initialize.
public void setContainer(NamedObj container)
throws IllegalActionException,
NameDuplicationException
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.
setContainer in class Attributecontainer - The proposed container.
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.
public void setCurrentTime(double newTime)
throws IllegalActionException
newTime - The new current simulation time.
IllegalActionException - If the new time is less than
the current time returned by getCurrentTime().public void setTimeResolution(double timeResolution)
timeResolution - The new time resolution.public void stop()
stop in interface Executablepublic void stopFire()
stopFire in interface Executablepublic void terminate()
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.
terminate in interface Executable
public boolean transferInputs(IOPort port)
throws IllegalActionException
port - The port to transfer tokens from.
IllegalActionException - If the port is not an opaque
input port.IOPort.transferInputs()
public boolean transferOutputs(IOPort port)
throws IllegalActionException
port - The port to transfer tokens from.
IllegalActionException - If the port is not an opaque
output port.IOPort.transferOutputs()
public void wrapup()
throws IllegalActionException
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.
wrapup in interface ExecutableIllegalActionException - If the wrapup() method of
one of the associated actors throws it.
protected java.lang.String _description(int detail,
int indent,
int bracket)
_description in class NamedObjdetail - The level of detail.indent - The amount of indenting.bracket - The number of surrounding brackets (0, 1, or 2).
protected boolean _isEmbedded()
protected boolean _isTopLevel()
protected boolean _writeAccessRequired()
In this base class, we assume that write access is required and always return true. This method should probably be overridden by derived classes.
|
||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||