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 <i>period</i>,
starting from the time at which initialize() is invoked,
this actor initiates a sequence of output events with values given by
<i>values</i> and offset into the period given by <i>offsets</i>.
These parameters contain arrays, which are required to have the same length.
The <i>offsets</i> 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 <i>period</i>
then the corresponding output will never be produced.
<p>
The <i>values</i> parameter by default
contains an array of IntTokens with values 1 and 0. The default
<i>offsets</i> 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.
<p>
The type of the output can be any token type. This type is inferred
from the element type of the <i>values</i> parameter.
<p>
If the <i>period</i> 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.
<p>
This actor can generate finite sequences by specifying
a finite <i>numberOfCycles</i>. 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 <i>values</i>
array is produced).
<p>
The actor can also generate a finite sequence by giving a finite
value to the <i>stopTime</i> 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 <i>numberOfCycles</i>. Just like <i>numberOfCycles</i>,
when the stop time is reached, the actor's postfire() method returns
false.
<p>
If the <i>trigger</i> 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."
<p>
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 <i>reset</i> flag
of a modal model transition). Alternatively, you can assign
a value to the
the <i>period</i> of the Clock in the <i>setActions</i>
of the transition. This will also have the effect of
waking up the clock, but with a subtle difference.
If you use a <i>reset</i> transition, the clock starts
over upon entering the destination state. If you set
the <i>period</i> 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.
<p>
This actor is a timed source; the untimed version is Pulse.
Edward A. Lee, Haiyang Zheng
$Id: Clock.java 70398 2014-10-22 23:44:32Z cxh $
Ptolemy II 0.3
Yellow (eal)
Yellow (yuhong)
The number of cycles to produce, or UNBOUNDED to specify no limit.
This is an integer with default UNBOUNDED.
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}.
The period of the output waveform.
This is a double that defaults to 2.0.
The values that will be produced at the specified offsets.
This parameter must contain an ArrayToken, and it defaults to
{1, 0}