ptolemy.actor.lib.hoc
Class ModelReference

java.lang.Object
  ptolemy.kernel.util.NamedObj
      ptolemy.kernel.InstantiableNamedObj
          ptolemy.kernel.Entity
              ptolemy.kernel.ComponentEntity
                  ptolemy.actor.AtomicActor
                      ptolemy.actor.TypedAtomicActor
                          ptolemy.actor.lib.hoc.ModelReference

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable, Actor, Executable, ExecutionListener, FiringsRecordable, Initializable, TypedActor, Changeable, Debuggable, DebugListener, Derivable, Instantiable, ModelErrorHandler, MoMLExportable, Moveable, Nameable

Direct Known Subclasses:

VisualModelReference

public class ModelReference
extends TypedAtomicActor
implements ExecutionListener

This is an atomic actor that can execute a model specified by a file or URL. This can be used to define an actor whose firing behavior is given by a complete execution of another model.

An instance of this actor can have ports added to it. If it has input ports, then on each firing, before executing the referenced model, this actor will read an input token from the input port, if there is one, and use it to set the value of a top-level parameter in the referenced model that has the same name as the port, if there is one. The simplest way to ensure that there is a matching parameter is to use a PortParameter for inputs. However, this actor will work also for ordinary ports. In this case, if there is a top-level parameter of the referenced model with the same name as the port, and it is an instance of Variable (or its derived class Parameter), then the token read at the input is moved into it using its setToken() method. Otherwise, if it is an instance of Settable, then a string representation of the token is copied using the setExpression() method. Input ports should not be multiports, and if they are, then all but the first channel will be ignored.

If this actor has output ports and the referenced model is executed, then upon completion of that execution, this actor looks for top-level parameters in the referenced model whose names match those of the output ports. If there are such parameters, then the final value of those parameters is sent to the output ports. If such a parameter is an instance of Variable (or its derived class Parameter), then its contained token is sent to the output. Otherwise, if it is an instance of Settable, then a string token is produced on the output with its value equal to that returned by getExpression() of the Settable. If the model is executed in the calling thread, then the outputs will be produced before the fire() method returns. If the model is executed in a new thread, then the outputs will be produced whenever that thread completes execution of the model. Output ports should not be multiports. If they are, then all but the first channel will be ignored. Normally, when you create output ports for this actor, you will have to manually set the type. There is no type inference from the parameter of the referenced model.

A typical use of this actor will use the SetVariable actor inside to define the value of the output port.

A suite of parameters is provided to control what happens when this actor executes:

• executionOnFiring: The value of this string attribute determines what execution happens when the fire() method is invoked. The recognized values are:
  • "run in calling thread" (the default)
  • "run in a new thread"
  • "do nothing".
  If execution in a separate thread is selected, then the execution can optionally be stopped by the postfire() method (see below). If the model is still executing the next time fire() is called on this actor, then the fire() method will wait for completion of the first execution. If an exception occurs during a run in another thread, then it will be reported at the next invocation of fire(), postfire(), or wrapup(). Note that if you select "run in a new thread" and this actor has output ports, the data is produced to those output ports when the execution completes, whenever that might be. This may make output ports difficult to use in some domains.
• lingerTime: The amount of time (in milliseconds) to linger in the fire() method of this actor. This is a long that defaults to 0L. If the model is run in the calling thread, then the linger occurs after the run is complete. If the model is run in a new thread, then the linger occurs after the run starts, and the run is stopped after the linger time expires. This can be used, for example, to run a model for a specified amount of time, then ask it to finish() and continue.
• modelFileOrURL: The file name or URL of the model that this actor will execute. This can be specified either by setting the parameter or by providing a string at the input port.
• postfireAction: The value of this string attribute determines what happens in the postfire() method. The recognized values are:
  • "do nothing" (the default)
  • "stop executing"
  The "stop executing" choices will only have an effect if if executionOnFiring is set to "run in a new thread". This can be used, for example, to run a model for a specified amount of time, and then stop it.

There are currently some limitations:

• The referenced model cannot create any displays. Use the subclass VisualModelReference to do that.
• FIXME: Pausing the referring model doesn't pause the referenced model.
• FIXME: Need options for error handling.

Since:

Ptolemy II 4.0

Version:

$Id: ModelReference.java 57040 2010-01-27 20:52:32Z cxh $

Author:

Edward A. Lee, Elaine Cheong

See Also:

RunCompositeActor, SetVariable, Serialized Form

Accepted Rating:

Red (eal)

Proposed Rating:

Yellow (eal)

Nested Class Summary

Nested classes/interfaces inherited from class ptolemy.kernel.Entity

Entity.ContainedObjectsIterator

Field Summary

protected boolean	_alreadyReadInputs If a derived class calls modelFileOrURL.update() in its fire() method prior to calling super.fire(), then it should set this flag to true.
private static int	_DO_NOTHING
private boolean	_executing
private int	_executionOnFiringValue The value of the executionOnFiring parameter.
private java.lang.Thread	_lingeringThread Reference to a thread that is lingering.
private Manager	_manager The manager currently managing execution.
protected NamedObj	_model The model.
private int	_postfireActionValue The value of the postfireAction parameter.
private static int	_RUN_IN_A_NEW_THREAD
private static int	_RUN_IN_CALLING_THREAD
private static int	_STOP_EXECUTING
private java.lang.Throwable	_throwable
StringParameter	executionOnFiring The value of this string parameter determines what execution happens when the fire() method is invoked.
Parameter	lingerTime The amount of time (in milliseconds) to linger in the fire() method of this actor.
FilePortParameter	modelFileOrURL The file name or URL of the model that this actor represents.
StringParameter	postfireAction The value of this string attribute determines what happens in the postfire() method.

Fields inherited from class ptolemy.actor.AtomicActor

_actorFiringListeners, _initializables, _notifyingActorFiring, _stopRequested

Fields inherited from class ptolemy.kernel.util.NamedObj

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

Fields inherited from interface ptolemy.actor.Executable

COMPLETED, NOT_READY, STOP_ITERATING

Constructor Summary

ModelReference(CompositeEntity container, java.lang.String name)
Construct a ModelReference with a name and a container.

Method Summary

protected void	_readInputsAndValidateSettables() Iterate over input ports and read any available values into the referenced model parameters and validate settable attributes.
private void	_writeOutputs() Iterate over output ports and read any available values from the referenced model parameters and produce them on the outputs.
void	attributeChanged(Attribute attribute) Override the base class to open the model specified if the attribute is modelFileOrURL, or for other parameters, to cache their values.
java.lang.Object	clone(Workspace workspace) Clone the actor into the specified workspace.
void	executionError(Manager manager, java.lang.Throwable throwable) React to the fact that execution has failed by unregistering as an execution listener and by allowing subsequent executions.
void	executionFinished(Manager manager) React to the fact that execution is finished by unregistering as an execution listener and by allowing subsequent executions.
void	fire() Run a complete execution of the referenced model.
void	managerStateChanged(Manager manager) Report in debugging statements that the manager state has changed.
boolean	postfire() Override the base class to perform requested postfire actions.
void	stop() Override the base class to call stop() on the referenced model.
void	stopFire() Request that execution of the current iteration complete.
void	terminate() Override the base class to call terminate() on the referenced model.
void	wrapup() Report an exception if it occurred in a background run.

Methods inherited from class ptolemy.actor.TypedAtomicActor

_addPort, _fireAt, _fireAt, attributeTypeChanged, clone, newPort, typeConstraintList, typeConstraints

Methods inherited from class ptolemy.actor.AtomicActor

_actorFiring, _actorFiring, addActorFiringListener, addInitializable, connectionsChanged, createReceivers, declareDelayDependency, getCausalityInterface, getDirector, getExecutiveDirector, getManager, initialize, inputPortList, isFireFunctional, isStrict, iterate, newReceiver, outputPortList, prefire, preinitialize, pruneDependencies, recordFiring, removeActorFiringListener, removeDependency, removeInitializable, setContainer

Methods inherited from class ptolemy.kernel.ComponentEntity

_adjustDeferrals, _checkContainer, _getContainedObject, _propagateExistence, getContainer, instantiate, isAtomic, isOpaque, moveDown, moveToFirst, moveToIndex, moveToLast, moveUp, propagateExistence, setName

Methods inherited from class ptolemy.kernel.Entity

_description, _exportMoMLContents, _removePort, _validateSettables, connectedPortList, connectedPorts, containedObjectsIterator, getAttribute, getPort, getPorts, linkedRelationList, linkedRelations, portList, removeAllPorts, setClassDefinition, uniqueName

Methods inherited from class ptolemy.kernel.InstantiableNamedObj

_setParent, exportMoML, getChildren, getElementName, getParent, getPrototypeList, isClassDefinition, isWithinClassDefinition

Methods inherited from class ptolemy.kernel.util.NamedObj

_addAttribute, _adjustOverride, _attachText, _cloneFixAttributeFields, _debug, _debug, _debug, _debug, _debug, _getIndentPrefix, _isMoMLSuppressed, _markContentsDerived, _propagateValue, _recordDecoratedAttributes, _removeAttribute, _splitName, _stripNumericSuffix, addChangeListener, addDebugListener, attributeList, attributeList, deepContains, depthInHierarchy, description, description, event, executeChangeRequests, exportMoML, exportMoML, exportMoML, exportMoML, exportMoMLPlain, getAttribute, getAttributes, getChangeListeners, getClassName, getDecoratorAttribute, getDecoratorAttributes, getDerivedLevel, getDerivedList, getDisplayName, getFullName, getModelErrorHandler, getName, getName, getSource, handleModelError, isDeferringChangeRequests, isOverridden, isPersistent, lazyContainedObjectsIterator, message, propagateValue, propagateValues, removeChangeListener, removeDebugListener, requestChange, setClassName, setDeferringChangeRequests, setDerivedLevel, setDisplayName, setModelErrorHandler, setPersistent, setSource, sortContainedObjects, toplevel, toString, validateSettables, workspace

Methods inherited from class java.lang.Object

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

Methods inherited from interface ptolemy.actor.Actor

createReceivers, getCausalityInterface, getDirector, getExecutiveDirector, getManager, inputPortList, newReceiver, outputPortList

Methods inherited from interface ptolemy.actor.Executable

isFireFunctional, isStrict, iterate, prefire

Methods inherited from interface ptolemy.actor.Initializable

addInitializable, initialize, preinitialize, removeInitializable

Methods inherited from interface ptolemy.kernel.util.Nameable

description, getContainer, getDisplayName, getFullName, getName, getName, setName

Methods inherited from interface ptolemy.kernel.util.Derivable

getDerivedLevel, getDerivedList, propagateValue

Field Detail

executionOnFiring

public StringParameter executionOnFiring

The value of this string parameter determines what execution happens when the fire() method is invoked. The recognized values are:

• "run in calling thread" (the default)
• "run in a new thread"
• "do nothing".

lingerTime

public Parameter lingerTime

The amount of time (in milliseconds) to linger in the fire() method of this actor. This is a long that defaults to 0L. If the model is run, then the linger occurs after the run is complete (if the run occurs in the calling thread) or after the run starts (if the run occurs in a separate thread).

modelFileOrURL

public FilePortParameter modelFileOrURL

The file name or URL of the model that this actor represents. This is empty by default, which means that there is no associated model to execute.

postfireAction

public StringParameter postfireAction

The value of this string attribute determines what happens in the postfire() method. The recognized values are:

• "do nothing" (the default)
• "stop executing"

The "stop executing" choices will only have an effect if if executionOnFiring is set to "run in a new thread". This can be used, for example, to run a model for a specified amount of time, and then stop it.

_alreadyReadInputs

protected boolean _alreadyReadInputs

If a derived class calls modelFileOrURL.update() in its fire() method prior to calling super.fire(), then it should set this flag to true.

_model

protected NamedObj _model

The model.

_DO_NOTHING

private static int _DO_NOTHING

_RUN_IN_CALLING_THREAD

private static int _RUN_IN_CALLING_THREAD

_RUN_IN_A_NEW_THREAD

private static int _RUN_IN_A_NEW_THREAD

_executionOnFiringValue

private transient int _executionOnFiringValue

The value of the executionOnFiring parameter.

_executing

private transient volatile boolean _executing

_lingeringThread

private java.lang.Thread _lingeringThread

Reference to a thread that is lingering.

_manager

private Manager _manager

The manager currently managing execution.

_postfireActionValue

private transient int _postfireActionValue

The value of the postfireAction parameter.

_STOP_EXECUTING

private static int _STOP_EXECUTING

_throwable

private transient java.lang.Throwable _throwable

Constructor Detail

ModelReference

public ModelReference(CompositeEntity container,
                      java.lang.String name)
               throws IllegalActionException,
                      NameDuplicationException

Construct a ModelReference with a name and a container. The container argument must not be null, or a NullPointerException will be thrown. This actor will use the workspace of the container for synchronization and version counts. If the name argument is null, then the name is set to the empty string. Increment the version of the workspace. This actor will have no local director initially, and its executive director will be simply the director of the container.

Parameters:

container - The container.

name - The name of this actor.

Throws:

IllegalActionException - If the container is incompatible with this actor.

NameDuplicationException - If the name coincides with an actor already in the container.

Method Detail

attributeChanged

public void attributeChanged(Attribute attribute)
                      throws IllegalActionException

Override the base class to open the model specified if the attribute is modelFileOrURL, or for other parameters, to cache their values.

Overrides:

attributeChanged in class NamedObj

Parameters:

attribute - The attribute that changed.

Throws:

IllegalActionException - If the change is not acceptable to this container (not thrown in this base class).

clone

public java.lang.Object clone(Workspace workspace)
                       throws java.lang.CloneNotSupportedException

Clone the actor into the specified workspace. This overrides the base class to ensure that private variables are reset to null.

Overrides:

clone in class AtomicActor

Parameters:

workspace - The workspace for the new object.

Returns:

A new actor.

Throws:

java.lang.CloneNotSupportedException - If a derived class contains an attribute that cannot be cloned.

See Also:

NamedObj.exportMoML(Writer, int, String), NamedObj.setDeferringChangeRequests(boolean)

executionError

public void executionError(Manager manager,
                           java.lang.Throwable throwable)

React to the fact that execution has failed by unregistering as an execution listener and by allowing subsequent executions. Report an execution failure at the next opportunity. This method will be called when an exception or error is caught by a manager during a run in another thread of the referenced model.

Specified by:

executionError in interface ExecutionListener

Parameters:

manager - The manager controlling the execution.

throwable - The throwable to report.

executionFinished

public void executionFinished(Manager manager)

React to the fact that execution is finished by unregistering as an execution listener and by allowing subsequent executions. This is called when an execution of the referenced model in another thread has finished and the wrapup sequence has completed normally. The number of successfully completed iterations can be obtained by calling getIterationCount() on the manager.

Specified by:

executionFinished in interface ExecutionListener

Parameters:

manager - The manager controlling the execution.

fire

public void fire()
          throws IllegalActionException

Run a complete execution of the referenced model. A complete execution consists of invocation of super.initialize(), repeated invocations of super.prefire(), super.fire(), and super.postfire(), followed by super.wrapup(). The invocations of prefire(), fire(), and postfire() are repeated until either the model indicates it is not ready to execute (prefire() returns false), or it requests a stop (postfire() returns false or stop() is called). Before running the complete execution, this method examines input ports, and if they are connected, have data, and if the referenced model has a top-level parameter with the same name, then one token is read from the input port and used to set the value of the parameter in the referenced model. After running the complete execution, if there are any output ports, then this method looks for top-level parameters in the referenced model with the same name as the output ports, and if there are any, reads their values and produces them on the output. If no model has been specified, then this method does nothing.

Specified by:

fire in interface Executable

Overrides:

fire in class AtomicActor

Throws:

IllegalActionException - If there is no director, or if the director's action methods throw it.

managerStateChanged

public void managerStateChanged(Manager manager)

Report in debugging statements that the manager state has changed. This method is called if the referenced model is executed in another thread and the manager changes state.

Specified by:

managerStateChanged in interface ExecutionListener

Parameters:

manager - The manager controlling the execution.

See Also:

Manager.getState()

postfire

public boolean postfire()
                 throws IllegalActionException

Override the base class to perform requested postfire actions.

Specified by:

postfire in interface Executable

Overrides:

postfire in class AtomicActor

Returns:

Whatever the superclass returns (probably true).

Throws:

IllegalActionException - Thrown if a parent class throws it.

stop

public void stop()

Override the base class to call stop() on the referenced model.

Specified by:

stop in interface Executable

Overrides:

stop in class AtomicActor

stopFire

public void stopFire()

Description copied from class: AtomicActor

Request that execution of the current iteration complete. Most atomic actors have bounded fire() methods, so they can simply ignore this. Atomic actors with unbounded fire() methods should override this method to save their state and return from the fire() method at the next convenient point. In this base class, do nothing.

Specified by:

stopFire in interface Executable

Overrides:

stopFire in class AtomicActor

terminate

public void terminate()

Override the base class to call terminate() on the referenced model.

Specified by:

terminate in interface Executable

Overrides:

terminate in class AtomicActor

wrapup

public void wrapup()
            throws IllegalActionException

Report an exception if it occurred in a background run.

Specified by:

wrapup in interface Initializable

Overrides:

wrapup in class AtomicActor

Throws:

IllegalActionException - If there is no director, or if a background run threw an exception.

_readInputsAndValidateSettables

protected void _readInputsAndValidateSettables()
                                        throws IllegalActionException

Iterate over input ports and read any available values into the referenced model parameters and validate settable attributes. Note: We call validateSettables() on the referenced model in this method, since input values read into the referenced model may cause structural changes to the model (e.g. if a Ptalon parameter changes and causes the internal structure of a PtalonActor to be regenerated). Since validateSettables() is not currently called in ptolemy.actor.Manager#preinitializeAndResolveTypes(), we must call it here before type resolution begins in a later step, in order to avoid collecting invalid type constraints (due to deleted or invalidated parts of the model) and to avoid insufficient type constraints (due to newly generated parts of the model).

Throws:

IllegalActionException - If reading the ports or setting the parameters causes it.

_writeOutputs

private void _writeOutputs()
                    throws IllegalActionException

Iterate over output ports and read any available values from the referenced model parameters and produce them on the outputs.

Throws:

IllegalActionException - If reading the parameters or writing to the ports causes it.