ptolemy.actor.lib.hoc
Class MultiInstanceComposite

java.lang.Object
  extended byptolemy.kernel.util.NamedObj
      extended byptolemy.kernel.InstantiableNamedObj
          extended byptolemy.kernel.Entity
              extended byptolemy.kernel.ComponentEntity
                  extended byptolemy.kernel.CompositeEntity
                      extended byptolemy.actor.CompositeActor
                          extended byptolemy.actor.TypedCompositeActor
                              extended byptolemy.actor.lib.hoc.MultiInstanceComposite
All Implemented Interfaces:
Actor, Changeable, java.lang.Cloneable, Debuggable, DebugListener, Derivable, Executable, Instantiable, ModelErrorHandler, MoMLExportable, Nameable, java.io.Serializable, TypedActor

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 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,v 1.11.2.1 2004/06/18 00:48:56 cxh Exp $
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 inherited from class ptolemy.kernel.CompositeEntity
CompositeEntity.ContainedObjectsIterator
 
Field Summary
 Parameter instance
          The index of this instance.
 Parameter nInstances
          The total number of instances to instantiate including instance 0 (the master copy).
 
Fields inherited from class ptolemy.actor.CompositeActor
_stopRequested
 
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
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
 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.
 void wrapup()
          Call the base class to perform standard wrapup() functions, and, if this is the master copy, delete the clones of this actor created during preinitialize().
 
Methods inherited from class ptolemy.actor.TypedCompositeActor
_addEntity, _addPort, _addRelation, _checkTypesFromTo, _typeConstraintsFromTo, newPort, newRelation, resolveTypes, typeConstraintList
 
Methods inherited from class ptolemy.actor.CompositeActor
_finishedAddEntity, _setDirector, connectionsChanged, fire, getDirector, getExecutiveDirector, getFunctionDependency, getManager, initialize, inputPortList, isOpaque, iterate, newInsideReceiver, newReceiver, outputPortList, postfire, prefire, requestChange, setContainer, setDirector, setManager, stop, stopFire, terminate
 
Methods inherited from class ptolemy.kernel.CompositeEntity
_adjustDeferrals, _description, _exportMoMLContents, _removeEntity, _removeRelation, allAtomicEntityList, allowLevelCrossingConnect, classDefinitionList, connect, connect, containedObjectsIterator, deepEntityList, deepGetEntities, entityList, entityList, exportLinks, getAttribute, getEntities, getEntity, getPort, getRelation, getRelations, isAtomic, numberOfClassDefinitions, numberOfEntities, numberOfRelations, numEntities, numRelations, relationList, removeAllEntities, removeAllRelations, uniqueName, validateSettables
 
Methods inherited from class ptolemy.kernel.ComponentEntity
_checkContainer, _getContainedObject, _propagateExistence, getContainer, instantiate, propagateExistence, setName
 
Methods inherited from class ptolemy.kernel.Entity
_removePort, connectedPortList, connectedPorts, getPorts, linkedRelationList, linkedRelations, portList, removeAllPorts, setClassDefinition
 
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, 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.actor.Actor
getDirector, getExecutiveDirector, getFunctionDependency, getManager, inputPortList, newReceiver, outputPortList
 
Methods inherited from interface ptolemy.actor.Executable
fire, initialize, iterate, postfire, prefire, stop, stopFire, terminate
 
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

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.

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.


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.

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 Executable
Overrides:
preinitialize in class CompositeActor
Throws:
IllegalActionException - If cloning the additional copies fails, or if any ports are not connected to multiports.

wrapup

public void wrapup()
            throws IllegalActionException
Call the base class to perform standard wrapup() functions, and, if this is the master copy, delete the clones of this actor created during preinitialize().

Specified by:
wrapup in interface Executable
Overrides:
wrapup in class CompositeActor
Throws:
IllegalActionException - Not thrown in this base class.