ptolemy.actor.lib
Class Commutator

java.lang.Object
  ptolemy.kernel.util.NamedObj
      ptolemy.kernel.InstantiableNamedObj
          ptolemy.kernel.Entity
              ptolemy.kernel.ComponentEntity
                  ptolemy.actor.AtomicActor
                      ptolemy.actor.TypedAtomicActor
                          ptolemy.actor.lib.Transformer
                              ptolemy.actor.lib.Commutator

All Implemented Interfaces:

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

public class Commutator
extends Transformer
implements SequenceActor

A polymorphic commutator, which merges a set of input sequences into a single output sequence. The commutator has an input port (a multiport) and an output port (a single port). The types of the ports are undeclared and will be resolved by the type resolution mechanism, with the constraint that the output type must be greater than or equal to the input type. On each call to the fire method, the actor reads N tokens from each input channel and sends the tokens to the output port, where N is the value of blockSize. The order in which the tokens are produced is the order of the channels in the input multiport. If any input channel has no tokens, then the fire method returns without producing output. In the next iteration, the actor will begin reading at the channel that had no input token in the previous iteration. If no input token is available on the first channel being read, then no output is produced.

For the benefit of domains like SDF, which need to know the token consumption or production rate for all ports before they can construct a firing schedule, this actor sets the tokenProductionRate parameter for the output port to equal the number of input channels times the value of the blockSize parameter. This parameter is set each time that a link is established with the input port, or when a link is removed. The director is notified that the schedule is invalid, so that if the link is modified at run time, the schedule will be recalculated if necessary.

Since:

Ptolemy II 0.2

Version:

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

Author:

Mudit Goel, Edward A. Lee

See Also:

Serialized Form

Accepted Rating:

Yellow (cxh)

Proposed Rating:

Yellow (mudit)

Nested Class Summary

private static class

Commutator.WidthDependentParameter This class will set _port.getWidth() + " * blockSize" as expression of the parameter, but will only do it when the token is requested to delay the triggering of the width.

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

Entity.ContainedObjectsIterator

Field Summary

private int	_currentInputPosition
private int	_tentativeInputPosition
Parameter	blockSize The number of tokens read from each input channel on each firing.
Parameter	input_tokenConsumptionRate The parameter controlling the input port consumption rate.
Parameter	output_tokenProductionRate The parameter controlling the output port production rate.

Fields inherited from class ptolemy.actor.lib.Transformer

input, output

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

Commutator(CompositeEntity container, java.lang.String name)
Construct an actor in the specified container with the specified name.

Method Summary

java.lang.Object	clone(Workspace workspace) Clone the actor into the specified workspace.
void	fire() Read blockSize tokens from each input channel and send them to the output port.
void	initialize() Begin execution by setting the current input channel to zero.
boolean	postfire() Update the input position to equal that determined by the most recent invocation of the fire() method.
boolean	prefire() Return false if the current input position does not have an input token.

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, getCausalityInterface, getDirector, getExecutiveDirector, getManager, inputPortList, isFireFunctional, isStrict, iterate, newReceiver, outputPortList, preinitialize, pruneDependencies, recordFiring, removeActorFiringListener, removeDependency, removeInitializable, setContainer, stop, stopFire, terminate, 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

isFireFunctional, isStrict, iterate, 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

blockSize

public Parameter blockSize

The number of tokens read from each input channel on each firing. This is an integer that defaults to 1.

input_tokenConsumptionRate

public Parameter input_tokenConsumptionRate

The parameter controlling the input port consumption rate. This parameter contains an IntToken, initially with a value of 1.

output_tokenProductionRate

public Parameter output_tokenProductionRate

The parameter controlling the output port production rate. This parameter contains an IntToken, initially with a value of 0. When connections are made and/or the blockSize parameter is set, this is changed to the width of the input times the value of the blockSize parameter.

_currentInputPosition

private int _currentInputPosition

_tentativeInputPosition

private int _tentativeInputPosition

Constructor Detail

Commutator

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

Construct an actor in the specified container with the specified name. Create ports and make the input port a multiport. Create the actor parameters.

Parameters:

container - The container.

name - This is the name of this commutator within the container.

Throws:

NameDuplicationException - If an actor with an identical name already exists in the container.

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

Method Detail

clone

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

Clone the actor into the specified workspace. This calls the base class method and sets the public variables to point to the new ports.

Overrides:

clone in class AtomicActor

Parameters:

workspace - The workspace for the new object.

Returns:

A new actor.

Throws:

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

See Also:

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

fire

public void fire()
          throws IllegalActionException

Read blockSize tokens from each input channel and send them to the output port. If an input channel does not have enough tokens, suspend firing and return. In this case, the actor makes a record of the input channel that it last attempted to read so that it can start reading at that channel in the next iteration. The order in which the tokens are produced is the order of the channels in the input port.

Specified by:

fire in interface Executable

Overrides:

fire in class AtomicActor

Throws:

IllegalActionException - If there is no director.

initialize

public void initialize()
                throws IllegalActionException

Begin execution by setting the current input channel to zero.

Specified by:

initialize in interface Initializable

Overrides:

initialize in class AtomicActor

Throws:

IllegalActionException - If there is no director.

postfire

public boolean postfire()
                 throws IllegalActionException

Update the input position to equal that determined by the most recent invocation of the fire() method. The input position is the channel number of the input port from which the next input will be read.

Specified by:

postfire in interface Executable

Overrides:

postfire in class AtomicActor

Returns:

True if execution can continue into the next iteration.

Throws:

IllegalActionException - If there is no director.

prefire

public boolean prefire()
                throws IllegalActionException

Return false if the current input position does not have an input token.

Specified by:

prefire in interface Executable

Overrides:

prefire in class AtomicActor

Returns:

False if the current input position has no token.

Throws:

IllegalActionException - If input.hasToken() throws it.