ptolemy.actor.lib.hoc
Class IterateOverArray
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.MirrorComposite
ptolemy.actor.lib.hoc.IterateOverArray
- All Implemented Interfaces:
- java.io.Serializable, java.lang.Cloneable, Actor, Executable, FiringsRecordable, Initializable, TypedActor, Changeable, Debuggable, DebugListener, Derivable, Instantiable, ModelErrorHandler, MoMLExportable, Moveable, Nameable, HandlesInternalLinks
public class IterateOverArray
- extends MirrorComposite
This actor iterates the contained actor or model over input arrays.
To use it, either drop an actor on it and provide arrays to the inputs,
or use a default configuration where the actor is effectively a
composite actor. In the latter case,
you can simply look inside and
populate that actor with a submodel that will be applied to the
array elements. The submodel is required to have a director.
An SDF director will
often be sufficient for operations taken on array elements,
but other directors can be used as well.
Note that this inside director should not impose a limit
on the number of iterations of the inside model. If it does,
then that limit will be respected, which may result in a failure
to iterate over all the input data.
Each input port expects an array. When this actor fires,
an array is read on each input port that has one, and its
contents are provided sequentially to the contained actor or model.
This actor then iterates the contained actor or model until either
there are no more input data for the actor or the prefire()
method of the actor or model
returns false. If postfire() of the actor returns false,
then postfire() of this actor will return false, requesting
a halt to execution of the model. The outputs from the
contained actor are collected into arrays that are
produced on the outputs of this actor.
A special variable named "iterationCount" can be used in
any expression setting the value of a parameter of this actor
or its contents. This variable has an integer value that
starts at 1 during the first iteration of the contained
actor(s) and is incremented by 1 on each firing. If the
inside actors consume one token on each firing, then
its final value will be the size of the input array(s).
This actor is properly viewed as a "higher-order component" in
that its contained actor is a parameter that specifies how to
operate on input arrays. It is inspired by the higher-order
functions of functional languages, but unlike those, the
contained actor need not be functional. That is, it can have
state.
Note that you cannot place class definitions inside this
actor. There should be no need to because class instances
inside it can be instances of classes defined outside of it.
This actor (and many of the other higher-order components)
has its intellectual roots in the higher-order functions
of functional languages, which have been in use since
the 1970s. Similar actors were implemented in Ptolemy
Classic, and are described in Lee & Parks, "Dataflow
Process Networks," Proceedings of the IEEE, 1995.
Those were inspired by [2].
Alternative approaches are found dataflow visual programming
since the beginning (Sutherland in the 1960s, Prograph and
Labview in the 1980s), and in time-based visual languages
(Simulink in the 1990s).
There are a number of known bugs or limitations in this
implementation:
-
FIXME: When you drop in an actor, and then another actor,
and then select "undo," the second actor is deleted without
the first one being re-created. Thus, undo is only a partial
undo. The fix to this is extremely complicated. Probably the
only viable mechanism is to use UndoStackAttribute.getUndoInfo()
to get the undo stack and then to manipulate the contents
of that stack directly.
-
FIXME: There should be an option to reset between
firings of the inside actor.
- FIXME: If you drop a new actor onto an
IterateOverArray in a subclass, it will replace the
version inherited from the prototype. This is not right,
since it violates the derivation invariant. Any attempt
to modify the contained object in the prototype will trigger
an exception. There are two possible fixes. One is to
relax the derivation invariant and allow derived objects
to not perfectly mirror the hierarchy of the prototype.
Another is for this class to somehow refuse to accept
the new object in a subclass. But it is not obvious how
to do this.
-
FIXME: If an instance of IterateOverArray in a derived class has
overridden values of parameters, those are lost if contained
entity of the instance in the base class is replaced and
then an undo is requested.
References
- E. A. Lee and T. M. Parks, "Dataflow Process Networks,"
Proceedings of the IEEE, 83(5): 773-801, May, 1995.
- H. J. Reekie,
Realtime Signal Processing: Dataflow, Visual,
and Functional Programming," Ph.D. Thesis,
University of Technology, Sydney, Sydney, Australia, 1995.
- Since:
- Ptolemy II 4.1
- Version:
- $Id: IterateOverArray.java 57040 2010-01-27 20:52:32Z cxh $
- Author:
- Edward A. Lee, Steve Neuendorffer
- See Also:
- Serialized Form
- Accepted Rating:
- Proposed Rating:
|
Nested Class Summary |
static class |
IterateOverArray.IterateComposite
This is a specialized composite actor for use in IterateOverArray. |
private class |
IterateOverArray.IterateDirector
This is a specialized director that fires contained actors
in the order in which they appear in the actor list repeatedly
until either there is no more input data for the actor or
the prefire() method of the actor returns false. |
static class |
IterateOverArray.IteratePort
This is a specialized port for IterateOverArray. |
| Fields inherited from class ptolemy.kernel.util.NamedObj |
_changeListeners, _changeLock, _changeRequests, _debugging, _debugListeners, _elementName, _isPersistent, _verbose, _workspace, ATTRIBUTES, CLASSNAME, COMPLETE, CONTENTS, DEEP, FULLNAME, LINKS |
|
Method Summary |
protected java.util.List |
_checkTypesFromTo(TypedIOPort sourcePort,
java.util.List destinationPortList)
Check types from a source port to a group of destination ports,
assuming the source port is connected to all the ports in the
group of destination ports. |
private void |
_init()
Initialize the class. |
protected java.util.List |
_typeConstraintsFromTo(TypedIOPort sourcePort,
java.util.List destinationPortList)
Return the type constraints on all connections starting from the
specified source port to all the ports in a group of destination
ports. |
java.lang.Object |
clone(Workspace workspace)
Clone the object into the specified workspace. |
Port |
newPort(java.lang.String name)
Override the base class to return a specialized port. |
java.util.Set<Inequality> |
typeConstraints()
Override the base class to ensure that the ports of this
actor all have array types. |
| 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, 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, _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.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 |
_iterationCount
private Variable _iterationCount
IterateOverArray
public IterateOverArray(CompositeEntity container,
java.lang.String name)
throws IllegalActionException,
NameDuplicationException
- Create an actor 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.
This actor will have no
local director initially, and its executive director will be simply
the director of the container.
You should set a director before attempting to execute it.
- 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.
IterateOverArray
public IterateOverArray(Workspace workspace)
throws IllegalActionException,
NameDuplicationException
- Construct an IterateOverArray in the specified workspace with
no container and 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. You should set the local director or
executive director before attempting to send data to the actor
or to execute it. Add the actor to the workspace directory.
Increment the version number of the workspace.
- Parameters:
workspace - The workspace that will list the actor.
- Throws:
IllegalActionException - If the container is incompatible
with this actor.
NameDuplicationException - If the name coincides with
an actor already in the container.
clone
public java.lang.Object clone(Workspace workspace)
throws java.lang.CloneNotSupportedException
- Clone the object into the specified workspace. This overrides
the base class to set the association with iterationCount.
- Overrides:
clone in class MirrorComposite
- Parameters:
workspace - The workspace for the new object.
- Returns:
- A new NamedObj.
- Throws:
java.lang.CloneNotSupportedException - If any of the attributes
cannot be cloned.- See Also:
CompositeEntity.exportMoML(Writer, int, String)
newPort
public Port newPort(java.lang.String name)
throws NameDuplicationException
- Override the base class to return a specialized port.
- Overrides:
newPort in class MirrorComposite
- Parameters:
name - The name of the port to create.
- Returns:
- A new instance of IteratePort, an inner class.
- Throws:
NameDuplicationException - If the container already has a port
with this name.
typeConstraints
public java.util.Set<Inequality> typeConstraints()
throws IllegalActionException
- Override the base class to ensure that the ports of this
actor all have array types.
- Specified by:
typeConstraints in interface TypedActor- Overrides:
typeConstraints in class TypedCompositeActor
- Returns:
- A list of instances of Inequality.
- Throws:
IllegalActionException - If the typeConstraints
of one of the deeply contained objects throws it.- See Also:
Inequality
_checkTypesFromTo
protected java.util.List _checkTypesFromTo(TypedIOPort sourcePort,
java.util.List destinationPortList)
- Check types from a source port to a group of destination ports,
assuming the source port is connected to all the ports in the
group of destination ports. Return a list of instances of
Inequality that have type conflicts. This overrides the base
class so that if one of the ports belongs to this IterateOverArray
actor, then its element type is compared against the inside port.
- Overrides:
_checkTypesFromTo in class TypedCompositeActor
- Parameters:
sourcePort - The source port.destinationPortList - A list of destination ports.
- Returns:
- A list of instances of Inequality indicating the
type constraints that are not satisfied.
_typeConstraintsFromTo
protected java.util.List _typeConstraintsFromTo(TypedIOPort sourcePort,
java.util.List destinationPortList)
- Return the type constraints on all connections starting from the
specified source port to all the ports in a group of destination
ports. This overrides the base class to ensure that if the source
port or the destination port is a port of this composite, then
the port is forced to be an array type and the proper constraint
on the element type of the array is made. If the source port
has no possible sources of data, then no type constraints are
added for it.
- Overrides:
_typeConstraintsFromTo in class TypedCompositeActor
- Parameters:
sourcePort - The source port.destinationPortList - The destination port list.
- Returns:
- A list of instances of Inequality.
_init
private void _init()
throws IllegalActionException,
NameDuplicationException
- Initialize the class.
- Throws:
IllegalActionException
NameDuplicationException