ptolemy.actor.lib
Class SetVariable

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.SetVariable

All Implemented Interfaces:

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

public class SetVariable
extends TypedAtomicActor
implements ChangeListener, ExplicitChangeContext

Set the value of a variable contained by the container. The result may occur at two different times, depending on the value of the delayed parameter.

If delayed is true, then the change to the value of the variable is implemented in a change request, and consequently will not take hold until the end of the current top-level iteration. This helps ensure that users of value of the variable will see changes to the value deterministically (independent of the schedule of execution of the actors), assuming there is only a single instance of SetVariable writing to the variable.

If delayed is false, then the change to the value of the variable is performed immediately in the fire() method. This allows more frequent reconfiguration, and can mimic the operation of PGM's graph variables. However, this can result in nondeterminism if the variable values are observed by any other actor in the system. If you are trying to communicate with another actor without wiring, use the Publisher and Subscriber actors instead.

If delayed is false, then the output port produces the same token provided at the input port when the actor fires, after the specified variable has been set. This can be used, even with delayed set to false, to ensure determinacy, by triggering downstream actions only after the variable has been set.

If delayed is true, then the output port produces the current value of the referenced variable. If the referenced variable does not exist on the first firing, or is not an instance of Variable, then no output is produced on the first firing.

The variable can be either any attribute that implements the Settable interface. If it is in addition an instance of Variable, then the input token is used directly to set the value, and the type of the variable is constrained to be the same as the type of the input. Otherwise, then input token is converted to a string and the setExpression() method on the variable is used to set the value.

The variable can occur anywhere in the hierarchy above the current level. If the variable is not found in the container, then the container of the container is checked until we reach the top level. If still no variable is found, then a variable is created in the container.

For efficiency, the variable update does not automatically trigger a repaint in Vergil. If the variable value is being used to create an animation in Vergil, then you should include in the model an instance of RepaintController, which can be found under Utilities in the library.

Since:

Ptolemy II 4.0

Version:

$Id: SetVariable.java 57046 2010-01-27 23:35:53Z cxh $

Author:

Edward A. Lee, Steve Neuendorffer, Contributor: Blanc, Bert Rodiers

See Also:

Publisher, Subscriber, Serialized Form

Accepted Rating:

Red (cxh)

Proposed Rating:

Red (yuhong)

Nested Class Summary

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

Entity.ContainedObjectsIterator

Field Summary

private Attribute	_attribute Cached reference to the associated variable.
private long	_attributeVersion Workspace version for the cached attribute reference.
private boolean	_setFailed Indicator that setting the variable failed.
Parameter	delayed Parameter that determines when reconfiguration occurs.
TypedIOPort	input The input port.
TypedIOPort	output The output port.
StringAttribute	variableName The name of the variable in the container to set.

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

SetVariable(CompositeEntity container, java.lang.String name)
Construct an actor with the given container and name.

Method Summary

private void	_setValue(Token value) Set the value of the associated container's variable.
void	changeExecuted(ChangeRequest change) Do nothing.
void	changeFailed(ChangeRequest change, java.lang.Exception exception) React to the fact that a change failed by setting a flag that causes an exception to be thrown in next call to prefire() or wrapup().
void	fire() Read at most one token from the input port and issue a change request to update variables as indicated by the input.
Entity	getContext() Return the change context being made explicit.
Attribute	getModifiedVariable() Return the (presumably Settable) attribute modified by this actor.
java.util.List	getModifiedVariables() Return a list of variables that this entity modifies.
boolean	postfire() Read at most one token from the input port and issue a change request to update variables as indicated by the input.
void	preinitialize() If there is no variable with the specified name, then create one.
java.util.Set<Inequality>	typeConstraints() Override the base class so that if there is a specified variable to modify, an inequality is included to ensure that the output type is greater than or equal to the type of that variable.

Methods inherited from class ptolemy.actor.TypedAtomicActor

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

Methods inherited from class ptolemy.actor.AtomicActor

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

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, attributeChanged, 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.kernel.util.Nameable

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

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, stop, stopFire, terminate

Methods inherited from interface ptolemy.actor.Initializable

addInitializable, initialize, removeInitializable, wrapup

Methods inherited from interface ptolemy.kernel.util.Derivable

getDerivedLevel, getDerivedList, propagateValue

Field Detail

delayed

public Parameter delayed

Parameter that determines when reconfiguration occurs.

input

public TypedIOPort input

The input port.

output

public TypedIOPort output

The output port.

variableName

public StringAttribute variableName

The name of the variable in the container to set.

_attribute

private Attribute _attribute

Cached reference to the associated variable.

_attributeVersion

private long _attributeVersion

Workspace version for the cached attribute reference.

_setFailed

private boolean _setFailed

Indicator that setting the variable failed.

Constructor Detail

SetVariable

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

Construct an actor with the given container and name.

Parameters:

container - The container.

name - The name of this actor.

Throws:

IllegalActionException - If this actor cannot be contained by the proposed container.

NameDuplicationException - If the container already has an actor with this name.

Method Detail

changeExecuted

public void changeExecuted(ChangeRequest change)

Do nothing.

Specified by:

changeExecuted in interface ChangeListener

Parameters:

change - The change that executed.

changeFailed

public void changeFailed(ChangeRequest change,
                         java.lang.Exception exception)

React to the fact that a change failed by setting a flag that causes an exception to be thrown in next call to prefire() or wrapup().

Specified by:

changeFailed in interface ChangeListener

Parameters:

change - The change request.

exception - The exception that resulted.

fire

public void fire()
          throws IllegalActionException

Read at most one token from the input port and issue a change request to update variables as indicated by the input.

Specified by:

fire in interface Executable

Overrides:

fire in class AtomicActor

Throws:

IllegalActionException - If thrown reading the input.

getContext

public Entity getContext()

Return the change context being made explicit. In this case, the change context returned is this actor.

Specified by:

getContext in interface ExplicitChangeContext

Returns:

The change context being made explicit

getModifiedVariable

public Attribute getModifiedVariable()
                              throws IllegalActionException

Return the (presumably Settable) attribute modified by this actor. This is the attribute in the container of this actor with the name given by the variableName attribute. If no such attribute is found, then this method creates a new variable in the actor's container with the correct name. This method gets write access on the workspace.

Returns:

The attribute modified by this actor.

Throws:

IllegalActionException - If the variable cannot be found.

getModifiedVariables

public java.util.List getModifiedVariables()
                                    throws IllegalActionException

Return a list of variables that this entity modifies. The variables are assumed to have a change context of the given entity.

Specified by:

getModifiedVariables in interface ExplicitChangeContext

Returns:

A list of variables.

Throws:

IllegalActionException - If the list of modified variables cannot be returned.

postfire

public boolean postfire()
                 throws IllegalActionException

Read at most one token from the input port and issue a change request to update variables as indicated by the input.

Specified by:

postfire in interface Executable

Overrides:

postfire in class AtomicActor

Returns:

True if execution can continue into the next iteration.

Throws:

IllegalActionException - If thrown reading the input.

preinitialize

public void preinitialize()
                   throws IllegalActionException

If there is no variable with the specified name, then create one. This is done in preinitialize() so that we can set up a type constraint that ensures that the type of the variable is at least that of the input port.

Specified by:

preinitialize in interface Initializable

Overrides:

preinitialize in class AtomicActor

Throws:

IllegalActionException - If the superclass throws it, or if there is no container.

typeConstraints

public java.util.Set<Inequality> typeConstraints()

Override the base class so that if there is a specified variable to modify, an inequality is included to ensure that the output type is greater than or equal to the type of that variable. Strictly speaking, this is necessary only if the delay parameter is set to true, because in that case, on the first firing, this actor will produce a token whose value is whatever the initial value of the parameter is.

Specified by:

typeConstraints in interface TypedActor

Overrides:

typeConstraints in class TypedAtomicActor

Returns:

A set of type constraints.

See Also:

Inequality

_setValue

private void _setValue(Token value)
                throws IllegalActionException

Set the value of the associated container's variable.

Parameters:

value - The new value.

Throws:

IllegalActionException