public class PeriodicTimer extends Timer
AsyncEvent whose fire method is
executed periodically according to the
given parameters. The clock associated with the Timer start time
must be identical to the the clock associated with the
Timer interval
The first firing is at the beginning of the first interval.
When an interval greater than 0 is given, the timer will fire
periodically. When an interval of 0 is given, the
PeriodicTimer will only fire once, unless restarted
after expiration, behaving like a OneShotTimer. In all
cases, when the timer is disabled when the firing time is
reached, that particular firing is lost (skipped). When
enabled at a later time, it will fire at its next scheduled
time.
When the clock time has already passed the beginning of the first
period, the PeriodicTimer will first fire according to
the PhasingPolicy.
Semantics details are described in the Timer pseudo-code
and compact graphic representation of state transitions.
Caution: This class is explicitly unsafe for multithreading when being changed. Code that mutates instances of this class should synchronize at a higher level.
| Constructor and Description |
|---|
PeriodicTimer(HighResolutionTime<?> start,
RelativeTime interval,
AsyncBaseEventHandler handler)
Creates a timer that executes its fire method periodically.
|
PeriodicTimer(HighResolutionTime<?> start,
RelativeTime interval,
AsyncBaseEventHandler handler,
TimeDispatcher dispatcher)
Creates a timer that executes its fire method periodically.
|
PeriodicTimer(HighResolutionTime<?> start,
RelativeTime interval,
AsyncEventHandler handler)
Deprecated.
since RTSJ 2.0
|
PeriodicTimer(HighResolutionTime<?> start,
RelativeTime interval,
Clock clock,
AsyncEventHandler handler)
Deprecated.
since RTSJ 2.0
|
| Modifier and Type | Method and Description |
|---|---|
ReleaseParameters<?> |
createReleaseParameters()
Creates a release parameters object with new objects containing
copies of the values corresponding to this timer.
|
void |
fire()
This should not be called for application code, except for
emulation.
|
Clock |
getClock()
Each instance can only be associated with a single clock, which
this method can obtain.
|
AbsoluteTime |
getFireTime()
Gets the time at which this
PeriodicTimer
is next expected to fire or to skip. |
AbsoluteTime |
getFireTime(AbsoluteTime dest)
Gets the time at which this
PeriodicTimer
is next expected to fire or to skip. |
RelativeTime |
getInterval()
Gets the interval of
this Timer. |
PeriodicTimer |
setInterval(RelativeTime interval)
Resets the
interval value of this. |
bindTo, destroy, disable, enable, getDispatcher, getEffectiveStartTime, getEffectiveStartTime, getStart, handledBy, isActive, isRunning, reschedule, setDispatcher, start, start, start, start, stopaddHandler, removeHandler, setHandler, unbindToaddHandler, handledBy, hasHandlers, removeHandler, setHandlerpublic PeriodicTimer(HighResolutionTime<?> start, RelativeTime interval, AsyncBaseEventHandler handler, TimeDispatcher dispatcher) throws StaticIllegalArgumentException, IllegalAssignmentError, StaticUnsupportedOperationException
start - The time that specifies when the first interval
begins, based on the clock associated with it. The first
firing of the timer is modified according to the
PhasingPolicy when the timer is started. A
start value of null is equivalent
to a RelativeTime of 0.
interval - The period of the timer. Its usage is based on the
clock specified by the clock parameter. When
interval is zero or null, the
period is ignored and the firing behavior of the
PeriodicTimer is that of a OneShotTimer.handler - The default handler to use for this event.
When null, no handler is associated with the
timer and nothing will happen when this event fires unless a
handler is subsequently associated with the timer
using the addHandler() or setHandler() method.dispatcher - The dispatcher to use for triggering this event.StaticIllegalArgumentException - when start or
interval is a RelativeTime
instance with a value less than zero; or the clocks associated with
start and
interval are not the identical.IllegalAssignmentError - when this PeriodicTimer
cannot hold references to handler,
clock and interval.StaticUnsupportedOperationException - when the Chronograph
associated with time is not a Clock.public PeriodicTimer(HighResolutionTime<?> start, RelativeTime interval, AsyncBaseEventHandler handler) throws StaticIllegalArgumentException, IllegalAssignmentError
PeriodicTimer(start, interval, handler, null).StaticIllegalArgumentExceptionIllegalAssignmentError@Deprecated public PeriodicTimer(HighResolutionTime<?> start, RelativeTime interval, AsyncEventHandler handler) throws StaticIllegalArgumentException, IllegalAssignmentError
PeriodicTimer(start, interval, handler, null).@Deprecated public PeriodicTimer(HighResolutionTime<?> start, RelativeTime interval, Clock clock, AsyncEventHandler handler) throws StaticIllegalArgumentException, StaticUnsupportedOperationException, IllegalAssignmentError
start - The time that specifies when the first interval
begins, based on the clock associated with it. The first
firing of the timer is modified according to the
PhasingPolicy when the timer is started. A
start value of null is equivalent
to a RelativeTime of 0.
interval - The period of the timer. Its usage is based on the
clock specified by the clock parameter. When
interval is zero or null, the
period is ignored and the firing behavior of the
PeriodicTimer is that of a OneShotTimer.clock - The clock to be used to time the start
and interval. When null, the system
Realtime clock is used. The Clock
association of the parameters start and
interval is always ignored.handler - The AsyncEventHandler that will be released
when fire is invoked. When null, no
handler is associated with this Timer and
nothing will happen when this event fires unless a handler
is subsequently associated with the timer using the
addHandler() or setHandler() method.StaticIllegalArgumentException - when start or
interval is a RelativeTime
instance with a value less than zero; or the clocks
associated with start and
interval are not the identical.IllegalAssignmentError - when this PeriodicTimer
cannot hold references to handler,
clock and interval.StaticUnsupportedOperationException - when the Chronograph
associated with time is not a Clock.public Clock getClock() throws StaticIllegalStateException
getClock in class TimerClock that is associated with
this.StaticIllegalStateException - when this has been destroyed.public ReleaseParameters<?> createReleaseParameters()
PeriodicTimer interval is greater than 0, creates
a PeriodicParameters object with a start time and period that
correspond to the next firing (or skipping) time, and interval,
of this timer. When the interval is 0, creates
an AperiodicParameters
object, since in this case the timer behaves like
a OneShotTimer.
When this timer is active, then the start time is the next firing
(or skipping) time returned as an AbsoluteTime. Otherwise,
the start time is the initial firing (or skipping) time, as set by
the last call to Timer.reschedule(javax.realtime.HighResolutionTime<?>), or when there
was no such call, by the constructor of this timer.
createReleaseParameters in class TimerPeriodicParameters. When the interval is zero returns
a new instance of AperiodicParameters.StaticIllegalStateException - when this Timer has
been destroyed.public AbsoluteTime getFireTime() throws java.lang.ArithmeticException, StaticIllegalStateException
PeriodicTimer
is next expected to fire or to skip.
When the PeriodicTimer is disabled, the returned
time is that of the skipping or firing.
When the PeriodicTimer is not-active it throws
StaticIllegalStateException.getFireTime in class Timerthis is next expected
to fire or to skip, in a newly allocated AbsoluteTime object.
When the timer has been created or re-scheduled
(see Timer.reschedule(HighResolutionTime))
using an instance of
RelativeTime for its time parameter, then it will return
the sum of the current time and the RelativeTime
remaining time before the timer is expected to fire/skip.
Within a periodic timer activation, the returned time is
associated with the start clock before the first fire (or skip) time,
and associated with the interval clock otherwise.java.lang.ArithmeticException - when the result does not fit
in the normalized format.StaticIllegalStateException - when this Timer
has been destroyed, or when it is not-active.public AbsoluteTime getFireTime(AbsoluteTime dest)
PeriodicTimer
is next expected to fire or to skip.
When the PeriodicTimer is disabled, the returned
time is that of the skipping.
When the PeriodicTimer is not-active it throws
StaticIllegalStateException.getFireTime in class Timerdest - The instance of AbsoluteTime which will be
updated in place and returned. The clock association of the
dest parameter is ignored. When
dest is null, a new object is
allocated for the result.AbsoluteTime passed as parameter,
with time values representing the absolute time at which
this is expected to fire or to skip. When the
dest parameter is null, the result
is returned in a newly allocated object.
When the timer has been created or re-scheduled
(see Timer.reschedule(HighResolutionTime))
using an instance of
RelativeTime for its time parameter then it will return
the sum of the current time and the RelativeTime
remaining time before the timer is expected to fire/skip.
Within a periodic timer activation, the returned time is
associated with the start clock before the first fire (or skip) time,
and associated with the interval clock otherwise.java.lang.ArithmeticException - when the result does not fit
in the normalized format.StaticIllegalStateException - when this Timer
has been destroyed, or when it is not-active.public RelativeTime getInterval()
this Timer.RelativeTime instance assigned as this
periodic timer's interval by the constructor or
setInterval(RelativeTime).StaticIllegalStateException - when this Timer
has been destroyed.public PeriodicTimer setInterval(RelativeTime interval)
interval value of this.interval - A RelativeTime object which is the interval
used to reset this Timer. A null
interval is interpreted as
RelativeTime(0,0).
The interval does not affect the first
firing (or skipping) of a timer's activation. At each firing
(or skipping), the next fire (or skip) time of an
active periodic timer is established based on the
interval currently in use. Resetting the
interval of an active periodic timer
only affects future fire (or skip) times after the next.
thisStaticIllegalArgumentException - when interval is a
RelativeTime instance with a value less than
zero, or the clock associated with interval is different
to the clock associated with this.IllegalAssignmentError - when this PeriodicTimer
cannot hold a reference to interval.StaticIllegalStateException - when this Timer has been
destroyed.public void fire()
this is enabled, it releases all handlers and then
reschedules itself for the next period without changing state.
When distabled, but active, it simply reschedules itself.
Otherwise it does nothing.fire in class AsyncEventOneShotTimer and
PeriodicTimer have slightly different semantics.