javax.realtime

Class Timer

java.lang.Object

javax.realtime.AsyncBaseEvent

javax.realtime.AsyncEvent

javax.realtime.Timer

All Implemented Interfaces:

ActiveEvent<Timer,TimeDispatcher>, Releasable<Timer,TimeDispatcher>

Direct Known Subclasses:

OneShotTimer, PeriodicTimer

public abstract class Timer
extends AsyncEvent
implements ActiveEvent<Timer,TimeDispatcher>

A timer is a timed event that measures time according to a given Clock. This class defines basic functionality available to all timers. Applications will generally use either PeriodicTimer to create an event that is fired repeatedly at regular intervals, or OneShotTimer for an event that just fires once at a specific time. A timer is always associated with at least one Clock, which provides the basic facilities of something that ticks along following some time line (realtime, CPU-time, user-time, simulation-time, etc.). All timers are created disabled and do nothing until start() is called.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	Timer(HighResolutionTime<?> time, AsyncEventHandler handler, TimeDispatcher dispatcher) Creates a timer that fires according to the given time based on the Clock associated with time and is dispatched by the specified dispatcher.
protected	Timer(HighResolutionTime<?> time, Clock clock, AsyncEventHandler handler) Creates a timer that fires according to the given time, which must be based on the supplied Clock clock (if any), and is handled by the specified AsyncEventHandler handler.

Method Summary

Modifier and Type	Method and Description
void	bindTo(java.lang.String happening) Deprecated. RTSJ 2.0
ReleaseParameters<?>	createReleaseParameters() Creates a ReleaseParameters object appropriate to the timing characteristics of this event.
void	destroy() Deprecated. since RTSJ 2.0
void	disable() Disables this timer, preventing it from firing.
void	enable() Re-enables this timer after it has been disabled.
Clock	getClock() Obtains the instance of Clock on which this timer is based.
TimeDispatcher	getDispatcher() Obtain the current dispatcher for this event.
AbsoluteTime	getEffectiveStartTime() Returns a newly-created time representing the time when the timer actually started, or when the timer has been rescheduled, the effective start time after the reschedule.
AbsoluteTime	getEffectiveStartTime(AbsoluteTime dest) Updates dest to represent the time when the timer actually started, or when the timer has been rescheduled, the effective start time after the reschedule.
AbsoluteTime	getFireTime() Gets the time at which this Timer is expected to fire.
AbsoluteTime	getFireTime(AbsoluteTime dest) Gets the time at which this Timer is expected to fire.
HighResolutionTime<?>	getStart() Gets the start time of this Timer.
boolean	handledBy(AsyncEventHandler handler) Determines whether or not the handler given as the parameter is associated with this.
boolean	isActive() Determines the activation state of this happening, i.e., it has been started.
boolean	isRunning() Determines if this is active and is enabled such that when the given time occurs it will fire the event.
void	reschedule(HighResolutionTime<?> time) Changes the scheduled time for this event.
TimeDispatcher	setDispatcher(TimeDispatcher dispatcher) Change the current dispatcher for this event.
void	start() Starts this timer.
void	start(boolean disabled) Starts this timer.
void	start(boolean disabled, PhasingPolicy phasingPolicy) Starts the timer with the specified PhasingPolicy and the specified disabled state.
void	start(PhasingPolicy phasingPolicy) Starts the timer with the specified PhasingPolicy.
boolean	stop() Stops a timer when it is active and changes its state to inactive and disabled.

Methods inherited from class javax.realtime.AsyncEvent

addHandler, fire, removeHandler, setHandler, unbindTo

Methods inherited from class javax.realtime.AsyncBaseEvent

addHandler, handledBy, hasHandlers, removeHandler, setHandler

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Timer

protected Timer(HighResolutionTime<?> time,
                AsyncEventHandler handler,
                TimeDispatcher dispatcher)
         throws StaticIllegalArgumentException,
                StaticUnsupportedOperationException,
                IllegalAssignmentError

Creates a timer that fires according to the given time based on the Clock associated with time and is dispatched by the specified dispatcher.

Parameters:

time - The parameter used to determine when to fire the event. A time value of null is equivalent to a RelativeTime of 0, and in this case the Timer fires immediately upon a call to start().

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 object used to interface between this timer and its associated clock. When null, the system default dispatcher is used.

Throws:

StaticIllegalArgumentException - when time is a negative RelativeTime value.

StaticUnsupportedOperationException - when time has a Chronograph is not a clock.

IllegalAssignmentError - when this Timer cannot hold references to handler and clock.

Since:

RTSJ 2.0

Timer

protected Timer(HighResolutionTime<?> time,
                Clock clock,
                AsyncEventHandler handler)
         throws StaticIllegalArgumentException,
                StaticUnsupportedOperationException,
                IllegalAssignmentError

Creates a timer that fires according to the given time, which must be based on the supplied Clock clock (if any), and is handled by the specified AsyncEventHandler handler. The system default dispatcher will be used.

This constructor is slated for deprecation in a future release, and a constructor that does not receive a Clock argument should be used in preference.

Parameters:

time - The parameter used to determine when to fire the event. A time value of null is equivalent to a RelativeTime of 0, and in this case the Timer fires immediately upon a call to start().

clock - The clock on which to base this timer. When null, the clock associated with time is used.

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.

Throws:

StaticIllegalArgumentException - when time is a negative RelativeTime value or the supplied clock is not the Clock associated with time.

StaticUnsupportedOperationException - when time has a Chronograph that is not an instance of Clock.

IllegalAssignmentError - when this Timer cannot hold references to handler and clock.

Method Detail

getClock

public Clock getClock()
               throws StaticIllegalStateException

Obtains the instance of Clock on which this timer is based.

Returns:

the instance of Clock associated with this Timer.

Throws:

StaticIllegalStateException - when this Timer has been destroyed.

getStart

public HighResolutionTime<?> getStart()

Gets the start time of this Timer. Note that the start time uses copy semantics, so changes made to the value returned by this method do not affect the start time of this Timer.

Returns:

a reference to the time (or start) parameter used when constructing this Timer, ensuring the content has the original values.

Since:

RTSJ 2.0

getEffectiveStartTime

public AbsoluteTime getEffectiveStartTime()
                                   throws StaticIllegalStateException,
                                          java.lang.ArithmeticException

Returns a newly-created time representing the time when the timer actually started, or when the timer has been rescheduled, the effective start time after the reschedule.

Returns:

the time this actually started.

Throws:

StaticIllegalStateException - when the timer is not active or has been destroyed.

java.lang.ArithmeticException - when the result does not fit in the normalized format.

Since:

RTSJ 2.0

getEffectiveStartTime

public AbsoluteTime getEffectiveStartTime(AbsoluteTime dest)
                                   throws StaticIllegalStateException,
                                          java.lang.ArithmeticException

Updates dest to represent the time when the timer actually started, or when the timer has been rescheduled, the effective start time after the reschedule. When dest is null, behaves as if getEffectiveStartTime() had been called.

Parameters:

dest - An object used to store the time this actually started.

Returns:

the time when the timer actually started, or when it has been rescheduled, the effective start time after the reschedule.

Throws:

StaticIllegalStateException - when the timer is not active or has been destroyed.

java.lang.ArithmeticException - when the result does not fit in the normalized format.

Since:

RTSJ 2.0

getFireTime

public AbsoluteTime getFireTime()
                         throws StaticIllegalStateException,
                                java.lang.ArithmeticException

Gets the time at which this Timer is expected to fire. When the Timer is disabled, the returned time is that of the skipping or the firing. When the Timer is not-active, it throws StaticIllegalStateException.

Returns:

the absolute time at which this is expected to fire (release handlers or skip), in a newly allocated AbsoluteTime object. When the timer has been created or re-scheduled (see reschedule(javax.realtime.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. The clock association of the returned time is the clock on which this timer is based.

Throws:

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.

getFireTime

public AbsoluteTime getFireTime(AbsoluteTime dest)
                         throws StaticIllegalStateException,
                                java.lang.ArithmeticException

Gets the time at which this Timer is expected to fire. When the Timer is disabled, the returned time is that of the skipping or the firing. When the Timer is not-active it throws StaticIllegalStateException.

Parameters:

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

Returns:

the instance of AbsoluteTime passed as parameter, with time values representing the absolute time at which this is expected to fire (release its handlers or skip). When the dest parameter is null, the result is returned in a newly allocated object. When the timer has been created or rescheduled (see reschedule(javax.realtime.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. The clock association of the returned time is the clock on which this timer is based.

Throws:

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.

Since:

RTSJ 1.0.1

getDispatcher

public TimeDispatcher getDispatcher()

Obtain the current dispatcher for this event.

Specified by:

getDispatcher in interface ActiveEvent<Timer,TimeDispatcher>

Specified by:

getDispatcher in interface Releasable<Timer,TimeDispatcher>

Returns:

the dispatcher associated with this event.

setDispatcher

public TimeDispatcher setDispatcher(TimeDispatcher dispatcher)

Change the current dispatcher for this event. When dispatcher is null, the default dispatcher is restored.

Specified by:

setDispatcher in interface ActiveEvent<Timer,TimeDispatcher>

Returns:

the dispatcher associated with this event.

isActive

public boolean isActive()

Determines the activation state of this happening, i.e., it has been started.

Specified by:

isActive in interface ActiveEvent<Timer,TimeDispatcher>

Returns:

true when active, false otherwise.

Since:

RTSJ 2.0

isRunning

public boolean isRunning()
                  throws StaticIllegalStateException

Determines if this is active and is enabled such that when the given time occurs it will fire the event. Given the Timer current state it answers the question "Is firing expected?".

Specified by:

isRunning in interface ActiveEvent<Timer,TimeDispatcher>

Overrides:

isRunning in class AsyncBaseEvent

Returns:

true when the timer is active and enabled; otherwise false, when the timer has either not been started, it has been started but it is disabled, or it has been started and is now stopped.

Throws:

StaticIllegalStateException - when this Timer has been destroyed.

handledBy

public boolean handledBy(AsyncEventHandler handler)
                  throws StaticIllegalStateException

Description copied from class: AsyncEvent

Determines whether or not the handler given as the parameter is associated with this.

Overrides:

handledBy in class AsyncEvent

Parameters:

handler - An event handler to be added to the Timer

Returns:

true when handler is associated with this, otherwise false.

Throws:

StaticIllegalStateException - when this Timer has been destroyed.

Since:

RTSJ 1.0.1

createReleaseParameters

public ReleaseParameters<?> createReleaseParameters()
                                             throws StaticIllegalStateException

Creates a ReleaseParameters object appropriate to the timing characteristics of this event. The default is the most pessimistic: AperiodicParameters. This is typically called by code that is setting up a handler for this event that will fill in the parts of the release parameters for which it has values, e.g. cost.

Overrides:

createReleaseParameters in class AsyncBaseEvent

Returns:

a newly created ReleaseParameters object.

Throws:

StaticIllegalStateException - when this Timer has been destroyed.

enable

public void enable()
            throws StaticIllegalStateException

Re-enables this timer after it has been disabled. (See disable().) When the Timer is already enabled, this method does nothing. When the Timer is not-active, this method does nothing.

Specified by:

enable in interface ActiveEvent<Timer,TimeDispatcher>

Overrides:

enable in class AsyncBaseEvent

Throws:

StaticIllegalStateException - when this Timer has been destroyed.

disable

public void disable()
             throws StaticIllegalStateException

Disables this timer, preventing it from firing. It may subsequently be re-enabled. When the timer is disabled when its fire time occurs, then it will not release its handlers. However, a disabled timer created using an instance of RelativeTime for its time parameter continues to count while it is disabled, and no changes take place in a disabled timer created using an instance of AbsoluteTime. In both cases the potential firing is simply masked, or skipped. When the timer is subsequently re-enabled before its fire time or(?) it is enabled when its fire time occurs, then it will fire. It is important to note that this method does not delay the time before a possible firing. For example, when the timer is set to fire at time 42 and the disable() is called at time 30 and enable() is called at time 40 the firing will occur at time 42 (not time 52). These semantics imply also that firings are not queued. Using the above example, when enable was called at time 43 no firing will occur, since at time 42 this was disabled. When the Timer is already disabled, whether it is active or inactive, this method does nothing.

Specified by:

disable in interface ActiveEvent<Timer,TimeDispatcher>

Overrides:

disable in class AsyncBaseEvent

Throws:

StaticIllegalStateException - when this Timer has been destroyed.

start

public void start()
           throws StaticIllegalStateException

Starts this timer. A timer starts measuring time from when it is started; this method makes the timer active and enabled.

Specified by:

start in interface ActiveEvent<Timer,TimeDispatcher>

Throws:

StaticIllegalStateException - when this Timer has been destroyed, or when this timer is already active.

start

public void start(boolean disabled)
           throws StaticIllegalStateException

Starts this timer. A timer starts measuring time from when it is started. When disabled is true starts the timer making it active in a disabled state. When disabled is false this method behaves like the start() method.

Specified by:

start in interface ActiveEvent<Timer,TimeDispatcher>

Parameters:

disabled - When true, the timer will be active but disabled after it is started. When false this method behaves like the start() method.

Throws:

StaticIllegalStateException - when this Timer has been destroyed, or when this timer is active.

Since:

RTSJ 1.0.1

start

public void start(PhasingPolicy phasingPolicy)
           throws LateStartException,
                  StaticIllegalArgumentException

Starts the timer with the specified PhasingPolicy.

Parameters:

phasingPolicy - Determines what happens when the start is too late.

Throws:

LateStartException - when this method is called after its absolute start time and the phasingPolicy is PhasingPolicy.STRICT_PHASING.

StaticIllegalArgumentException - when the start time of this timer is not an absolute time, or phasingPolicy is null or, when this in not a periodic timer, ADJUST_FORWARD or ADJUST_BACKWARD.

Since:

RTSJ 2.0

start

public void start(boolean disabled,
                  PhasingPolicy phasingPolicy)
           throws LateStartException,
                  StaticIllegalArgumentException

Starts the timer with the specified PhasingPolicy and the specified disabled state.

Parameters:

disabled - It determines the mode of start: true for enabled and false for disabled for consistency with start(boolean).

phasingPolicy - It determines what happens when the start is too late.

Throws:

LateStartException - when this method is called after its absolute start time and the phasingPolicy is PhasingPolicy.STRICT_PHASING.

StaticIllegalArgumentException - when the start time of this timer is not an absolute time, or phasingPolicy is null or, when this in not a periodic timer, ADJUST_FORWARD or ADJUST_BACKWARD.

Since:

RTSJ 2.0

stop

public boolean stop()
             throws StaticIllegalStateException

Stops a timer when it is active and changes its state to inactive and disabled.

Specified by:

stop in interface ActiveEvent<Timer,TimeDispatcher>

Returns:

true when this was enabled and false otherwise.

Throws:

StaticIllegalStateException - when this Timer has been destroyed.

reschedule

public void reschedule(HighResolutionTime<?> time)
                throws StaticIllegalStateException,
                       StaticIllegalArgumentException

Changes the scheduled time for this event. This method can take either an AbsoluteTime or a RelativeTime for its argument, and the Timer will behave as if created using that type for its time parameter. The rescheduling will take place between the invocation and the return of the method.

Note that while the scheduled time is changed as described above, the rescheduling itself is applied only on the first firing (or on the first skipping when disabled) of a timer's activation. When reschedule is invoked after the current activation timer's firing, then the rescheduled time will be effective only upon the next start or startDisabled command (which may need to be preceded by a stop command).

When reschedule is invoked with a RelativeTime time on an active timer before its first firing/skipping, then the rescheduled firing/skipping time is relative to the time of invocation.

Parameters:

time - The time to reschedule for this event firing. When time is null, the previous time is still the time used for the Timer firing.

Throws:

StaticIllegalArgumentException - when time is a negative RelativeTime value.

StaticIllegalStateException - when this Timer has been destroyed.

destroy

@Deprecated
public void destroy()
                         throws StaticIllegalStateException

Deprecated. since RTSJ 2.0

Stops this from counting or comparing when active, removes from it all the associated handlers if any, and releases as many of its resources as possible back to the system. Every method invoked on a Timer that has been destroyed will throw StaticIllegalStateException.

Throws:

StaticIllegalStateException - when this Timer has been destroyed.

bindTo

@Deprecated
public void bindTo(java.lang.String happening)
                        throws StaticUnsupportedOperationException

Deprecated. RTSJ 2.0

Should not be called, since this was only meant for binding happenings to normal instances AsyncEvent, not to special subclasses.

Overrides:

bindTo in class AsyncEvent

Parameters:

happening - to which to bind

Throws:

StaticUnsupportedOperationException - when bindTo is called on a Timer.

Since:

RTSJ 1.0.1