
Manager |
ptolemy.actor.Manager |
A Manager governs the execution of a model in a domain-independent way.
Its methods are designed to be called by a GUI, an applet, a command-line
interface, or the top-level code of an application. The manager can
execute the model in the calling thread or in a separate thread.
The latter is useful when the caller wishes to remain live during
the execution of the model.
There are three methods that can be used to start execution of a
system attached to the manager. The execute() method is the most
basic way to execute a model. The model will be executed
synchronously, meaning that the execute() method will return
when execution has completed. Any exceptions that occur will be
thrown by the execute method to the calling thread, and will not be
reported to any execution listeners. The run() method also initiates
synchronous execution of a model, but additionally catches all
exceptions and passes them to the notifyListenersOfException() method
without throwing them to the calling thread. The startRun()
method, unlike the previous two techniques, begins asynchronous
execution of a model. This method starts a new thread for execution
of the model and then returns immediately. Exceptions are reported
using the notifyListenersOfException() method.
In addition, execution can be manually driven, one phase at a
time, using the methods initialize(), iterate() and wrapup(). This is
most useful for testing purposes. For example, a type system check
only needs to get the resolved types, which are found during
initialize, so the test can avoid actually executing the system.
Also, when testing mutations, the model can be examined after each
toplevel iteration to ensure the proper behavior.
A manager provides services for cleanly handling changes to the
topology. These include such changes as adding or removing an entity,
port, or relation, creating or destroying a link, and changing the
value or type of a parameter. Collectively, such changes are called
mutations. Usually, mutations cannot safely occur at arbitrary
points in the execution of a model. Models can queue mutations with
any object in the hierarchy or with the manager using the
requestChange() method. An object in the hierarchy simply delegates
the request to its container, so the request propagates up the
hierarchy until it gets to the top level composite actor, which
delegates to the manager, which performs the change at the earliest
opportunity. In this implementation of Manager, the changes are
executed between iterations.
A service is also provided whereby an object can be registered
with the composite actor as a change listener. A change listener is
informed when mutations that are requested via requestChange() are
executed successfully, or when they fail with an exception.
Manager can optimize the performance of an execution by making the
workspace write protected during an iteration, if all relevant
directors permit this. This removes some of the overhead of obtaining
read and write permission on the workspace. By default, directors do
not permit this, but many directors explicitly relinquish write access
to allow faster execution. Such directors are declaring that they
will not make changes to the topology during execution. Instead, any
desired mutations are delegated to the manager via the requestChange()
method.
Many domains make use of static analyses for performing, e.g.,
static scheduling of actor firings. In some cases, these analyses
must make use of global information. The class provides a centralized
mechanism for managing such global analyses. During preinitialize,
domains can invoke the getAnalysis and addAnalysis methods to create a
global analysis. It is up to the users of this mechanism to ensure
that a particular type of analysis is only created once, if that is
what is required. After preinitialize, the manager clears the list of
analyses, to avoid unnecessary memory usage, and to ensure that the
analyses are performed again on the next invocation of the model.
This is somewhat preferable to tying a cache of analysis information
to the version of the workspace, since the version number of the
workspace itself may change during preinitialize as domains add
annotation to the model.
Author(s): Steve Neuendorffer, Lukito Muliadi, Edward A. Lee, Elaine Cheong
// Contributors: Mudit Goel, John S. Davis II
Version:$Id: Manager.java,v 1.227 2006/03/30 16:34:53 cxh Exp $
Pt.Proposed Rating:Green (neuendor)
Pt.Accepted Rating:Yellow (cxh)