Package ptolemy.actor.lib.hoc

Class RunCompositeActor

  • All Implemented Interfaces:
    java.lang.Cloneable, Actor, Executable, FiringsRecordable, Initializable, TypedActor, Changeable, Debuggable, DebugListener, Derivable, Instantiable, ModelErrorHandler, MoMLExportable, Moveable, Nameable
    Direct Known Subclasses:
    ExecuteActor
    public class RunCompositeActor
extends LifeCycleManager
    This is a composite actor that can execute the contained model completely, as if it were a top-level model, on each firing. This can be used to define an actor whose firing behavior is given by a complete execution of a submodel.

    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 contained 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 this actor has a parameter 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 contained model is executed, then upon completion of that execution, if this actor has parameters whose names match those of the output ports, 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 token. 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. Output ports should not be multiports. If they are, then all but the first channel will be ignored. A typical use of this actor will use the SetVariable actor inside to define the value of the output port.

    In preinitialize(), type constraints are set up so that input and output ports with (name) matching parameters are constrained to have compatible types. Note that if the ports or parameters are changed during execution, then it will be necessary to set up matching type constraints by hand. Since this isn't possible to do from Vergil, the ports and parameters of this actor should not be changed using Vergil during execution.

    This actor also overrides the requestChange() method and the executeChangeRequests() method to execute the given change. It does not delegate the change request to the container, but executes the request immediately or records it, depending on whether setDeferringChangeRequests() has been called with a true argument.

    Since:
    Ptolemy II 4.0
    Version:
    $Id$
    Author:
    Edward A. Lee, Yang Zhao, Elaine Cheong
    See Also:
    ModelReference, SetVariable
    Pt.AcceptedRating:
    Red (eal)
    Pt.ProposedRating:
    Yellow (eal)

    • Field Detail

      • firingCountLimit

        public Parameter firingCountLimit
        Indicator to run the contained model a limited number of times. If this parameter has a value greater than zero, then after executing the inside model the specified number of times, postfire() will return false. This is an int that defaults to 0, which means that there is no limit.

    • Constructor Detail

      • RunCompositeActor

        public RunCompositeActor()
                  throws IllegalActionException,
                         NameDuplicationException
        Construct an actor in the default workspace with no container and an empty string as its name. Add the actor to the workspace directory. You should set the local director or executive director before attempting to send data to the actor or to execute it. Increment the version number of the workspace.
        Throws:
        NameDuplicationException - If there is already a parameter with name firingCountLimit.
        IllegalActionException - If the firingCountLimit cannot be initialized.

      • RunCompositeActor

        public RunCompositeActor​(Workspace workspace)
                  throws IllegalActionException,
                         NameDuplicationException
        Construct a RunCompositeActor in the specified workspace with no container and 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. You should set the local director or executive director before attempting to send data to the actor or to execute it. Add the actor to the workspace directory. Increment the version number of the workspace.
        Parameters:
        workspace - The workspace that will list the actor.
        Throws:
        NameDuplicationException - If there is already a parameter with name firingCountLimit.
        IllegalActionException - If the firingCountLimit cannot be initialized.

      • RunCompositeActor

        public RunCompositeActor​(CompositeEntity container,
                         java.lang.String name)
                  throws IllegalActionException,
                         NameDuplicationException
        Construct a RunCompositeActor 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

      • fire

        public void fire()
          throws IllegalActionException
        Run a complete execution of the contained 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 calls the director's transferInputs() method to read any available inputs. After running the complete execution, it calls transferOutputs(). The subclass of this can set the _isSubclassOfRunCompositeActor to be true to call the fire method of the superclass of this.
        Specified by:
        fire in interface Executable
        Overrides:
        fire in class CompositeActor
        Throws:
        IllegalActionException - If there is no director, or if the director's action methods throw it.

      • initialize

        public void initialize()
                throws IllegalActionException
        Initialize this actor, which in this case, does nothing. The initialization of the submodel is accomplished in fire(). The subclass of this can set the _isSubclassOfRunCompositeActor to be true to call the initialize method of the superclass of this.
        Specified by:
        initialize in interface Initializable
        Overrides:
        initialize in class CompositeActor
        Throws:
        IllegalActionException - Not thrown in this base class, but declared so the subclasses can throw it.

      • postfire

        public boolean postfire()
                 throws IllegalActionException
        Return true, indicating that execution can continue. The subclass of this can set the _isSubclassOfRunCompositeActor to be true to call the postfire method of the superclass of this.
        Specified by:
        postfire in interface Executable
        Overrides:
        postfire in class CompositeActor
        Returns:
        True if the execution can continue into the next iteration.
        Throws:
        IllegalActionException - Not thrown in this base class, but declared so the subclasses can throw it.

      • preinitialize

        public void preinitialize()
                   throws IllegalActionException
        Override the base class to set type constraints between the output ports and parameters of this actor whose name matches the output port. If there is no such parameter, then create an instance of Variable with a matching name and set up the type constraints to that instance. The type of the output port is constrained to be at least that of the parameter or variable.
        Specified by:
        preinitialize in interface Initializable
        Overrides:
        preinitialize in class CompositeActor
        Throws:
        IllegalActionException - If there is no director, or if the director's preinitialize() method throws it, or if this actor is not opaque.