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.
@author Mudit Goel, Edward A. Lee, Lukito Muliadi, Steve Neuendorffer, John Reekie
@version $Id: Director.java,v 1.266 2007/12/07 06:25:19 cxh Exp $
@since Ptolemy II 0.2
@Pt.ProposedRating Green (eal)
@Pt.AcceptedRating Yellow (neuendor)