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
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,v 1.17 2007/12/07 06:26:07 cxh Exp $
- Author:
- Edward A. Lee
- See Also:
- Serialized Form
- Accepted Rating:
- Proposed Rating:
|
Field Summary |
Parameter |
delay
The maximum model-time delay between the input events and the
output events. |
| 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 |
void |
attributeChanged(Attribute attribute)
React to a change in an attribute. |
boolean |
fireContainedActors()
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.CompositeActor |
_actorFiring, _actorFiring, _createReceivers, _finishedAddEntity, _setDirector, addActorFiringListener, addInitializable, addPiggyback, connectionsChanged, fire, getDirector, getExecutiveDirector, getFunctionDependency, getManager, initialize, inputPortList, isFireFunctional, isOpaque, isStrict, iterate, newInsideReceiver, newReceiver, outputPortList, postfire, prefire, preinitialize, recordFiring, removeActorFiringListener, removeInitializable, removePiggyback, requestChange, setContainer, setDirector, setManager, stop, stopFire, terminate, wrapup |
| Methods inherited from class ptolemy.kernel.CompositeEntity |
_adjustDeferrals, _description, _removeRelation, _validateSettables, allAtomicEntityList, allCompositeEntityList, allowLevelCrossingConnect, classDefinitionList, connect, connect, containedObjectsIterator, deepEntityList, deepGetEntities, entityList, entityList, exportLinks, getAttribute, getEntities, getEntity, getPort, getRelation, getRelations, isAtomic, 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, attributeList, attributeList, attributeTypeChanged, clone, deepContains, depthInHierarchy, description, description, event, executeChangeRequests, exportMoML, exportMoML, exportMoML, exportMoML, exportMoMLPlain, getAttribute, getAttributes, getChangeListeners, getClassName, getDerivedLevel, getDerivedList, getDisplayName, getFullName, getModelErrorHandler, getName, getName, getSource, handleModelError, isDeferringChangeRequests, isOverridden, isPersistent, 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 |
delay
public Parameter delay
- The maximum model-time delay between the input events and the
output events. This is a double that defaults to UNDEFINED.
RealTimeComposite
public RealTimeComposite(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.
- 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.
attributeChanged
public void attributeChanged(Attribute attribute)
throws IllegalActionException
- 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
- 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.