Package ptolemy.actor.lib

Class Clock

  • All Implemented Interfaces:
    java.lang.Cloneable, Actor, Executable, FiringsRecordable, Initializable, TimedActor, TypedActor, Changeable, Debuggable, DebugListener, Derivable, Instantiable, ModelErrorHandler, MoMLExportable, Moveable, Nameable
    Direct Known Subclasses:
    ListenClock, TriggeredClock, VariableClock
    @Deprecated
public class Clock
extends TimedSource
    Deprecated.
    Use DiscreteClock.
    This actor produces a periodic signal, a sequence of events at regularly spaced intervals. At the beginning of each time interval of length given by period, starting from the time at which initialize() is invoked, this actor initiates a sequence of output events with values given by values and offset into the period given by offsets. These parameters contain arrays, which are required to have the same length. The offsets array contains doubles, which must be nondecreasing and nonnegative, or an exception will be thrown when it is set. If any entry is greater than or equal to the period then the corresponding output will never be produced.

    The values parameter by default contains an array of IntTokens with values 1 and 0. The default offsets array is {0.0, 1.0}. Thus, the default output will be alternating 1 and 0 with 50% duty cycle. The default period is 2.0.

    The type of the output can be any token type. This type is inferred from the element type of the values parameter.

    If the period is changed at any time, either by providing an input or by changing the parameter, then the new period will take effect as soon as possible. That is, if there is already a period in progress, it may be cut short if the new period is shorter so that its time matches the new period. But it will only be cut short if current time has not passed the cycle start time plus the new period. Otherwise, the period in progress will run to completion.

    This actor can generate finite sequences by specifying a finite numberOfCycles. The numberOfCycles has a default value UNBOUNDED, indicating infinite length of executions. If numberOfCycles is a positive number, once the specified number of cycles has been completed, then this actor returns false from the postfire() method, which indicates to the director that the actor should not be fired again. (A cycle is "completed" each time the last event in the values array is produced).

    The actor can also generate a finite sequence by giving a finite value to the stopTime parameter. This gives a time rather than a number of cycles, and thus can be used to stop the clock in the middle of a cycle, unlike numberOfCycles. Just like numberOfCycles, when the stop time is reached, the actor's postfire() method returns false.

    If the trigger input is connected, then an output will only be produced if a input has been received since the last output. The trigger input has no effect on the first output. After the first output event, no further output event will be produced until a time greater than or equal to the time at which a trigger input is received. At that time, the output produced will have whatever value would have been produced if the trigger input was not connected. Note that this trigger is typically useful in a feedback situation, where the output of the clock eventually results in a trigger input. If the time-stamp of that trigger input is less than the time between clock events, then the clock will behave as if there were no trigger input. Otherwise, it will "skip beats."

    This actor can be a bit tricky to use inside a ModalModel. In particular, if the actor is in a state refinement, then it may "skip a beat" because of the state not being the current state at the time of the beat. If this occurs, the clock will simply stop firing, and will produce no further outputs. To prevent this, the clock may be reinitialized (by setting the reset flag of a modal model transition). Alternatively, you can assign a value to the the period of the Clock in the setActions of the transition. This will also have the effect of waking up the clock, but with a subtle difference. If you use a reset transition, the clock starts over upon entering the destination state. If you set the period parameter instead, then the clock behaves as if it had been running all along (except that its period may get changed). Thus, in the first case, the output events are aligned with the time of the transition, while in the second case, they are aligned with the start time of the model execution.

    This actor is a timed source; the untimed version is Pulse.

    Since:
    Ptolemy II 0.3
    Version:
    $Id$
    Author:
    Edward A. Lee, Haiyang Zheng
    Pt.AcceptedRating:
    Yellow (yuhong)
    Pt.ProposedRating:
    Yellow (eal)

    • Field Detail

      • numberOfCycles

        public Parameter numberOfCycles
        Deprecated.
        The number of cycles to produce, or UNBOUNDED to specify no limit. This is an integer with default UNBOUNDED.

      • offsets

        public Parameter offsets
        Deprecated.
        The offsets at which the specified values will be produced. This parameter must contain an array of doubles, and it defaults to {0.0, 1.0}.

      • period

        public PortParameter period
        Deprecated.
        The period of the output waveform. This is a double that defaults to 2.0.

      • values

        public Parameter values
        Deprecated.
        The values that will be produced at the specified offsets. This parameter must contain an ArrayToken, and it defaults to {1, 0}

      • _cycleCount

        protected transient int _cycleCount
        Deprecated.
        The count of cycles executed so far, or 0 before the start.

      • _cycleStartTime

        protected transient Time _cycleStartTime
        Deprecated.
        The most recent cycle start time.

      • _enabled

        protected transient boolean _enabled
        Deprecated.
        Indicator of whether the specified number of cycles have been completed. Also used in derived classes to turn on and off the clock.

      • _firstOutputProduced

        protected transient boolean _firstOutputProduced
        Deprecated.
        Indicator of whether the first output has been produced.

      • _nextOutputTime

        protected transient Time _nextOutputTime
        Deprecated.
        The time for the next output.

      • _offsets

        protected transient double[] _offsets
        Deprecated.
        Cache of offsets array value.

      • _outputProduced

        protected transient boolean _outputProduced
        Deprecated.
        Indicator of whether an output was produced in this iteration.

      • _phase

        protected transient int _phase
        Deprecated.
        The phase of the next output.

      • _tentativeNextOutputTime

        protected transient Time _tentativeNextOutputTime
        Deprecated.
        The tentative time for the next output.

    • Method Detail

      • attributeChanged

        public void attributeChanged​(Attribute attribute)
                      throws IllegalActionException
        Deprecated.
        If the argument is the offsets parameter, check that the array is nondecreasing and has the right dimension; if the argument is period, check that it is positive. Other sanity checks with period and values are done in the fire() method.
        Overrides:
        attributeChanged in class TimedSource
        Parameters:
        attribute - The attribute that changed.
        Throws:
        IllegalActionException - If the offsets array is not nondecreasing and nonnegative, or if the director will not respect the fireAt() call.

      • clone

        public java.lang.Object clone​(Workspace workspace)
                       throws java.lang.CloneNotSupportedException
        Deprecated.
        Clone the actor into the specified workspace. This calls the base class and then sets the parameter public members to refer to the parameters of the new actor.
        Overrides:
        clone in class TypedAtomicActor
        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
        Deprecated.
        Output the current value of the clock if the time is right and, if connected, a trigger has been received.
        Specified by:
        fire in interface Executable
        Overrides:
        fire in class Source
        Throws:
        IllegalActionException - If the value in the offsets parameter is encountered that is greater than the period, or if there is no director.

      • initialize

        public void initialize()
                throws IllegalActionException
        Deprecated.
        Schedule the first firing and initialize local variables.
        Specified by:
        initialize in interface Initializable
        Overrides:
        initialize in class TimedSource
        Throws:
        IllegalActionException - If the parent class throws it, or if the values parameter is not a row vector, or if the fireAt() method of the director throws it, or if the director will not respect the fireAt() call.

      • postfire

        public boolean postfire()
                 throws IllegalActionException
        Deprecated.
        Update the state of the actor and schedule the next firing, if appropriate.
        Specified by:
        postfire in interface Executable
        Overrides:
        postfire in class TimedSource
        Returns:
        True if execution can continue into the next iteration.
        Throws:
        IllegalActionException - If the director throws it when scheduling the next firing.

      • _catchUp

        protected void _catchUp()
                 throws IllegalActionException
        Deprecated.
        Catch up the tentative view of what the next output time should be. This sets _tentativeNextOutputTime to a value that is equal to or greater than current time, and it updates _tentativePhase and _tentativeCycleStartTime to correspond with this _tentativeNextOutputTime. If _tentativeNextOutputTime is already equal to or greater than current time, then do nothing.
        Throws:
        IllegalActionException - If the period is invalid.

      • _getValue

        protected Token _getValue​(int index)
                   throws IllegalActionException
        Deprecated.
        Get the specified output value, checking the form of the values parameter.
        Parameters:
        index - The index of the output values.
        Returns:
        A token that contains the output value.
        Throws:
        IllegalActionException - If the index is out of the range of the values parameter.

      • _isTimeForOutput

        protected boolean _isTimeForOutput()
                            throws IllegalActionException
        Deprecated.
        Return true if the current time is the right time for an output.
        Returns:
        True if the current time matches the _nextOutputTime.
        Throws:
        IllegalActionException - If the time is not right an a refiring cannot be requested.

      • _updateTentativeValues

        protected void _updateTentativeValues()
                               throws IllegalActionException
        Deprecated.
        Copy values committed in initialize() or in the last postfire() into the corresponding tentative variables. In effect, this loads the last known good value for these variables, which is particularly important if time has gone backwards. This is done in a protected method because derived classes may want to override it.
        Throws:
        IllegalActionException - Not thrown in this base class.

      • _updateStates

        protected void _updateStates()
                      throws IllegalActionException
        Deprecated.
        Update the states and request refiring if necessary.
        Throws:
        IllegalActionException - If the numberOfCycles parameter does not contain a valid parameter or can not request refiring, or if the director will not respect the fireAt() call..