ptolemy.domains.ddf.lib
Class ActorRecursion

java.lang.Object
  ptolemy.kernel.util.NamedObj
      ptolemy.kernel.InstantiableNamedObj
          ptolemy.kernel.Entity
              ptolemy.kernel.ComponentEntity
                  ptolemy.kernel.CompositeEntity
                      ptolemy.actor.CompositeActor
                          ptolemy.actor.TypedCompositeActor
                              ptolemy.domains.ddf.lib.ActorRecursion

All Implemented Interfaces:

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

public class ActorRecursion
extends TypedCompositeActor

This actor performs actor recursion dynamically during execution. Upon firing, it clones the composite actor which contains itself and is referred to by the StringParameter recursionActor. It then places the clone inside itself and connects the corresponding ports of both actors. It uses a local DDFDirector to preinitialize the clone and then transfers all tokens contained by input ports of this actor to the connected opaque ports inside. It again uses the local DDFDirector to initialize all actors contained by this actor and classifies each of them such as their enabling and deferrable status. It then transfers all tokens contained by output ports of this actor to the connected opaque ports outside. It finally merges the local DDFDirector with its executive DDFDirector and then removes the local DDFDirector. Thus during execution this actor is fired at most once, after which the executive director directly controls all actors inside. Since there is no type constraint between input ports and output ports of this actor, users have to manually configure types for all outputs of this actor.

Since:

Ptolemy II 4.1

Version:

$Id: ActorRecursion.java 44788 2006-12-19 18:31:56Z cxh $

Author:

Gang Zhou

See Also:

Serialized Form

Accepted Rating:

Yellow (cxh)

Proposed Rating:

Yellow (zgang)

Nested Class Summary

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

CompositeEntity.ContainedObjectsIterator

Field Summary

private java.util.HashMap	_inputTokensHolder A HashMap to store tokens of the input ports.
private boolean	_isCompatibilityChecked A flag indicating if the compatibility of the to-be-cloned composite actor has been checked.
private CompositeActor	_recursionActor The composite actor to be cloned.
StringParameter	recursionActor A StringParameter representing the name of the composite actor to clone from.

Fields inherited from class ptolemy.actor.CompositeActor

_actorFiringListeners, _causalityInterface, _initializables, _notifyingActorFiring, _publishedPorts, _publisherRelations, _stopRequested

Fields inherited from class ptolemy.kernel.CompositeEntity

_levelCrossingLinks

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

ActorRecursion(CompositeEntity container, java.lang.String name)
Create an ActorRecursion with a name and a container.

Method Summary

private void	_checkCompatibility() Check the compatibility of the to-be-cloned composite actor with this actor.
private void	_cloneRecursionActor() Clone the composite actor into the same workspace as this actor.
protected void	_exportMoMLContents(java.io.Writer output, int depth) Write a MoML description of the contents of this object.
protected void	_finishedAddEntity(ComponentEntity entity) Notify this actor that the given entity has been added inside it.
private int	_getTokenConsumptionRate(Receiver receiver) Get token consumption rate for the given receiver.
private void	_searchRecursionActor() Get the to-be-cloned composite actor's name from StringParameter recursionActor.
private void	_setOutputPortRate() Read the rate parameters of the input ports of all actors receiving tokens from this actor and propagate these parameters back to the connected output ports of this actor.
private void	_transferInputs() Transfer all tokens contained by input ports of this actor and stored by an internal variable to the connected opaque ports inside.
private void	_transferOutputs() Transfer all tokens contained by output ports of this actor to the connected opaque ports outside.We cannot use transferOutputs(IOPort) of the local director because we have to transfer all tokens instead of those specified by rate parameters because all output ports will become transparent after this firing.
void	fire() Clone the composite actor referred to by the StringParameter recursionActor into itself.
void	initialize() Initialize this actor.
boolean	postfire() Override the base class to return false.

Methods inherited from class ptolemy.actor.TypedCompositeActor

_addEntity, _addPort, _addRelation, _checkTypesFromTo, _typeConstraintsFromTo, newPort, newRelation, resolveTypes, typeConstraintList, typeConstraints

Methods inherited from class ptolemy.actor.CompositeActor

_actorFiring, _actorFiring, _getPublishedPort, _setDirector, addActorFiringListener, addInitializable, addPiggyback, clone, connectionsChanged, createReceivers, createSchedule, getCausalityInterface, getDirector, getExecutiveDirector, getManager, inferringWidths, inferWidths, inputPortList, isFireFunctional, isOpaque, isStrict, iterate, linkToPublishedPort, linkToPublishedPort, needsWidthInference, newInsideReceiver, newReceiver, notifyConnectivityChange, outputPortList, prefire, preinitialize, recordFiring, registerPublisherPort, removeActorFiringListener, removeInitializable, removePiggyback, requestChange, setContainer, setDirector, setManager, stop, stopFire, terminate, unlinkToPublishedPort, unlinkToPublishedPort, unregisterPublisherPort, wrapup

Methods inherited from class ptolemy.kernel.CompositeEntity

_adjustDeferrals, _deepOpaqueEntityList, _description, _recordDecoratedAttributes, _removeEntity, _removeRelation, _validateSettables, allAtomicEntityList, allCompositeEntityList, allowLevelCrossingConnect, classDefinitionList, connect, connect, containedObjectsIterator, deepEntityList, deepGetEntities, deepOpaqueEntityList, deepRelationSet, entityList, entityList, exportLinks, exportMoML, getAttribute, getEntities, getEntity, getPort, getRelation, getRelations, isAtomic, lazyAllAtomicEntityList, lazyAllCompositeEntityList, lazyClassDefinitionList, lazyDeepEntityList, lazyEntityList, lazyRelationList, numberOfEntities, numberOfRelations, numEntities, numRelations, relationList, removeAllEntities, removeAllRelations, setClassDefinition, statistics, uniqueName

Methods inherited from class ptolemy.kernel.ComponentEntity

_checkContainer, _getContainedObject, _propagateExistence, getContainer, instantiate, moveDown, moveToFirst, moveToIndex, moveToLast, moveUp, propagateExistence, setName

Methods inherited from class ptolemy.kernel.Entity

_removePort, connectedPortList, connectedPorts, getPorts, linkedRelationList, linkedRelations, portList, removeAllPorts

Methods inherited from class ptolemy.kernel.InstantiableNamedObj

_setParent, 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, _removeAttribute, _splitName, _stripNumericSuffix, addChangeListener, addDebugListener, attributeChanged, attributeList, attributeList, attributeTypeChanged, clone, 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, 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

isFireFunctional, isStrict, iterate, prefire, stop, stopFire, terminate

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

recursionActor

public StringParameter recursionActor

A StringParameter representing the name of the composite actor to clone from. The composite actor contains this actor in some hierarchy.

_recursionActor

private CompositeActor _recursionActor

The composite actor to be cloned.

_isCompatibilityChecked

private boolean _isCompatibilityChecked

A flag indicating if the compatibility of the to-be-cloned composite actor has been checked. It is set to true after checking so that checking is performed only once during the execution of the model.

_inputTokensHolder

private java.util.HashMap _inputTokensHolder

A HashMap to store tokens of the input ports.

Constructor Detail

ActorRecursion

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

Create an ActorRecursion 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. The actor creates a DDFDirector initially, which will be removed toward the end of firing this actor, when the director completes its responsibility of preinitializing and initializing the cloned composite actor and merging with the outside DDFDirector.

Parameters:

container - The container actor.

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

Clone the composite actor referred to by the StringParameter recursionActor into itself. Use a local DDFDirector to preinitialize all (just cloned) actors contained by this actor. Transfer all tokens contained by input ports of this actor to the connected opaque ports inside. Read rate parameters of input ports of all actors receiving tokens from this actor and propagate these parameters back to the connected output ports of this actor. Use the local DDFDirector to initialize all actors contained by this actor and classify each of them according to their enabling and deferrable status. Transfer all tokens contained by output ports of this actor to the connected opaque ports outside. Merge the local DDFDirector with the outside DDFDirector and finally remove local DDFDirector.

Specified by:

fire in interface Executable

Overrides:

fire in class CompositeActor

Throws:

IllegalActionException - If any called method throws IllegalActionException.

initialize

public void initialize()
                throws IllegalActionException

Initialize this actor. First find the composite actor to be cloned, which is the first containing actor up in the hierarchy with the name referred to by the StringParameter recursionActor. Then check the compatibility of the found composite actor with this actor. It is only done once due to the recursive nature of this actor.

Specified by:

initialize in interface Initializable

Overrides:

initialize in class CompositeActor

Throws:

IllegalActionException - If no actor is found with the given name or the found actor is not compatible.

postfire

public boolean postfire()
                 throws IllegalActionException

Override the base class to return false. Upon seeing the return value, its executive director disables this actor and only fires all inside actors next time.

Specified by:

postfire in interface Executable

Overrides:

postfire in class CompositeActor

Returns:

false.

Throws:

IllegalActionException - Not thrown in this base class.

_exportMoMLContents

protected void _exportMoMLContents(java.io.Writer output,
                                   int depth)
                            throws java.io.IOException

Write a MoML description of the contents of this object. Override the base class to describe contained ports and attributes, but not inside entities, links and relations created during execution.

Overrides:

_exportMoMLContents in class CompositeEntity

Parameters:

output - The output to write to.

depth - The depth in the hierarchy, to determine indenting.

Throws:

java.io.IOException - If an I/O error occurs.

See Also:

NamedObj.exportMoML(Writer, int)

_finishedAddEntity

protected void _finishedAddEntity(ComponentEntity entity)

Notify this actor that the given entity has been added inside it. Override the base class to do nothing. This will prevent it from calling requestInitialization(Actor) to the cloned composite actor. The preinitialization and initialization have already been done in the fire() method.

Overrides:

_finishedAddEntity in class CompositeActor

Parameters:

entity - Actor to contain.

_checkCompatibility

private void _checkCompatibility()
                          throws IllegalActionException

Check the compatibility of the to-be-cloned composite actor with this actor. The compatibility criteria are self-evident in the code. Basically two actors should look the same from outside and it should not violate type constraints by placing the cloned composite actor inside this actor and connecting the corresponding ports.

Throws:

IllegalActionException - If the composite actor to be cloned is not compatible with this actor.

_cloneRecursionActor

private void _cloneRecursionActor()
                           throws IllegalActionException,
                                  java.lang.CloneNotSupportedException

Clone the composite actor into the same workspace as this actor. Set its container to this actor. Store all tokens contained by input ports of this actor. Connect the corresponding ports of this actor and the cloned composite actor.

Throws:

IllegalActionException - If any called method throws IllegalActionException, or NameDuplicationException is caught in this method.

java.lang.CloneNotSupportedException - If the CompositeActor cannot be cloned.

_getTokenConsumptionRate

private int _getTokenConsumptionRate(Receiver receiver)
                              throws IllegalActionException

Get token consumption rate for the given receiver. If the port containing the receiver is an input port, return the consumption rate for that receiver. If the port containing the receiver is an opaque output port, return the production rate for that receiver.

Parameters:

receiver - The receiver to get token consumption rate.

Returns:

The token consumption rate of the given receiver.

Throws:

IllegalActionException - If any called method throws IllegalActionException.

_searchRecursionActor

private void _searchRecursionActor()
                            throws IllegalActionException

Get the to-be-cloned composite actor's name from StringParameter recursionActor. Go up in hierarchy and find the first container with matching name.

Throws:

IllegalActionException - If no actor is found with the given name.

_setOutputPortRate

private void _setOutputPortRate()
                         throws IllegalActionException

Read the rate parameters of the input ports of all actors receiving tokens from this actor and propagate these parameters back to the connected output ports of this actor. This is needed because during the initialization of the local director, the contained actors only see the opaque output ports of this actor instead of the connected opaque ports on the outside after the local director is removed. To determine the deferrability (see DDFDirector for its definition) of the contained actors, which happens during the initialization of the local director, we need to propagate these rate parameters back to the connected output ports of this actor.

Throws:

IllegalActionException - If any called method throws IllegalActionException.

_transferInputs

private void _transferInputs()
                      throws IllegalActionException

Transfer all tokens contained by input ports of this actor and stored by an internal variable to the connected opaque ports inside. We cannot use transferInputs(IOPort) of the local director for two reason. One is that tokens are now stored by an internal variable. The other is that we have to transfer all tokens instead of those specified by rate parameters because all input ports will become transparent after this firing.

Throws:

IllegalActionException - If conversion to the type of the destination port cannot be done.

_transferOutputs

private void _transferOutputs()
                       throws IllegalActionException

Transfer all tokens contained by output ports of this actor to the connected opaque ports outside.We cannot use transferOutputs(IOPort) of the local director because we have to transfer all tokens instead of those specified by rate parameters because all output ports will become transparent after this firing.

Throws:

IllegalActionException - If conversion to the type of the destination port cannot be done.