ptolemy.actor.lib.hoc
Class MultiInstanceComposite

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.actor.lib.hoc.MultiInstanceComposite

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 MultiInstanceComposite
extends TypedCompositeActor

A TypedCompositeActor that creates multiple instances of itself during the preinitialize phase of model execution.

A MultiInstanceComposite actor may be used to instantiate nInstances identical processing blocks within a model. This actor (the "master") creates nInstances - 1 additional instances (clones) of itself during the preinitialize() phase of model execution and destroys these additional instances during model CompositeActor.wrapup(). MultiInstanceComposite must be opaque (have a director), so that its Actor interface methods (preinitialize(), ..., wrapup()) are invoked during model initialization. Each instance may refer to its instance [0..nInstances-1] parameter which is set automatically by the master if it needs to know its instance number.

MultiInstanceComposite input ports must not be multiports (for now) and may be connected to multiports or regular ports. During preinitialize(), the master MultiInstanceComposite determines how its input ports are connected, and creates additional relations in its container (the model it is embedded in) to connect the input ports of its clones (instances) to the same output port if that port is a multiport. If that output port is a regular port, the clone's input port is linked to the already existing relation between that output port and the master's input port. MultiInstanceComposite output ports must not be multiports (for now) and must be connected to input multiports. The master MultiInstanceComposite creates additional relations to connect the output ports of its clones to the input port. Finally, after all these connections are made, the master's preinitialize() calls preinitialize() of the clones.

From here on until wrapup(), nothing special happens. Type resolution occurs on all instances in the modified model, so does initialize() and the computation of schedules by directors of the master and clones.

During model wrapup(), the master MultiContextComposite deletes any relations created, unlinks any ports if needed, and deletes the clones it created. To re-synchronize vergil's model graph, an empty ChangeRequest is also queued with the Manager.

Actor parameters inside MultiInstanceComposite may refer to parameters of the container model. This presents a problem during cloning() and wrapup() where the container model's parameters are not in scope during the clone's validateSettables() (unless the MultiInstanceComposite is built as a moml class having its own set of parameters). This problem is for now solved by providing a temporary scope copy using a ScopeExtendingAttribute for the cloning() and wrapup() phases of the clones.

Since:

Ptolemy II 4.0

Version:

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

Author:

Zoltan Kemenczy, Sean Simmons, Research In Motion Limited

See Also:

Serialized Form

Accepted Rating:

Red (cxh)

Proposed Rating:

Red (zkemenczy)

Nested Class Summary

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

CompositeEntity.ContainedObjectsIterator

Field Summary

private java.util.List<MultiInstanceComposite>	_clones
private boolean	_isMasterCopy
Parameter	instance The index of this instance.
Parameter	nInstances The total number of instances to instantiate including instance 0 (the master copy).
Parameter	showClones If true, show the clones.

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

MultiInstanceComposite(CompositeEntity container, java.lang.String name)
Construct a MultiInstanceComposite actor with the given container and name.

MultiInstanceComposite(Workspace workspace)
Construct a MultiInstanceComposite actor in the specified workspace with no container and an empty string as a name.

Method Summary

private java.lang.Object	_cloneClone(Workspace workspace) Clone to create a copy of the master copy.
private void	_construct()
private void	_preinitClone()
java.lang.Object	clone(Workspace workspace) Clone a "master copy" of this actor into the specified workspace - note that this is not used for creating the additional instances.
void	preinitialize() Call the base class to perform standard preinitialize(), and, if this is the master copy, proceed to create nInstances-1 additional copies, and link them to the same input/output ports this master is connected to.

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, _finishedAddEntity, _getPublishedPort, _setDirector, addActorFiringListener, addInitializable, addPiggyback, connectionsChanged, createReceivers, createSchedule, fire, getCausalityInterface, getDirector, getExecutiveDirector, getManager, inferringWidths, inferWidths, initialize, inputPortList, isFireFunctional, isOpaque, isStrict, iterate, linkToPublishedPort, linkToPublishedPort, needsWidthInference, newInsideReceiver, newReceiver, notifyConnectivityChange, outputPortList, postfire, prefire, 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, _exportMoMLContents, _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

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

Methods inherited from interface ptolemy.actor.Initializable

addInitializable, initialize, 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

nInstances

public Parameter nInstances

The total number of instances to instantiate including instance 0 (the master copy).

instance

public Parameter instance

The index of this instance.

showClones

public Parameter showClones

If true, show the clones.

_clones

private java.util.List<MultiInstanceComposite> _clones

_isMasterCopy

private boolean _isMasterCopy

Constructor Detail

MultiInstanceComposite

public MultiInstanceComposite(Workspace workspace)

Construct a MultiInstanceComposite actor in the specified workspace with no container and an empty string as a name.

Parameters:

workspace - The workspace of this object.

MultiInstanceComposite

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

Construct a MultiInstanceComposite actor with the given container and name.

Parameters:

container - The container.

name - The name of this actor.

Throws:

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

NameDuplicationException - If the container already has an actor with this name.

Method Detail

clone

public java.lang.Object clone(Workspace workspace)
                       throws java.lang.CloneNotSupportedException

Clone a "master copy" of this actor into the specified workspace - note that this is not used for creating the additional instances.

Overrides:

clone in class CompositeActor

Parameters:

workspace - The workspace for the new object.

Returns:

A new actor.

Throws:

java.lang.CloneNotSupportedException - If a derived class contains an attribute that cannot be cloned.

See Also:

NamedObj.exportMoML(Writer, int, String), NamedObj.setDeferringChangeRequests(boolean)

preinitialize

public void preinitialize()
                   throws IllegalActionException

Call the base class to perform standard preinitialize(), and, if this is the master copy, proceed to create nInstances-1 additional copies, and link them to the same input/output ports this master is connected to.

Specified by:

preinitialize in interface Initializable

Overrides:

preinitialize in class CompositeActor

Throws:

IllegalActionException - If cloning the additional copies fails, or if any ports are not connected to multiports.

_cloneClone

private java.lang.Object _cloneClone(Workspace workspace)
                              throws java.lang.CloneNotSupportedException

Clone to create a copy of the master copy.

Throws:

java.lang.CloneNotSupportedException

_construct

private void _construct()

_preinitClone

private void _preinitClone()
                    throws IllegalActionException

Throws:

IllegalActionException