ptolemy.domains.de.lib
Class TimedDelay

java.lang.Object
  ptolemy.kernel.util.NamedObj
      ptolemy.kernel.InstantiableNamedObj
          ptolemy.kernel.Entity
              ptolemy.kernel.ComponentEntity
                  ptolemy.actor.AtomicActor
                      ptolemy.actor.TypedAtomicActor
                          ptolemy.domains.de.kernel.DEActor
                              ptolemy.domains.de.lib.DETransformer
                                  ptolemy.domains.de.lib.TimedDelay

All Implemented Interfaces:

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

Direct Known Subclasses:

BoundedBufferTimedDelay, VariableDelay

public class TimedDelay
extends DETransformer

This actor delays the input by a specified amount of time. The amount of the time is required to be non-negative and has a default value 1.0. The input and output types are unconstrained, except that the output type must be the same as that of the input.

This actor keeps a local FIFO queue to store all received but not processed inputs. The behavior of this actor on each firing is to read a token from the input, if there is one, store it into the local queue, and output the previously received token that is scheduled to be produced at the current time.

During the postfire() method, this actor schedules itself to fire again to produce the just received token on the corresponding output channel after the appropriate time delay. Note that if the value of delay is 0.0, the actor schedules itself to fire at the current model time.

Occasionally, this actor is useful with the delay parameter set to 0.0. The time stamp of the output will equal that of the input, but there is a "microstep" delay. The discrete-event domain in Ptolemy II has a "super dense" model of time, meaning that a signal from one actor to another can contain multiple events with the same time stamp. These events are "simultaneous," but nonetheless have a well-defined sequential ordering determined by the order in which they are produced. If \textit{delay} is 0.0, then the fire() method of this actor always produces on its output port the event consumed in the \textit{previous iteration} with the same time stamp, if there was one. If there wasn't such a previous iteration, then it produces no output. Its postfire() method consumes and records the input for use in the next iteration, if there is such an input, and also requests a refiring at the current time. This refire request triggers the next iteration (at the same time stamp), on which the output is produced.

A consequence of this strategy is that this actor is able to produce an output (or assert that there is no output) before the input with the same time is known. Hence, it can be used to break causality loops in feedback systems. The DE director will leverage this when determining the precedences of the actors. It is sometimes useful to think of this zero-valued delay as an infinitesimal delay.

Since:

Ptolemy II 1.0

Version:

$Id: TimedDelay.java 59167 2010-09-21 17:08:02Z cxh $

Author:

Edward A. Lee, Lukito Muliadi, Haiyang Zheng

See Also:

VariableDelay, Server, Serialized Form

Accepted Rating:

Yellow (hyzheng)

Proposed Rating:

Green (hyzheng)

Nested Class Summary

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

Entity.ContainedObjectsIterator

Field Summary

protected CausalityMarker	_causalityMarker A causality marker to store information about how pure events are causally related to trigger events.
protected Token	_currentInput Current input.
protected Token	_currentOutput Current output.
protected double	_delay The amount of delay.
protected CalendarQueue	_delayedOutputTokens A local event queue to store the delayed output tokens.
Parameter	delay The amount of delay.

Fields inherited from class ptolemy.domains.de.lib.DETransformer

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

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

Method Summary

protected void	_fireAt(Time time) Request a firing of this actor at the specified time and throw an exception if the director does not agree to do it at the requested time.
protected void	_init() Initialize the delay parameter.
void	attributeChanged(Attribute attribute) If the attribute is delay, then ensure that the value is non-negative.
java.lang.Object	clone(Workspace workspace) Clone the actor into the specified workspace.
void	fire() Read one token from the input.
void	initialize() Initialize the states of this actor.
boolean	postfire() Process the current input if it has not been processed.
void	preinitialize() Override the base class to declare that the output does not depend on the input in a firing.

Methods inherited from class ptolemy.actor.TypedAtomicActor

_addPort, _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, 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, 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, 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

delay

public Parameter delay

The amount of delay. The default for this parameter is 1.0. This parameter must contain a DoubleToken with a non-negative value, or an exception will be thrown when it is set.

_currentInput

protected Token _currentInput

Current input.

_currentOutput

protected Token _currentOutput

Current output.

_delay

protected double _delay

The amount of delay.

_delayedOutputTokens

protected CalendarQueue _delayedOutputTokens

A local event queue to store the delayed output tokens.

_causalityMarker

protected CausalityMarker _causalityMarker

A causality marker to store information about how pure events are causally related to trigger events.

Constructor Detail

TimedDelay

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

Construct an actor with the specified container and name. Constrain that the output type to be the same as the input type.

Parameters:

container - The composite entity to contain this one.

name - The name of this actor.

Throws:

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

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

Method Detail

attributeChanged

public void attributeChanged(Attribute attribute)
                      throws IllegalActionException

If the attribute is delay, then ensure that the value is non-negative.

NOTE: the newDelay may be 0.0, which may change the causality property of the model. We leave the model designers to decide whether the zero delay is really what they want.

Overrides:

attributeChanged in class NamedObj

Parameters:

attribute - The attribute that changed.

Throws:

IllegalActionException - If the delay is negative.

clone

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

Clone the actor into the specified workspace. Set a type constraint that the output type is the same as the that of input.

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

See Also:

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

fire

public void fire()
          throws IllegalActionException

Read one token from the input. Send out a token that is scheduled to produce at the current time to the output.

Specified by:

fire in interface Executable

Overrides:

fire in class AtomicActor

Throws:

IllegalActionException - If there is no director, or the input can not be read, or the output can not be sent.

initialize

public void initialize()
                throws IllegalActionException

Initialize the states of this actor.

Specified by:

initialize in interface Initializable

Overrides:

initialize in class AtomicActor

Throws:

IllegalActionException - If a derived class throws it.

postfire

public boolean postfire()
                 throws IllegalActionException

Process the current input if it has not been processed. Schedule a firing to produce the earliest output token.

Specified by:

postfire in interface Executable

Overrides:

postfire in class AtomicActor

Returns:

True if execution can continue into the next iteration.

Throws:

IllegalActionException - If scheduling to refire cannot be performed or the superclass throws it.

preinitialize

public void preinitialize()
                   throws IllegalActionException

Override the base class to declare that the output does not depend on the input in a firing.

Specified by:

preinitialize in interface Initializable

Overrides:

preinitialize in class AtomicActor

Throws:

IllegalActionException - If the superclass throws it.

_init

protected void _init()
              throws IllegalActionException,
                     NameDuplicationException

Initialize the delay parameter.

Throws:

IllegalActionException - If delay parameter cannot be set.

NameDuplicationException - If there already is a parameter named "delay".

_fireAt

protected void _fireAt(Time time)
                throws IllegalActionException

Request a firing of this actor at the specified time and throw an exception if the director does not agree to do it at the requested time. This is a convenience method provided because many actors need it.

If the executive director is a Ptides director, use fireAt(Actor, Time, IOPort) method because the pure event this actor generates is always safe to process.

Overrides:

_fireAt in class TypedAtomicActor

Parameters:

time - The requested time.

Throws:

IllegalActionException - If the director does not agree to fire the actor at the specified time, or if there is no director.