ptolemy.domains.rendezvous.lib
Class Buffer

java.lang.Object
  ptolemy.kernel.util.NamedObj
      ptolemy.kernel.InstantiableNamedObj
          ptolemy.kernel.Entity
              ptolemy.kernel.ComponentEntity
                  ptolemy.actor.AtomicActor
                      ptolemy.actor.TypedAtomicActor
                          ptolemy.domains.rendezvous.lib.Buffer

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 Buffer
extends TypedAtomicActor

This actor buffers data provided at the input, sending it to the output when needed. It uses two threads. The main actor thread is willing to rendezvous with the output as long as the buffer is not empty. A second thread is created on the first invocation of fire(). This second thread is willing to rendezvous with the input as long as the buffer is not full. Thus, this actor acts as a FIFO (first-in, first-out) buffer that will accept input tokens as long as it is not full, and will produce output tokens as long as it is not empty.

If the capacity changes during execution, and the buffer already contains more tokens than the new capacity, then no tokens are lost, but no new tokens are accepted at the input until the number of buffered tokens drops below the capacity.

This actor is similar to the ResourcePool actor except that the input and output ports are not multiports and there are no initial tokens in this buffer.

Since:

Ptolemy II 5.1

Version:

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

Author:

Edward A. Lee

See Also:

ResourcePool, Serialized Form

Accepted Rating:

Red (cxh)

Proposed Rating:

Yellow (eal)

Nested Class Summary

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

Entity.ContainedObjectsIterator

Field Summary

private java.util.List	_buffer The current buffer.
private IllegalActionException	_exception Exception that might be thrown by the spawned thread.
private boolean	_postfireReturns Flag indicating what postfire should return.
private java.lang.Thread	_readThread The read thread, if it exists.
Parameter	capacity The capacity of the buffer.
TypedIOPort	input The input port.
TypedIOPort	output The output port.

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

Buffer(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() If it has not already been done, start a thread to read tokens from the input port and store them in the buffer.
void	initialize() Clear the buffer.
boolean	postfire() Return false if it is time to stop the process.

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, prefire, 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, 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

capacity

public Parameter capacity

The capacity of the buffer. To provide "infinite" capacity, set this to a negative number.

input

public TypedIOPort input

The input port.

output

public TypedIOPort output

The output port. The type of this output is constrained to be at least that of the input.

_buffer

private java.util.List _buffer

The current buffer.

_exception

private IllegalActionException _exception

Exception that might be thrown by the spawned thread.

_postfireReturns

private boolean _postfireReturns

Flag indicating what postfire should return.

_readThread

private java.lang.Thread _readThread

The read thread, if it exists.

Constructor Detail

Buffer

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

Construct an actor in the specified container with the specified name. The name must be unique within the container or an exception is thrown. The container argument must not be null, or a NullPointerException will be thrown.

Parameters:

container - The container.

name - The name.

Throws:

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

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

Method Detail

clone

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

Clone the actor into the specified workspace.

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 an attribute that cannot be cloned.

See Also:

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

fire

public void fire()
          throws IllegalActionException

If it has not already been done, start a thread to read tokens from the input port and store them in the buffer. Then, in the calling thread, if there is at least one token in the buffer, write the first token to the output port.

Specified by:

fire in interface Executable

Overrides:

fire in class AtomicActor

Throws:

IllegalActionException - If an error occurs during executing the process.

TerminateProcessException - If the process termination is requested by the director.

initialize

public void initialize()
                throws IllegalActionException

Clear the buffer.

Specified by:

initialize in interface Initializable

Overrides:

initialize in class AtomicActor

Throws:

IllegalActionException - If the base class throws it.

postfire

public boolean postfire()

Return false if it is time to stop the process.

Specified by:

postfire in interface Executable

Overrides:

postfire in class AtomicActor

Returns:

False a TerminateProcessException was thrown during I/O.