ptolemy.actor.lib.hoc
Class RealTimeComposite

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.RealTimeComposite

All Implemented Interfaces:

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

Deprecated. Use ThreadedComposite instead

public class RealTimeComposite
extends MirrorComposite

This is a container for another actor that fires that other actor at real times corresponding to the input time stamps. Its ports are those of the contained actor. Given one or more events with time stamp t at the input ports, it queues the events to provide to a firing of the contained actor that is deferred to occur when real time (since start of execution, in seconds) exceeds or matches t. If real time already exceeds t, then the firing may occur immediately.

In addition to the parameters of the contained actor, this actor has a delay parameter. The value of this parameter is the minimum delay (in model time) between an input event and an output event that results from that input event. If the enclosed actor produces no output, or if the time of the outputs can be arbitrarily whatever current time is in the model when they are produced, then delay should be set to UNDEFINED. This is the default value. With this value, the enclosed actor is executed in a separate thread. If the firing produces output events, then those are given time stamps equal to the greater of the current model time of the enclosing model and the current real time at which the outputs are produced (in seconds since the start of execution). In this case, the enclosed actor does not regulate in any way the passage of time of the enclosing model, so the time stamps of the enclosing model could get arbitrarily far ahead of real time.

If the value of delay is 0.0 (zero), then the inside model is run in the same thread as the enclosing model. When this RealTimeComposite fires, the fire() method stalls until real time matches the current time of the model, and then invokes the enclosed model. If the enclosed model produces any outputs, then those outputs have time stamps equal to the time stamps of the input. Hence, from the perspective of DE semantics, this actor has zero delay, even though it can introduce real-time delay (which is indistinguishable from just taking a long time to evaluate the fire() method). Note that with delay = 0.0, this actor affects the model in way similar to the synchronizeToRealTime parameter of the director, except that only the events provided to this actor are synchronized to real time, rather than all events.

If the value of delay is positive, then the inside model is run in a separate thread, just as if the value were UNDEFINED, but in this case, this actor does regulate the passage of time of the enclosing model. In particular, given an event with time stamp t it prevents model time from advancing past t + delay until the firing triggered by the event has completed (which will be at some real time greater than t). Any outputs produced by that firing are assigned time stamps equal to the greater of t + delay and the current real time at which the output is produced.

For various reasons, this actor is tricky to use. The most natural domain to use it in is DE, providing it with input events with time stamps that specify when to perform some action, such as an actuator or display action. However, if the DE system is an open-loop system, then model time of the DE system can get very far ahead of the RealTimeComposite. It is helpful to use a feedback loop including this RealTimeComposite to keep the DE model from getting ahead, and to use the delay parameter judiciously as explained above.

This actor may also be used in SDF and SR if the period parameter of the director is set to something greater than zero. This actor consumes its inputs and schedules execution in its postfire() method, and hence in SR will behave as a strict actor (all inputs must be known for anything to happen).

FIXME: For actors that are triggered by internal calls to fireAt(), it seems that the delay needs to be no larger than the smallest increment between calls to fireAt(). Is this correct? Why?

FIXME: If there is a PortParameter, the parameter gets updated when the fire() method of this composite is invoked, which creates a nondeterminate interaction with the deferred execution. See CompositeActor.fire().

Since:

Ptolemy II 6.1

Version:

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

Author:

Edward A. Lee

See Also:

Serialized Form

Accepted Rating:

Red (neuendor)

Proposed Rating:

Yellow (eal)

Nested Class Summary

private class	RealTimeComposite.InputFrame Deprecated. Bundle of a token and the input port at which it arrived.
private static class	RealTimeComposite.OutputFrame Deprecated. Bundle of a token and the output port at which it arrived.
private static class	RealTimeComposite.QueuedToken Deprecated. Bundle of a token and the input port and channel at which it arrived.
private class	RealTimeComposite.RealTimeDirector Deprecated. This is a specialized director that defers firing of the contained actors until real-time matches the time stamp of provided inputs.

Nested classes/interfaces inherited from class ptolemy.actor.lib.hoc.MirrorComposite

MirrorComposite.MirrorCompositeContents

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

CompositeEntity.ContainedObjectsIterator

Field Summary

private double	_delayValue Deprecated. The cached value of the delay parameter.
private java.util.List<Time>	_fireAtTimes Deprecated. Queue of times at which inside actors have requested firings.
private java.util.concurrent.DelayQueue<RealTimeComposite.InputFrame>	_inputFrames Deprecated. Queue of unprocessed input events.
private java.util.List<RealTimeComposite.OutputFrame>	_outputFrames Deprecated. Queue of unprocessed output events.
private long	_realStartTime Deprecated. The real time at which the model begins executing, in milliseconds.
private java.util.Queue<Time>	_responseTimes Deprecated. Queue of times at which responses to firings are expected.
Parameter	delay Deprecated. The maximum model-time delay between the input events and the output events.

Fields inherited from class ptolemy.actor.CompositeActor

_actorFiringListeners, _causalityInterface, _initializables, _notifyingActorFiring, _publishedPorts, _publisherRelations, _stopRequested

Fields inherited from class ptolemy.kernel.CompositeEntity

_levelCrossingLinks

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

RealTimeComposite(CompositeEntity container, java.lang.String name)
Deprecated. Create an actor with a name and a container.

Method Summary

void	attributeChanged(Attribute attribute) Deprecated. React to a change in an attribute.
boolean	fireContainedActors() Deprecated. Invoke iterations on the contained actor of the container of this director repeatedly until either it runs out of input data or prefire() returns false.

Methods inherited from class ptolemy.actor.lib.hoc.MirrorComposite

_addEntity, _addPort, _exportMoMLContents, _removeEntity, _removePort, clone, newPort

Methods inherited from class ptolemy.actor.TypedCompositeActor

_addRelation, _checkTypesFromTo, _typeConstraintsFromTo, newRelation, resolveTypes, typeConstraintList, typeConstraints

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.Entity

connectedPortList, connectedPorts, getPorts, linkedRelationList, linkedRelations, portList, removeAllPorts

Methods inherited from class ptolemy.kernel.InstantiableNamedObj

_setParent, 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, _removeAttribute, _splitName, _stripNumericSuffix, addChangeListener, addDebugListener, 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

Methods inherited from interface ptolemy.actor.Actor

createReceivers, getCausalityInterface, getDirector, getExecutiveDirector, getManager, inputPortList, newReceiver, outputPortList

Methods inherited from interface ptolemy.actor.Executable

fire, isFireFunctional, isStrict, iterate, postfire, prefire, stop, stopFire, terminate

Methods inherited from interface ptolemy.actor.Initializable

addInitializable, initialize, 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

delay

public Parameter delay

Deprecated.

The maximum model-time delay between the input events and the output events. This is a double that defaults to UNDEFINED.

_delayValue

private double _delayValue

Deprecated.

The cached value of the delay parameter.

_fireAtTimes

private java.util.List<Time> _fireAtTimes

Deprecated.

Queue of times at which inside actors have requested firings. This queue is accessed from multiple threads, so it must be thread safe.

_inputFrames

private java.util.concurrent.DelayQueue<RealTimeComposite.InputFrame> _inputFrames

Deprecated.

Queue of unprocessed input events.

_outputFrames

private java.util.List<RealTimeComposite.OutputFrame> _outputFrames

Deprecated.

Queue of unprocessed output events. This queue is accessed from multiple threads, so it must be thread safe.

_realStartTime

private long _realStartTime

Deprecated.

The real time at which the model begins executing, in milliseconds.

_responseTimes

private java.util.Queue<Time> _responseTimes

Deprecated.

Queue of times at which responses to firings are expected. This is accessed only from the Director action methods, which run in a single thread, so it need not by thread safe.

Constructor Detail

RealTimeComposite

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

Deprecated.

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.

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.

Method Detail

attributeChanged

public void attributeChanged(Attribute attribute)
                      throws IllegalActionException

Deprecated.

React to a change in an attribute. This method is called by a contained attribute when its value changes. In this base class, the method does nothing. In derived classes, this method may throw an exception, indicating that the new attribute value is invalid. It is up to the caller to restore the attribute to a valid value if an exception is thrown.

Overrides:

attributeChanged in class NamedObj

Parameters:

attribute - The attribute that changed.

Throws:

IllegalActionException - If the change is not acceptable to this container (not thrown in this base class).

fireContainedActors

public boolean fireContainedActors()
                            throws IllegalActionException

Deprecated.

Invoke iterations on the contained actor of the container of this director repeatedly until either it runs out of input data or prefire() returns false. If postfire() of any actor returns false, then return false. Otherwise, return true.

Returns:

True to allow the thread to continue executing.

Throws:

IllegalActionException - If any called method of of the contained actor throws it, or if the contained actor is not opaque.