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)