Package ptolemy.actor.lib

Class SetVariable

  • All Implemented Interfaces:
    java.lang.Cloneable, Actor, Executable, FiringsRecordable, Initializable, TypedActor, ExplicitChangeContext, Changeable, ChangeListener, Debuggable, DebugListener, Derivable, Instantiable, ModelErrorHandler, MoMLExportable, Moveable, Nameable
    Direct Known Subclasses:
    SequencedSharedMemoryActor
    public class SetVariable
extends TypedAtomicActor
implements ChangeListener, ExplicitChangeContext

    Set the value of a variable. If there is a variable or parameter in scope with a name matching variableName, then that variable is the one to be set. If there is no such variable, then one will be created in the container of this actor. A variable is in scope if it is contained by the container, the container's container, or any container above in the hierarchy. NOTE: We recommend always creating a parameter with a name matching variableName, because then the model is explicit about which variable will be set. It also makes it easier to monitor the variable updates.

    The update to the variable 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. 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 any attribute that implements the Settable interface, which includes Parameter. If it is in addition an instance of Variable or Parameter, 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.

    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$
    Author:
    Edward A. Lee, Steve Neuendorffer, Contributor: Blanc, Bert Rodiers
    See Also:
    Publisher, Subscriber
    Pt.AcceptedRating:
    Red (cxh)
    Pt.ProposedRating:
    Red (yuhong)

    • Field Detail

      • delayed

        public Parameter delayed
        Parameter that determines when reconfiguration occurs.

      • variableName

        public StringAttribute variableName
        The name of the variable in the container to set.

    • Constructor Detail

      • SetVariable

        public SetVariable​(Workspace workspace)
        Construct an actor in the specified workspace with an empty string as a name. You can then change the name with setName(). If the workspace argument is null, then use the default workspace. The object is added to the workspace directory. Increment the version number of the workspace.
        Parameters:
        workspace - The workspace that will list the entity.

    • Method Detail

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

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

      • _customTypeConstraints

        protected java.util.Set<Inequality> _customTypeConstraints()
        Return a constraint requiring that if there is a specified variable to modify, the type of that variable is less than or equal to the type of the output port.
        Overrides:
        _customTypeConstraints in class TypedAtomicActor
        Returns:
        A set of type constraints.