ptolemy.actor

Class Manager

java.lang.Object

ptolemy.kernel.util.NamedObj

ptolemy.actor.Manager

All Implemented Interfaces:

java.lang.Cloneable, java.lang.Runnable, Changeable, Debuggable, DebugListener, Derivable, ModelErrorHandler, MoMLExportable, Moveable, Nameable

public class Manager
extends NamedObj
implements java.lang.Runnable

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.

Since:

Ptolemy II 0.2

Version:

$Id$

Author:

Steve Neuendorffer, Lukito Muliadi, Edward A. Lee, Elaine Cheong, Contributor: Mudit Goel, John S. Davis II, Bert Rodiers, Daniel Crawl

Pt.AcceptedRating:

Yellow (cxh)

Pt.ProposedRating:

Green (neuendor)

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Manager.State Instances of this class represent phases of execution, or the state of the manager.

Nested classes/interfaces inherited from class ptolemy.kernel.util.NamedObj

NamedObj.ContainedObjectsIterator

Field Summary

Fields

Modifier and Type	Field and Description
static Manager.State	CORRUPTED Indicator that the model may be corrupted.
static Manager.State	EXITING Indicator that the execution is in the wrapup phase and about to exit.
static Manager.State	IDLE Indicator that there is no currently active execution.
static Manager.State	INFERING_WIDTHS Indicator that width inference is being done.
static Manager.State	INITIALIZING Indicator that the execution is in the initialize phase.
static Manager.State	ITERATING Indicator that the execution is in an iteration.
static int	minimumStatisticsTime The minimum amount of time that may elapse during certain operations before statistics are generated.
static Manager.State	PAUSED Indicator that the execution is paused.
static Manager.State	PAUSED_ON_BREAKPOINT Indicator that the execution is paused on a breakpoint.
static Manager.State	PREINITIALIZING Indicator that the execution is in the preinitialize phase.
static Manager.State	RESOLVING_TYPES Indicator that type resolution is being done.
static long	SHUTDOWN_TIME The amount of time to allow for the model to terminate gracefully before shutting it down when the JVM is shut down due to control-C, user logging out, etc.
static Manager.State	THROWING_A_THROWABLE Indicator that the execution is throwing a throwable.
static Manager.State	WRAPPING_UP Indicator that the execution is in the wrapup phase.

Fields inherited from class ptolemy.kernel.util.NamedObj

_changeListeners, _changeLock, _changeRequests, _debugging, _debugListeners, _deferChangeRequests, _elementName, _isPersistent, _verbose, _workspace, ATTRIBUTES, CLASSNAME, COMPLETE, CONTENTS, DEEP, FULLNAME, LINKS

Constructor Summary

Constructors

Constructor and Description
Manager() Construct a manager in the default workspace with an empty string as its name.
Manager(java.lang.String name) Construct a manager in the default workspace with the given name.
Manager(Workspace workspace, java.lang.String name) Construct a manager in the given workspace with the given name.

Method Summary

Modifier and Type	Method and Description
protected void	_makeManagerOf(CompositeActor compositeActor) Make this manager the manager of the specified composite actor.
protected void	_notifyListenersOfCompletion() Deprecated. Incomplete name, use _notifyListenersOfSuccessfulCompletion()
protected void	_notifyListenersOfStateChange() Propagate the state change event to all the execution listeners.
protected void	_notifyListenersOfSuccessfulCompletion() Notify listeners that execution has completed successfully.
protected void	_registerShutdownHook() Register a shutdown hook to gracefully stop the execution of a model if the JVM is shut down (by control-C, the user logging out, etc.).
protected void	_setState(Manager.State newState) Set the state of execution and notify listeners if the state actually changes.
void	addAnalysis(java.lang.String name, java.lang.Object analysis) Add a static analysis to this manager.
void	addExecutionListener(ExecutionListener listener) Add a listener to be notified when the model execution changes state.
long	elapsedTimeSinceStart() Return the elapsed time (in milliseconds) since the start of execution of the model.
void	enablePrintTimeAndMemory(boolean enabled) Enable or disable printing time and memory usage at the end of model execution.
void	execute() Execute the model.
void	exitAfterWrapup() Cause the system to exit after wrapup().
void	finish() If the state is not IDLE, set a flag to request that execution stop and exit in a completely deterministic fashion at the end of the next toplevel iteration.
java.lang.Object	getAnalysis(java.lang.String name) Get the analysis with the given name, or return null if no such analysis exists.
NamedObj	getContainer() Return the top-level composite actor for which this manager controls execution.
java.lang.Object	getExecutionIdentifier(java.lang.Throwable throwable) Get the execution identifier object for a throwable.
int	getIterationCount() Return the iteration count, which is the number of iterations that have been started (but not necessarily completed).
long	getPreinitializeVersion() Return the workspace version on the last completion of preinitializeAndResolveTypes().
long	getRealStartTime() Get the real time at which the model began executing.
Manager.State	getState() Return the current state of execution of the manager.
java.lang.String	getStatusMessage() Return any messages, such as the amount of time consumed.
java.lang.Thread	getWaitingThread() Return a thread that is waiting and can be interrupted in the event that a change request is made, or null to indicate that there is no thread waiting.
void	initialize() Initialize the model.
void	invalidateResolvedTypes() Indicate that resolved types in the system may no longer be valid.
boolean	isExitingAfterWrapup() Return true if exitAfterWrapup() was called.
boolean	iterate() Invoke one iteration of the model.
void	notifyListenersOfException(java.lang.Exception exception) Notify all the execution listeners of an exception.
void	notifyListenersOfThrowable(java.lang.Throwable throwable) Notify all the execution listeners of a Throwable.
void	pause() Set a flag requesting that execution pause at the next opportunity (between iterations).
void	pauseOnBreakpoint(java.lang.String breakpointMessage) The thread that calls this method will wait until resume() has been called.
void	preinitializeAndResolveTypes() Preinitialize the model.
void	preinitializeIfNecessary() If the workspace version has changed since the last invocation of preinitializeAndResolveTypes(), then invoke it now and set the state of the Manager to IDLE upon completion.
static void	preinitializeThenWrapup(Actor actor) Invoke preinitialize() and wrapup().
void	removeExecutionListener(ExecutionListener listener) Remove a listener from the list of listeners that are notified of execution events.
void	requestInitialization(Actor actor) Queue an initialization request.
void	resolveTypes() Check types on all the connections and resolve undeclared types.
void	resume() If the model is paused, resume execution.
void	run() Execute the model, catching all exceptions.
void	setExecutionIdentifier(java.lang.Object executionIdentifier) Set the execution identifier object.
void	setStatusMessage(java.lang.String message) Set the status message, such as the amount of time consumed.
void	setWaitingThread(java.lang.Thread thread) Indicate that the specified thread is waiting and can be interrupted in the event that a change request is made.
static java.lang.String	shortDescription(java.lang.Throwable throwable) Deprecated. Instead ptolemy.util.MessageHandler.shortDescription()
void	startRun() Start an execution in another thread and return.
void	stop() If the state is not IDLE, set a flag to request that execution stop and exit in a completely deterministic fashion at the end of the next toplevel iteration.
void	terminate() Deprecated.
static java.lang.String	timeAndMemory(long startTime) Return a string with the elapsed time since startTime, and the amount of memory used.
static java.lang.String	timeAndMemory(long startTime, long totalMemory, long freeMemory) Return a string with the elapsed time since startTime, and the amount of memory used.
void	waitForCompletion() If there is an active thread created by startRun(), then wait for it to complete and return.
void	wrapup() Wrap up the model by invoking the wrapup method of the toplevel composite actor.

Methods inherited from class ptolemy.kernel.util.NamedObj

_addAttribute, _adjustOverride, _attachText, _cloneFixAttributeFields, _containedDecorators, _copyChangeRequestList, _debug, _debug, _debug, _debug, _debug, _description, _executeChangeRequests, _exportMoMLContents, _getContainedObject, _getIndentPrefix, _isMoMLSuppressed, _markContentsDerived, _notifyHierarchyListenersAfterChange, _notifyHierarchyListenersBeforeChange, _propagateExistence, _propagateValue, _removeAttribute, _splitName, _stripNumericSuffix, _validateSettables, addChangeListener, addDebugListener, addHierarchyListener, attributeChanged, attributeDeleted, attributeList, attributeList, attributeTypeChanged, clone, clone, containedObjectsIterator, decorators, deepContains, depthInHierarchy, description, description, event, executeChangeRequests, exportMoML, exportMoML, exportMoML, exportMoML, exportMoML, exportMoMLPlain, getAttribute, getAttribute, getAttributes, getChangeListeners, getClassName, getDecoratorAttribute, getDecoratorAttributes, getDerivedLevel, getDerivedList, getDisplayName, getElementName, getFullName, getModelErrorHandler, getName, getName, getPrototypeList, getSource, handleModelError, isDeferringChangeRequests, isOverridden, isPersistent, lazyContainedObjectsIterator, message, moveDown, moveToFirst, moveToIndex, moveToLast, moveUp, notifyOfNameChange, propagateExistence, propagateValue, propagateValues, removeAttribute, removeChangeListener, removeDebugListener, removeHierarchyListener, requestChange, setClassName, setDeferringChangeRequests, setDerivedLevel, setDisplayName, setModelErrorHandler, setName, setPersistent, setSource, sortContainedObjects, toplevel, toString, uniqueName, validateSettables, workspace

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

CORRUPTED

public static final Manager.State CORRUPTED

Indicator that the model may be corrupted.

IDLE

public static final Manager.State IDLE

Indicator that there is no currently active execution.

INFERING_WIDTHS

public static final Manager.State INFERING_WIDTHS

Indicator that width inference is being done.

INITIALIZING

public static final Manager.State INITIALIZING

Indicator that the execution is in the initialize phase.

ITERATING

public static final Manager.State ITERATING

Indicator that the execution is in an iteration.

PAUSED

public static final Manager.State PAUSED

Indicator that the execution is paused.

PAUSED_ON_BREAKPOINT

public static final Manager.State PAUSED_ON_BREAKPOINT

Indicator that the execution is paused on a breakpoint.

PREINITIALIZING

public static final Manager.State PREINITIALIZING

Indicator that the execution is in the preinitialize phase.

RESOLVING_TYPES

public static final Manager.State RESOLVING_TYPES

Indicator that type resolution is being done.

THROWING_A_THROWABLE

public static final Manager.State THROWING_A_THROWABLE

Indicator that the execution is throwing a throwable.

WRAPPING_UP

public static final Manager.State WRAPPING_UP

Indicator that the execution is in the wrapup phase.

EXITING

public static final Manager.State EXITING

Indicator that the execution is in the wrapup phase and about to exit.

minimumStatisticsTime

public static int minimumStatisticsTime

The minimum amount of time that may elapse during certain operations before statistics are generated. The Manager and other classes in Ptolemy will print out statistics if the amount of time (in milliseconds) named by this variable elapses during certain steps such as preinitialize(). The initial default value is 10000, meaning that certain operations can take up to 10 seconds before statistics are printed.

See Also:

CompositeEntity.statistics(String)

SHUTDOWN_TIME

public static long SHUTDOWN_TIME

The amount of time to allow for the model to terminate gracefully before shutting it down when the JVM is shut down due to control-C, user logging out, etc.

Constructor Detail

Manager

public Manager()

Construct a manager in the default workspace with an empty string as its name. The manager is added to the list of objects in the workspace. Increment the version number of the workspace.

Manager

public Manager(java.lang.String name)
        throws IllegalActionException

Construct a manager in the default workspace with the given name. If the name argument is null, then the name is set to the empty string. The manager is added to the list of objects in the workspace. Increment the version number of the workspace.

Parameters:

name - Name of this Manager.

Throws:

IllegalActionException - If the name has a period.

Manager

public Manager(Workspace workspace,
               java.lang.String name)
        throws IllegalActionException

Construct a manager in the given workspace with the given name. If the workspace argument is null, use the default workspace. The manager is added to the list of objects in the workspace. If the name argument is null, then the name is set to the empty string. Increment the version number of the workspace.

Parameters:

workspace - Object for synchronization and version tracking.

name - Name of this Manager.

Throws:

IllegalActionException - If the name has a period.

Method Detail

addAnalysis

public void addAnalysis(java.lang.String name,
                        java.lang.Object analysis)

Add a static analysis to this manager. A static analysis is simply an object that is recorded in a hash table and cleared at the end of preinitialize(), with no semantics associated with that object. The intent is for that object to serve as a repository for static analysis results, but clearing it and the end of preinitialize isn't quite right. The idea is that it is cleared at a point when the analysis has to be redone after that point. But doing this at the end of preinitialize means this won't work with models that mutate either during preinitialize() (as in higher- order actors) or during execution.

Parameters:

name - The name of the analysis.

analysis - The analysis to record.

See Also:

getAnalysis(String)

addExecutionListener

public void addExecutionListener(ExecutionListener listener)

Add a listener to be notified when the model execution changes state. If the specified listener is already a listener, do nothing.

Parameters:

listener - The listener.

See Also:

removeExecutionListener(ExecutionListener)

elapsedTimeSinceStart

public long elapsedTimeSinceStart()

Return the elapsed time (in milliseconds) since the start of execution of the model. The start of execution is defined to be the time after initialize() has been called and before any component has been iterated.

Returns:

The time in milliseconds since the start of execution of the model.

enablePrintTimeAndMemory

public void enablePrintTimeAndMemory(boolean enabled)

Enable or disable printing time and memory usage at the end of model execution.

Parameters:

enabled - Whether time and memory printing is enabled.

execute

public void execute()
             throws KernelException,
                    IllegalActionException

Execute the model. Begin with the initialization phase, followed by a sequence of iterations, followed by a wrapup phase. The sequence of iterations concludes when the postfire() method of the container (the top-level composite actor) returns false, or when the finish() method is called.

The execution is performed in the calling thread (the current thread), so this method returns only after execution finishes. If you wish to perform execution in a new thread, use startRun() instead. Even if an exception occurs during the execution, the wrapup() method is called (in a finally clause).

If an exception occurs during the execution, delegate to the exception handlers (if there are any) to handle these exceptions. If there are no exception handlers, it is up to the caller to handle (e.g. report) the exception. If you do not wish to handle exceptions, but want to execute within the calling thread, use run().

Throws:

KernelException - If the model throws it.

IllegalActionException - If the model is already running, or if there is no container.

See Also:

run()

exitAfterWrapup

public void exitAfterWrapup()

Cause the system to exit after wrapup(). If the ptolemy.ptII.exitAfterWrapup property is not set, then when wrapup() is almost finished, we call System.exit(). If the ptolemy.ptII.exitAfterWrapup property is set, then we throw an Exception.

finish

public void finish()

If the state is not IDLE, set a flag to request that execution stop and exit in a completely deterministic fashion at the end of the next toplevel iteration. This method may be called from within an actor to stop the execution of the model. This will result in stop() being called on the top level CompositeActor, although not necessarily immediately. Note that this method is allowed to be called if the model is paused and actors that implement the stop() method must properly respond to that method even if the model is paused.

See Also:

Executable.stop()

getAnalysis

public java.lang.Object getAnalysis(java.lang.String name)

Get the analysis with the given name, or return null if no such analysis exists.

Parameters:

name - The name of the analysis.

Returns:

the analysis with the given name, or null.

See Also:

addAnalysis(String, Object)

getRealStartTime

public long getRealStartTime()

Get the real time at which the model began executing.

Returns:

The real time at which the model began executing.

getContainer

public NamedObj getContainer()

Return the top-level composite actor for which this manager controls execution.

Specified by:

getContainer in interface Nameable

Overrides:

getContainer in class NamedObj

Returns:

The composite actor that this manager is responsible for.

getIterationCount

public int getIterationCount()

Return the iteration count, which is the number of iterations that have been started (but not necessarily completed).

Returns:

The number of iterations started.

getPreinitializeVersion

public long getPreinitializeVersion()

Return the workspace version on the last completion of preinitializeAndResolveTypes(). This can be used to optimize away actions on repeated runs when the workspace hasn't changed between runs.

Returns:

the workspace version on the last completion of preinitializeAndResolveTypes().

getState

public Manager.State getState()

Return the current state of execution of the manager.

Returns:

The state of execution.

getStatusMessage

public java.lang.String getStatusMessage()

Return any messages, such as the amount of time consumed. This method is called to update the status bar, so the output should be short.

Returns:

the message

See Also:

setStatusMessage(String)

getExecutionIdentifier

public java.lang.Object getExecutionIdentifier(java.lang.Throwable throwable)

Get the execution identifier object for a throwable.

An execution identifier is an object given to the Manager via setExecutionIdentifier(), and cleared during preinitialize(). If the Manager notifies a listener of a model error, getExecutionIdentifier() can be used to map that error back to the executionIdentifier object.

Parameters:

throwable - The throwable.

Returns:

The execution identifier object if one was set, otherwise null.

See Also:

setExecutionIdentifier(Object)

getWaitingThread

public java.lang.Thread getWaitingThread()

Return a thread that is waiting and can be interrupted in the event that a change request is made, or null to indicate that there is no thread waiting.

Returns:

The thread that is waiting, or null to indicate that no thread is waiting.

See Also:

setWaitingThread(Thread)

initialize

public void initialize()
                throws KernelException,
                       IllegalActionException

Initialize the model. This calls the preinitialize() method of the container, followed by the resolveTypes() and initialize() methods. Set the Manager's state to PREINITIALIZING and INITIALIZING as appropriate. This method is read synchronized on the workspace.

Throws:

KernelException - If the model throws it.

IllegalActionException - If the model is already running, or if there is no container.

invalidateResolvedTypes

public void invalidateResolvedTypes()

Indicate that resolved types in the system may no longer be valid. This will force type resolution to be redone on the next iteration.

isExitingAfterWrapup

public boolean isExitingAfterWrapup()

Return true if exitAfterWrapup() was called.

Returns:

true if exitAfterWrapup was called.

iterate

public boolean iterate()
                throws KernelException

Invoke one iteration of the model. An iteration consists of first performing changes queued with requestChange() and type resolution, if necessary, and then invoking prefire(), fire(), and postfire(), in that order. If prefire() returns false, then fire() and postfire() are not invoked, and true is returned. Otherwise, fire() will be called once, followed by postfire(). The return value of postfire() is returned. Note that this method ignores finish and pause requests and thus determines a minimum granularity of the execution. Set the state of the manager to ITERATING. This method is read synchronized on the workspace.

Returns:

True if postfire() is not called, otherwise, return the value returned by postfire().

Throws:

KernelException - If the model throws it, or if there is no container.

notifyListenersOfException

public void notifyListenersOfException(java.lang.Exception exception)

Notify all the execution listeners of an exception. If there are no listeners, then print the exception information to the standard error stream. This is intended to be used by threads that are involved in an execution as a mechanism for reporting errors. As an example, in a threaded domain, each thread should catch all exceptions and report them using this method. This method is merely calls notifyListenersOfThrowable(Throwable).

Parameters:

exception - The exception.

notifyListenersOfThrowable

public void notifyListenersOfThrowable(java.lang.Throwable throwable)

Notify all the execution listeners of a Throwable. If there are no listeners, then print the throwable information to the standard error stream. This is intended to be used by threads that are involved in an execution as a mechanism for reporting errors. As an example, in a threaded domain, each thread should catch all exceptions and report them using this method. This method defers the actual reporting to a new thread because it requires obtaining a lock on this manager, and that could cause deadlock.

Parameters:

throwable - The throwable

pause

public void pause()

Set a flag requesting that execution pause at the next opportunity (between iterations). This method calls stopFire() on the toplevel composite actor to ensure that the manager's execution thread becomes active again. Actors are expected to react to stopFire() by returning as soon as possible from their fire() methods, thus completing an iteration. For example, in the case of PN, an iteration only ends if deadlock occurs, which may never happen. Calling stopFire() truncates the iteration. The thread controlling the execution (the one that calls execute()) will be suspended the next time through the iteration loop. To resume execution, call resume().

See Also:

Executable.stopFire()

pauseOnBreakpoint

public void pauseOnBreakpoint(java.lang.String breakpointMessage)

The thread that calls this method will wait until resume() has been called.

Note: This method will block. It should only be called from the executing thread (the thread that is executing the model). Do not call this method from the same thread that will call resume().

Parameters:

breakpointMessage - The message to print when paused on a breakpoint.

preinitializeAndResolveTypes

public void preinitializeAndResolveTypes()
                                  throws KernelException

Preinitialize the model. This calls the preinitialize() method of the container, followed by the resolveTypes() methods. Set the Manager's state to PREINITIALIZING. Note that this method may be invoked without actually running the method, but the calling code must make sure that the Manager's state is reset to IDLE. This method is read synchronized on the workspace.

Throws:

KernelException - If the model throws it.

IllegalActionException - If the model is already running, or if there is no container.

preinitializeIfNecessary

public void preinitializeIfNecessary()
                              throws KernelException

If the workspace version has changed since the last invocation of preinitializeAndResolveTypes(), then invoke it now and set the state of the Manager to IDLE upon completion. This can be used during editing a model to check types, to expand higher-order components, or to establish connections between Publisher and Subscriber actors.

Throws:

KernelException - If thrown while preinitializing and resolving types.

preinitializeThenWrapup

public static void preinitializeThenWrapup(Actor actor)
                                    throws KernelException

Invoke preinitialize() and wrapup().

If the model has not been preinitialized since the last change to its structure, that must be done now for the result to be accurate. This is because higher-order components and Publisher and Subscriber connections may not have yet been created.

Parameters:

actor - The actor upon which to call preinitialize() on its toplevel.

Throws:

KernelException - If thrown when a Manager is added to the top level or if preinitialize() fails.

removeExecutionListener

public void removeExecutionListener(ExecutionListener listener)

Remove a listener from the list of listeners that are notified of execution events. If the specified listener is not on the list, do nothing.

Parameters:

listener - The listener to remove.

See Also:

addExecutionListener(ExecutionListener)

requestInitialization

public void requestInitialization(Actor actor)

Queue an initialization request. The specified actor will be initialized at an appropriate time, in the iterate() method, by calling its preinitialize() and initialize() methods. This method should be called when an actor is added to a model through a mutation in order to properly initialize the actor.

Parameters:

actor - The actor to initialize.

resolveTypes

public void resolveTypes()
                  throws TypeConflictException

Check types on all the connections and resolve undeclared types. If the container is not an instance of TypedCompositeActor, do nothing. Set the Manager's state to RESOLVING_TYPES. This method is write-synchronized on the workspace.

Throws:

TypeConflictException - If a type conflict is detected.

resume

public void resume()

If the model is paused, resume execution. This method must be called from a different thread than that controlling the execution, since the thread controlling the execution is suspended.

run

public void run()

Execute the model, catching all exceptions. Use this method to execute the model within the calling thread, but to not throw exceptions. Instead, the exception is handled using the notifyListenersOfException() method. Except for its exception handling, this method has exactly the same behavior as execute().

Specified by:

run in interface java.lang.Runnable

setExecutionIdentifier

public void setExecutionIdentifier(java.lang.Object executionIdentifier)

Set the execution identifier object. Any throwables that occur in current execution cycle are associated with this identifier. The execution identifier is reset in preinitialize().

Parameters:

executionIdentifier - The execution identifier object

See Also:

getExecutionIdentifier(Throwable)

setStatusMessage

public void setStatusMessage(java.lang.String message)

Set the status message, such as the amount of time consumed. This method is called to update the status bar, so the output should be short.

Parameters:

message - The message to be displayed.

See Also:

getStatusMessage()

setWaitingThread

public void setWaitingThread(java.lang.Thread thread)

Indicate that the specified thread is waiting and can be interrupted in the event that a change request is made.

Parameters:

thread - The thread that is waiting, or null to indicate that no thread is waiting.

See Also:

getWaitingThread()

shortDescription

@Deprecated
public static java.lang.String shortDescription(java.lang.Throwable throwable)

Deprecated. Instead ptolemy.util.MessageHandler.shortDescription()

Return a short description of the throwable.

Parameters:

throwable - The throwable

Returns:

If the throwable is an Exception, return "Exception", if it is an Error, return "Error", if it is a Throwable, return "Throwable".

startRun

public void startRun()
              throws IllegalActionException

Start an execution in another thread and return. Any exceptions that occur during the execution of the model are handled by the notifyListenersOfException() method.

Throws:

IllegalActionException - If the model is already running, e.g. the state is not IDLE.

stop

public void stop()

If the state is not IDLE, set a flag to request that execution stop and exit in a completely deterministic fashion at the end of the next toplevel iteration. This method may be called from within an actor to stop the execution of the model. This will result in stop() being called on the top level CompositeActor, although not necessarily immediately. This is basically an alias for finish().

Note that in general, it is best to get that director and call finish() and stopFire() on the director than it is to call Manager.stop().

The reason that it is better to call Director.finish() is that if Manager.stop() is called inside a RunCompositeActor then only the inside execution will be stopped, not the outside one. It is also not correct to call stop() on the directory because Director.stop() requests immediate stopping. To give determinate stopping, call Director.finish() so that the current iteration is completed.

In multithreaded domains, Director.stopFire is called to request that all actors conclude ongoing firings.

terminate

@Deprecated
public void terminate()

Deprecated.

Terminate the currently executing model with extreme prejudice. This leaves the state of the manager in CORRUPTED, which means that the model cannot be executed again. A new model must be created, with a new manager, to execute again. This method is not intended to be used as a normal route of stopping execution. To normally stop execution, call the finish() method instead. This method should be called only when execution fails to terminate by normal means due to certain kinds of programming errors (infinite loops, threading errors, etc.).

If the model execution was started in a separate thread (using startRun()), then that thread is killed unceremoniously (using a method that is now deprecated in Java, for obvious reasons). This method also calls terminate on the toplevel composite actor.

This method is not synchronized because we want it to execute as soon as possible.

timeAndMemory

public static java.lang.String timeAndMemory(long startTime)

Return a string with the elapsed time since startTime, and the amount of memory used.

Parameters:

startTime - The start time in milliseconds. For example, the value returned by (new Date()).getTime().

Returns:

A string with the elapsed time since startTime, and the amount of memory used.

timeAndMemory

public static java.lang.String timeAndMemory(long startTime,
                                             long totalMemory,
                                             long freeMemory)

Return a string with the elapsed time since startTime, and the amount of memory used. the value returned by (new Date()).getTime().

Parameters:

startTime - The start time in milliseconds. For example, the value returned by (new Date()).getTime().

totalMemory - The total amount of memory used in kilobytes.

freeMemory - The total amount of memory free in kilobytes.

Returns:

A string with the elapsed time since startTime, and the amount of memory used.

waitForCompletion

public void waitForCompletion()

If there is an active thread created by startRun(), then wait for it to complete and return. The wait is accomplished by calling the join() method on the thread. If there is no active thread, then wait until the manager state is idle by calling wait().

See Also:

startRun()

wrapup

public void wrapup()
            throws KernelException,
                   IllegalActionException

Wrap up the model by invoking the wrapup method of the toplevel composite actor. At the end of this model, the state is set to idle.

Throws:

KernelException - If the model throws it.

IllegalActionException - If the model is idle or already wrapping up, or if there is no container.

_makeManagerOf

protected void _makeManagerOf(CompositeActor compositeActor)

Make this manager the manager of the specified composite actor. If the composite actor is not null, then the manager is removed from the directory of the workspace. If the composite actor is null, then the manager is not returned to the directory of the workspace, which may result in it being garbage collected. This method should not be called directly. Instead, call setManager in the CompositeActor class (or a derived class).

Parameters:

compositeActor - The composite actor that this manager will manage.

_notifyListenersOfCompletion

@Deprecated
protected void _notifyListenersOfCompletion()

Deprecated. Incomplete name, use _notifyListenersOfSuccessfulCompletion()

Notify listeners that execution has completed.

_notifyListenersOfSuccessfulCompletion

protected void _notifyListenersOfSuccessfulCompletion()

Notify listeners that execution has completed successfully.

_notifyListenersOfStateChange

protected void _notifyListenersOfStateChange()

Propagate the state change event to all the execution listeners.

_registerShutdownHook

protected void _registerShutdownHook()

Register a shutdown hook to gracefully stop the execution of a model if the JVM is shut down (by control-C, the user logging out, etc.).

_setState

protected void _setState(Manager.State newState)

Set the state of execution and notify listeners if the state actually changes.

Parameters:

newState - The new state.