Package ptolemy.actor.lib.hoc

Class RealTimeComposite

  • All Implemented Interfaces:
    java.lang.Cloneable, Actor, Executable, FiringsRecordable, Initializable, TypedActor, Changeable, Debuggable, DebugListener, Derivable, Instantiable, ModelErrorHandler, MoMLExportable, Moveable, Nameable, HandlesInternalLinks
    @Deprecated
public class RealTimeComposite
extends MirrorComposite
    Deprecated.
    Use ThreadedComposite instead
    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$
    Author:
    Edward A. Lee
    Pt.AcceptedRating:
    Red (neuendor)
    Pt.ProposedRating:
    Yellow (eal)

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

    • 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 TypedCompositeActor
        Parameters:
        attribute - The attribute that changed.
        Throws:
        IllegalActionException - If the change is not acceptable to this container (not thrown in this base class).

      • clone

        public java.lang.Object clone​(Workspace workspace)
                       throws java.lang.CloneNotSupportedException
        Deprecated.
        Clone the object into the specified workspace. This overrides the base class to instantiate a new RealTimeDirector.
        Overrides:
        clone in class ReflectComposite
        Parameters:
        workspace - The workspace for the new object.
        Returns:
        A new NamedObj.
        Throws:
        java.lang.CloneNotSupportedException - If any of the attributes cannot be cloned.
        See Also:
        CompositeEntity.exportMoML(java.io.Writer, int, String)

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