ptolemy.domains.csp.kernel
Class CSPActor

java.lang.Object
  ptolemy.kernel.util.NamedObj
      ptolemy.kernel.InstantiableNamedObj
          ptolemy.kernel.Entity
              ptolemy.kernel.ComponentEntity
                  ptolemy.actor.AtomicActor
                      ptolemy.actor.TypedAtomicActor
                          ptolemy.domains.csp.kernel.CSPActor

All Implemented Interfaces:

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

Direct Known Subclasses:

Buffer, CSPBuffer, CSPMultiSink, CSPMultiSource, CSPSieve, ResourcePool

public class CSPActor
extends TypedAtomicActor
implements BranchActor

This class is the base class of all atomic actors using the non-deterministic communication and timed features of the communicating sequential processes(CSP) domain.

Two conditional communication constructs are available: "Conditional if" (CIF) and "Conditional do" (CDO). The constructs are analogous to, but different from, the common if and do statements. The steps involved in using both of these are
(1) create the branches involved and assign an identification number to each branch.
(2) call the chooseBranch() method, which invokes the chooseBranch() method of the controller to determine which branch should succeed.
(3) execute the statements associated with the successful branch.

Each branch is either an instance of ConditionalSend or ConditionalReceive, depending on the communication in the branch. Please see these classes for details on guarded communication statements, which they represent. The identification number assigned to each branch only needs to identify the branch uniquely for one sequence of the steps above. A good example of how to use a CDO is the code in the actor CSPBuffer, in the ptolemy.domains.csp.lib package. One significant difference between a CDO (or CIF) and a common do (if) is that all the branches are evaluated in parallel, as opposed to sequentially.

The chooseBranch() method takes an array of the branches as an argument, and simply passes the branches to the chooseBranch() method of the controller to decide which branch is successful. The successful branch is the branch that succeeds with its communication. See the chooseBranch() method of ConditionalBranchController for details about how the successful branch is chosen.

Time is supported by the method delay(double). This delays the process until time has advanced the argument time from the current model time. If this method is called with a zero argument, then the process continues immediately. As far as each process is concerned, time can only increase while the process is blocked trying to rendezvous or when it is delayed. A process can be aware of the current model time, but it should only affect the model time through delays. Thus time is centralized in that it is advanced by the director controlling the process represented by this actor.

A process can also choose to delay its execution until the next occasion a deadlock occurs by calling _waitForDeadlock(). The process resumes at the same model time at which it delayed. This is useful if a process wishes to delay itself until some changes to the topology have been carried out.

The model of computation used in this domain extends the original CSP, as proposed by Hoare in 1978, model of computation in two ways. First it allows non-deterministic communication using both sends and receives. The original model only allowed non-deterministic receives. Second, a centralized notion of time has been added. The original proposal was untimed. Neither of these extensions are new, but it is worth noting the differences between the model used here and the original model. If an actor wishes to use either non-deterministic rendezvous or time, it must derive from this class. Otherwise deriving from AtomicActor is sufficient.

Since:

Ptolemy II 0.2

Version:

$Id: CSPActor.java 57040 2010-01-27 20:52:32Z cxh $

Author:

Neil Smyth, Bilung Lee

See Also:

ConditionalBranch, ConditionalReceive, ConditionalSend, Serialized Form

Accepted Rating:

Yellow (liuj)

Proposed Rating:

Green (nsmyth)

Nested Class Summary

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

Entity.ContainedObjectsIterator

Field Summary

private boolean	_cancelDelay Flag that causes the delay() method to abort with an exception.
private ConditionalBranchController	_conditionalBranchController This object is in charge of all conditional rendezvous issues.
private boolean	_delayed Flag indicating this actor is delayed.

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

CSPActor()
Construct a CSPActor in the default workspace with an empty string as its name.

CSPActor(CompositeEntity container, java.lang.String name)
Construct a CSPActor in the specified container with the specified name.

CSPActor(Workspace workspace)
Construct a CSPActor in the specified workspace with an empty string as a name.

Method Summary

protected void	_cancelDelay() If the actor is delayed, then cancel the delay.
protected void	_continue() Resume a delayed actor.
protected void	_waitForDeadlock() Wait for deadlock to occur.
int	chooseBranch(ConditionalBranch[] branches) Determine which branch succeeds with a rendezvous.
java.lang.Object	clone(Workspace workspace) Clone this actor into the specified workspace.
void	delay(double delta) Delay this actor.
AbstractBranchController	getBranchController() Return the conditional branch control of this actor.
void	initialize() Initialize the state of the actor.
boolean	postfire() Return false.
void	terminate() Terminate abruptly any threads created by this actor.

Methods inherited from class ptolemy.actor.TypedAtomicActor

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

Methods inherited from class ptolemy.actor.AtomicActor

_actorFiring, _actorFiring, addActorFiringListener, addInitializable, connectionsChanged, createReceivers, declareDelayDependency, fire, getCausalityInterface, getDirector, getExecutiveDirector, getManager, inputPortList, isFireFunctional, isStrict, iterate, newReceiver, outputPortList, prefire, preinitialize, pruneDependencies, recordFiring, removeActorFiringListener, removeDependency, removeInitializable, setContainer, stop, stopFire, 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.actor.Actor

createReceivers, getCausalityInterface, getDirector, getExecutiveDirector, getManager, inputPortList, newReceiver, outputPortList

Methods inherited from interface ptolemy.actor.Executable

fire, isFireFunctional, isStrict, iterate, prefire, stop, stopFire

Methods inherited from interface ptolemy.actor.Initializable

addInitializable, preinitialize, removeInitializable, wrapup

Methods inherited from interface ptolemy.kernel.util.Nameable

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

Methods inherited from interface ptolemy.kernel.util.Derivable

getDerivedLevel, getDerivedList, propagateValue

Field Detail

_cancelDelay

private boolean _cancelDelay

Flag that causes the delay() method to abort with an exception.

_conditionalBranchController

private ConditionalBranchController _conditionalBranchController

This object is in charge of all conditional rendezvous issues.

_delayed

private boolean _delayed

Flag indicating this actor is delayed.

Constructor Detail

CSPActor

public CSPActor()

Construct a CSPActor in the default workspace with an empty string as its name. The object is added to the workspace directory. Increment the version number of the workspace.

CSPActor

public CSPActor(Workspace workspace)

Construct a CSPActor 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.

CSPActor

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

Construct a CSPActor 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 TypedCompositeActor that contains this actor.

name - The actor's name.

Throws:

IllegalActionException - If the entity cannot be contained by the proposed container.

NameDuplicationException - If the name argument coincides with an entity already in the container.

Method Detail

chooseBranch

public int chooseBranch(ConditionalBranch[] branches)
                 throws IllegalActionException

Determine which branch succeeds with a rendezvous. Pass the branches to ConditionalBranchController to decide.

Parameters:

branches - The set of conditional branches involved.

Returns:

The ID of the successful branch, or -1 if none of the branches were enabled.

Throws:

IllegalActionException - If the rendezvous fails (e.g. because of incompatible types).

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 number of ports (cloned) as the original, but no connections and no container. A container must be set before much can be done with the actor.

Overrides:

clone in class AtomicActor

Parameters:

workspace - The workspace for the cloned object.

Returns:

A new CSPActor.

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)

delay

public void delay(double delta)
           throws IllegalActionException

Delay this actor. The actor resumes executing when the director advances the current model time to "getCurrentTime() + delta". If the actor tries to delay for a negative time, an exception is thrown. A delay of zero time has no effect and this method returns immediately.

Parameters:

delta - The time to delay this actor for from the current time.

Throws:

IllegalActionException - If the argument is negative.

TerminateProcessException - If the director requests termination by calling the protected method _cancelDelay().

getBranchController

public AbstractBranchController getBranchController()

Return the conditional branch control of this actor.

Specified by:

getBranchController in interface BranchActor

Returns:

The conditional branch controller.

initialize

public void initialize()
                throws IllegalActionException

Initialize the state of the actor.

Specified by:

initialize in interface Initializable

Overrides:

initialize in class AtomicActor

Throws:

IllegalActionException - Not thrown in this base class, but might be in a derived class.

postfire

public boolean postfire()

Return false. If an actor wishes to continue for more than one iteration it should override this method to return true.

Specified by:

postfire in interface Executable

Overrides:

postfire in class AtomicActor

Returns:

True if another iteration can occur.

terminate

public void terminate()

Terminate abruptly any threads created by this actor. Note that this method does not allow the threads to terminate gracefully.

Specified by:

terminate in interface Executable

Overrides:

terminate in class AtomicActor

_cancelDelay

protected void _cancelDelay()

If the actor is delayed, then cancel the delay. Some time after this method is called, the thread that called delay() will be restarted and the delay() method will throw a TerminateProcessException.

_continue

protected void _continue()

Resume a delayed actor. This method is only called by CSPDirector after time has sufficiently advanced.

_waitForDeadlock

protected void _waitForDeadlock()

Wait for deadlock to occur. The current model time will not advance while this actor is delayed. This method may be useful if an actor wishes to delay itself until some topology changes have been carried out.