ptolemy.actor
Class AtomicActor

java.lang.Object
  extended byptolemy.kernel.util.NamedObj
      extended byptolemy.kernel.InstantiableNamedObj
          extended byptolemy.kernel.Entity
              extended byptolemy.kernel.ComponentEntity
                  extended byptolemy.actor.AtomicActor
All Implemented Interfaces:
Actor, Changeable, java.lang.Cloneable, Debuggable, DebugListener, Derivable, Executable, Instantiable, ModelErrorHandler, MoMLExportable, Nameable, java.io.Serializable
Direct Known Subclasses:
CSPSink, CSPSource, TypedAtomicActor

public class AtomicActor
extends ComponentEntity
implements Actor

An AtomicActor is an executable entity that cannot itself contain other actors. The Ports of AtomicActors are constrained to be IOPorts. Derived classes may further constrain the ports by overriding the public method newPort() to create a port of the appropriate subclass, and the protected method _addPort() to throw an exception if its argument is a port that is not of the appropriate subclass. In this base class, the actor does nothing in the action methods (prefire, fire, ...).

Since:
Ptolemy II 0.2
Version:
$Id: AtomicActor.java,v 1.95.2.2 2004/06/20 03:10:42 cxh Exp $
Author:
Mudit Goel, Edward A. Lee, Lukito Muliadi, Steve Neuendorffer
See Also:
CompositeActor, IOPort, Serialized Form
Accepted Rating:
Green (neuendor)
Proposed Rating:
Green (eal)

Nested Class Summary
 
Nested classes inherited from class ptolemy.kernel.Entity
Entity.ContainedObjectsIterator
 
Field Summary
protected  boolean _stopRequested
          Indicator that a stop has been requested by a call to stop().
 
Fields inherited from class ptolemy.kernel.util.NamedObj
_changeListeners, _changeLock, _changeRequests, _debugging, _debugListeners, _elementName, _isPersistent, _workspace, ATTRIBUTES, CLASSNAME, COMPLETE, CONTENTS, DEEP, FULLNAME, LINKS
 
Fields inherited from interface ptolemy.actor.Executable
COMPLETED, NOT_READY, STOP_ITERATING
 
Constructor Summary
AtomicActor()
          Construct an actor in the default workspace with an empty string as its name.
AtomicActor(CompositeEntity container, java.lang.String name)
          Create a new actor in the specified container with the specified name.
AtomicActor(Workspace workspace)
          Construct an actor in the specified workspace with an empty string as a name.
 
Method Summary
protected  void _addPort(Port port)
          Override the base class to throw an exception if the added port is not an instance of IOPort.
protected  void _createReceivers()
           
 java.lang.Object clone(Workspace workspace)
          Clone this actor into the specified workspace.
 void connectionsChanged(Port port)
          Create new receivers if the port is an input port and there is a director.
 void fire()
          Do nothing.
 Director getDirector()
          Return the director responsible for the execution of this actor.
 Director getExecutiveDirector()
          Return the executive director (same as getDirector()).
 FunctionDependency getFunctionDependency()
          Return a representation of the function dependencies that output ports have on input ports.
 Manager getManager()
          Return the Manager responsible for execution of this actor, if there is one.
 void initialize()
          Initialize this actor.
 java.util.List inputPortList()
          List all the input ports.
 int iterate(int count)
          Invoke a specified number of iterations of the actor.
 Port newPort(java.lang.String name)
          Create a new IOPort with the specified name.
 Receiver newReceiver()
          Return a new receiver of a type compatible with the director.
 java.util.List outputPortList()
          List the output ports.
 boolean postfire()
          Return true, unless stop() has been called, in which case, return false.
 boolean prefire()
          Return true.
 void preinitialize()
          Create receivers.
 void pruneDependencies()
          Prune the dependency declarations, which by default state that each output port depends on all input ports in a firing.
 void removeDependency(IOPort input, IOPort output)
          Remove the dependency that the specified output port has, by default, on the specified input port.
 void setContainer(CompositeEntity container)
          Override the base class to invalidate the schedule and resolved types of the director.
 void stop()
          Request that execution of the current iteration stop as soon as possible.
 void stopFire()
          Request that execution of the current iteration complete.
 void terminate()
          Terminate execution immediately.
 void wrapup()
          Do nothing.
 
Methods inherited from class ptolemy.kernel.ComponentEntity
_adjustDeferrals, _checkContainer, _getContainedObject, _propagateExistence, getContainer, instantiate, isAtomic, isOpaque, propagateExistence, setName
 
Methods inherited from class ptolemy.kernel.Entity
_description, _exportMoMLContents, _removePort, connectedPortList, connectedPorts, containedObjectsIterator, getAttribute, getPort, getPorts, linkedRelationList, linkedRelations, portList, removeAllPorts, setClassDefinition, uniqueName, validateSettables
 
Methods inherited from class ptolemy.kernel.InstantiableNamedObj
_setParent, exportMoML, getChildren, getElementName, getParent, getPrototypeList, isClassDefinition
 
Methods inherited from class ptolemy.kernel.util.NamedObj
_addAttribute, _attachText, _cloneFixAttributeFields, _debug, _debug, _debug, _debug, _debug, _getIndentPrefix, _isMoMLSuppressed, _markContentsDerived, _propagateValue, _removeAttribute, _splitName, _stripNumericSuffix, addChangeListener, addDebugListener, attributeChanged, attributeList, attributeList, attributeTypeChanged, clone, deepContains, depthInHierarchy, description, description, event, executeChangeRequests, exportMoML, exportMoML, exportMoML, exportMoML, getAttribute, getAttributes, getChangeListeners, getClassName, getDerivedLevel, getDerivedList, getFullName, getModelErrorHandler, getName, getName, getSource, handleModelError, isDeferringChangeRequests, isOverridden, isPersistent, message, propagateValue, propagateValues, removeChangeListener, removeDebugListener, requestChange, setClassName, setDeferringChangeRequests, setDerivedLevel, setModelErrorHandler, setPersistent, setSource, toplevel, toString, workspace
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface ptolemy.kernel.util.Derivable
getDerivedLevel, getDerivedList, propagateValue
 
Methods inherited from interface ptolemy.kernel.util.Nameable
description, getFullName, getName, getName
 

Field Detail

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

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
Parameters:
port - The port that has connection changes.

fire

public void fire()
          throws IllegalActionException
Do nothing. Derived classes override this method to define their their primary run-time action.

Specified by:
fire in interface Executable
Throws:
IllegalActionException - Not thrown in this base class.

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.

getFunctionDependency

public FunctionDependency getFunctionDependency()
Return a representation of the function dependencies that output ports have on input ports.

Specified by:
getFunctionDependency in interface Actor
Returns:
A representation of the function dependencies of the ports of this actor.
See Also:
FunctionDependency

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 Executable
Throws:
IllegalActionException - If a derived class throws it.

inputPortList

public java.util.List 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.

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
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 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. 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 Executable
Throws:
IllegalActionException - Not thrown in this base class.

pruneDependencies

public void pruneDependencies()
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 should call removeDependency(input, output).

See Also:
TimedDelay, removeDependency(IOPort, IOPort), FunctionDependencyOfAtomicActor

removeDependency

public void removeDependency(IOPort input,
                             IOPort output)
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 should call this method inside their override of the pruneDependencies() method if a particular output port does not depend on data from a particular input port in a firing. 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.
See Also:
FunctionDependencyOfAtomicActor

setContainer

public void setContainer(CompositeEntity container)
                  throws IllegalActionException,
                         NameDuplicationException
Override the base class to invalidate the schedule and resolved types of the director.

Overrides:
setContainer in class ComponentEntity
Parameters:
container - The proposed container.
Throws:
IllegalActionException - If the action would result in a recursive containment structure, or if this entity and container are not in the same workspace.
NameDuplicationException - If the container already has an entity with the name of this entity.
See Also:
ComponentEntity.getContainer()

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. 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 Executable
Throws:
IllegalActionException - Not thrown in this base class.

_addPort

protected void _addPort(Port port)
                 throws IllegalActionException,
                        NameDuplicationException
Override the base class to throw an exception if the added port is not an instance of IOPort. This method should not be used directly. Call the setContainer() method of the port instead. This method does not set the container of the port to point to this entity. It assumes that the port is in the same workspace as this entity, but does not check. The caller should check. Derived classes may override this method to further constrain to a subclass of IOPort. This method is not synchronized on the workspace, so the caller should be.

Overrides:
_addPort in class ComponentEntity
Parameters:
port - The port to add to this entity.
Throws:
IllegalActionException - If the port class is not acceptable to this entity, or the port has no name.
NameDuplicationException - If the port name coincides with a name already in the entity.

_createReceivers

protected void _createReceivers()
                         throws IllegalActionException
Throws:
IllegalActionException