Package ptolemy.actor

Class AtomicActor<T extends IOPort>

    • Field Detail

      • _actorFiringListeners

        protected java.util.LinkedList<ActorFiringListener> _actorFiringListeners
        The list of ActorFiringListeners registered with this object. NOTE: Because of the way we synchronize on this object, it should never be reset to null after the first list is created.

      • _initializables

        protected transient java.util.Set<Initializable> _initializables
        List of objects whose (pre)initialize() and wrapup() methods should be slaved to these.

      • _notifyingActorFiring

        protected boolean _notifyingActorFiring
        Flag that is true if there are actor firing listeners.

      • _stopRequested

        protected boolean _stopRequested
        Indicator that a stop has been requested by a call to stop().

    • Constructor Detail

      • AtomicActor

        public AtomicActor()
        Construct an actor in the default workspace with an empty string as its name. Increment the version number of the workspace. The object is added to the workspace directory.

      • AtomicActor

        public AtomicActor​(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 this actor.

      • AtomicActor

        public AtomicActor​(CompositeEntity container,
                   java.lang.String name)
            throws IllegalActionException,
                   NameDuplicationException
        Create a new actor in the specified container with the specified name. The name must be unique within the container or an exception is thrown. The container argument must not be null, or a NullPointerException will be thrown.
        Parameters:
        container - The container.
        name - The name of this actor within the container.
        Throws:
        IllegalActionException - If the entity cannot be contained by the proposed container (see the setContainer() method).
        NameDuplicationException - If the name coincides with an entity already in the container.

    • Method Detail

      • clone

        public java.lang.Object clone​(Workspace workspace)
                       throws java.lang.CloneNotSupportedException
        Clone this actor into the specified workspace. The new actor is not added to the directory of that workspace (you must do this yourself if you want it there). The result is a new actor with the same ports as the original, but no connections and no container. A container must be set before much can be done with this actor.
        Overrides:
        clone in class ComponentEntity<T extends IOPort>
        Parameters:
        workspace - The workspace for the cloned object.
        Returns:
        A new ComponentEntity.
        Throws:
        java.lang.CloneNotSupportedException - If cloned ports cannot have as their container the cloned entity (this should not occur), or if one of the attributes cannot be cloned.
        See Also:
        NamedObj.exportMoML(Writer, int, String), NamedObj.setDeferringChangeRequests(boolean)

      • connectionsChanged

        public void connectionsChanged​(Port port)
        Create new receivers if the port is an input port and there is a director.
        Overrides:
        connectionsChanged in class Entity<T extends IOPort>
        Parameters:
        port - The port that has connection changes.

      • declareDelayDependency

        public void declareDelayDependency()
                            throws IllegalActionException
        Set the dependency between all output ports and all input ports of this actor. By default, each output port is assumed to have a dependency on all input ports. Since this is the assumed behavior, this method does nothing by default. However, for subclasses such as TimeDelay, where output ports depend on input ports with a time delay, this method should be overridden. Protected method _declareDelayDependency() should be used to declare dependency between input and output ports for this actor.
        Throws:
        IllegalActionException - Not thrown in this base class, derived classes should throw this exception if the delay dependency cannot be computed.
        See Also:
        getCausalityInterface(), _declareDelayDependency(IOPort, IOPort, double)

      • getDirector

        public Director getDirector()
        Return the director responsible for the execution of this actor. In this class, this is always the executive director. Return null if either there is no container or the container has no director.
        Specified by:
        getDirector in interface Actor
        Returns:
        The director that invokes this actor.

      • getExecutiveDirector

        public Director getExecutiveDirector()
        Return the executive director (same as getDirector()).
        Specified by:
        getExecutiveDirector in interface Actor
        Returns:
        The executive director.

      • getManager

        public Manager getManager()
        Return the Manager responsible for execution of this actor, if there is one. Otherwise, return null.
        Specified by:
        getManager in interface Actor
        Returns:
        The manager.

      • initialize

        public void initialize()
                throws IllegalActionException
        Initialize this actor. Derived classes override this method to perform actions that should occur once at the beginning of an execution, but after type resolution. Derived classes can produce output data and schedule events.
        Specified by:
        initialize in interface Initializable
        Throws:
        IllegalActionException - If a derived class throws it.

      • inputPortList

        public java.util.List<T> inputPortList()
        List all the input ports. This method is read-synchronized on the workspace.
        Specified by:
        inputPortList in interface Actor
        Returns:
        A list of input IOPort objects.

      • isFireFunctional

        public boolean isFireFunctional()
        Return true. Most actors are written so that the prefire() and fire() methods do not change the state of the actor. Hence, for convenience, this base class by default returns true. An actor that does change state in prefire() or fire() must override this method to return false.
        Specified by:
        isFireFunctional in interface Executable
        Returns:
        True.

      • isStrict

        public boolean isStrict()
                 throws IllegalActionException
        Return true unless all input ports have non-empty default values. By default, most actors do not check their inputs to see whether they are known. They assume they are known. Note that ParameterPort is not treated as having a default value because such ports might be used in a context where it is important to supply them with an input value.
        Specified by:
        isStrict in interface Executable
        Returns:
        False if this actor does not need to be provided with inputs to fire.
        Throws:
        IllegalActionException - If the defaultValue expression cannot be evaluated for an input port.

      • iterate

        public int iterate​(int count)
            throws IllegalActionException
        Invoke a specified number of iterations of the actor. An iteration is equivalent to invoking prefire(), fire(), and postfire(), in that order. In an iteration, if prefire() returns true, then fire() will be called once, followed by postfire(). Otherwise, if prefire() returns false, fire() and postfire() are not invoked, and this method returns NOT_READY. If postfire() returns false, then no more iterations are invoked, and this method returns STOP_ITERATING. Otherwise, it returns COMPLETED. If stop() is called while this is executing, then cease executing and return STOP_ITERATING.

        This base class method actually invokes prefire(), fire(), and postfire(), as described above, but a derived class may override the method to execute more efficient code.

        Specified by:
        iterate in interface Executable
        Parameters:
        count - The number of iterations to perform.
        Returns:
        NOT_READY, STOP_ITERATING, or COMPLETED.
        Throws:
        IllegalActionException - If iterating is not permitted, or if prefire(), fire(), or postfire() throw it.

      • newPort

        public Port newPort​(java.lang.String name)
             throws NameDuplicationException
        Create a new IOPort with the specified name. The container of the port is set to this actor. This method is write-synchronized on the workspace. Normally this method is not called directly by actor code. Instead, a change request should be queued with the director.
        Overrides:
        newPort in class ComponentEntity<T extends IOPort>
        Parameters:
        name - The name for the new port.
        Returns:
        The new port.
        Throws:
        NameDuplicationException - If this actor already has a port with the specified name.
        See Also:
        Workspace.getWriteAccess()

      • newReceiver

        public Receiver newReceiver()
                     throws IllegalActionException
        Return a new receiver of a type compatible with the director. Derived classes may further specialize this to return a receiver specialized to the particular actor.
        Specified by:
        newReceiver in interface Actor
        Returns:
        A new object implementing the Receiver interface.
        Throws:
        IllegalActionException - If there is no director.

      • outputPortList

        public java.util.List<T> outputPortList()
        List the output ports. This method is read-synchronized on the workspace.
        Specified by:
        outputPortList in interface Actor
        Returns:
        A list of output IOPort objects.

      • postfire

        public boolean postfire()
                 throws IllegalActionException
        Return true, unless stop() has been called, in which case, return false. Derived classes override this method to define operations to be performed at the end of every iteration of its execution, after one invocation of the prefire() method and any number of invocations of the fire() method. This method typically wraps up an iteration, which may involve updating local state. In derived classes, this method returns false to indicate that this actor should not be fired again.
        Specified by:
        postfire in interface Executable
        Returns:
        True if execution can continue into the next iteration.
        Throws:
        IllegalActionException - Not thrown in this base class.

      • prefire

        public boolean prefire()
                throws IllegalActionException
        Return true. Derived classes override this method to define operations to be performed at the beginning of every iteration of its execution, prior the invocation of the fire() method. Derived classes may also use it to check preconditions for an iteration, if there are any.
        Specified by:
        prefire in interface Executable
        Returns:
        True if this actor is ready for firing, false otherwise.
        Throws:
        IllegalActionException - Not thrown in this base class.

      • preinitialize

        public void preinitialize()
                   throws IllegalActionException
        Create receivers and declare delay dependencies. Derived classes can override this method to perform additional initialization functions, but they should call this base class methods or create the receivers themselves. This method gets executed exactly once prior to any other action methods. It cannot produce output data since type resolution is typically not yet done. It also gets invoked prior to any static scheduling that might occur in the domain, so it can change scheduling information.
        Specified by:
        preinitialize in interface Initializable
        Throws:
        IllegalActionException - Not thrown in this base class.

      • pruneDependencies

        @Deprecated
public void pruneDependencies()
                       throws IllegalActionException
        Deprecated.
        There is no need to override this method anymore. Just call removeDependency() in preinitialize().
        Prune the dependency declarations, which by default state that each output port depends on all input ports in a firing. This base class does no pruning, but subclasses that have output ports that do not depend on input ports should override this method to prune the dependencies. To declare that an output port does not depend on an input port, subclasses can call removeDependency(input, output) rather than implementing a specialized CausalityInterface, at least for the simple cases where output ports do not depend at all on input ports.
        Throws:
        IllegalActionException - Thrown by subclasses if causality interface cannot be computed.
        See Also:
        removeDependency(IOPort, IOPort), getCausalityInterface()

      • removeActorFiringListener

        public void removeActorFiringListener​(ActorFiringListener listener)
        Unregister an actor firing listener. If the specified listener has not been previously registered, then do nothing. Note that this method is basically the same as removeDebugListener in the class NamedObj.
        Specified by:
        removeActorFiringListener in interface FiringsRecordable
        Parameters:
        listener - The listener to remove from the list of listeners to which actor firing messages are sent.
        See Also:
        addActorFiringListener(ActorFiringListener)

      • removeDependency

        public void removeDependency​(IOPort input,
                             IOPort output)
                      throws IllegalActionException
        Remove the dependency that the specified output port has, by default, on the specified input port. By default, each output port is assumed to have a dependency on all input ports. Subclasses can call this method in preinitialize() instead of implementing a custom CausalityInterface for the simple cases where output ports do not depend at all on certain input ports. There should be one such call for each input, output pair that does not have a dependency.
        Parameters:
        input - The input port.
        output - The output port that does not depend on the input port.
        Throws:
        IllegalActionException - If causality interface cannot be computed.
        See Also:
        getCausalityInterface()

      • stop

        public void stop()
        Request that execution of the current iteration stop as soon as possible. In this base class, we set a flag indicating that this request has been made (the protected variable _stopRequested). Most atomic actors have bounded fire() methods, so they can simply ignore this. Atomic actors with unbounded fire() methods should react by saving their state and returning from the fire() method at the next convenient point.
        Specified by:
        stop in interface Executable

      • stopFire

        public void stopFire()
        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

      • terminate

        public void terminate()
        Terminate execution immediately. In this base class, call stop(). Derived classes may wish to do something more aggressive, such as terminating any threads they have started.
        Specified by:
        terminate in interface Executable

      • wrapup

        public void wrapup()
            throws IllegalActionException
        Do nothing except invoke the wrapup() methods of any objects that have been registered with addInitializable(). Derived classes override this method to define operations to be performed exactly once at the end of a complete execution of an application. It typically closes files, displays final results, etc.
        Specified by:
        wrapup in interface Initializable
        Throws:
        IllegalActionException - Not thrown in this base class.

      • _actorFiring

        protected final void _actorFiring​(FiringEvent event)
        Send an actor firing event to all actor firing listeners that have registered with this actor.
        Parameters:
        event - The event.

      • _actorFiring

        protected final void _actorFiring​(FiringEvent.FiringEventType type,
                                  int multiplicity)
        Send an actor firing event type to all actor firing listeners that have registered with this actor.
        Parameters:
        type - The type.
        multiplicity - The multiplicity of the firing, that is, the number of times the firing will occur or has occurred.

      • _declareDelayDependency

        protected void _declareDelayDependency​(IOPort input,
                                       IOPort output,
                                       double timeDelay)
                                throws IllegalActionException
        Set the dependency between the input and output port to represent a time delay with the specified value. Subclasses can call this method instead of implementing a custom CausalityInterface for the cases where output ports depend on input ports with a time delay. If the time delay is 0.0, this method nonetheless assumes that the output port does not (immediately) depend on the input port (this amounts to a superdense time delay of (0.0, 1)). There should be one such call for each input, output pair that does not have a dependency.
        Parameters:
        input - The input port.
        output - The output port with a time delay dependency on the input port.
        timeDelay - The time delay.
        Throws:
        IllegalActionException - If causality interface cannot be computed.
        See Also:
        getCausalityInterface()