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>

Jamaica Real-Time Specification for Java class Timer.

abstract super class of PeriodicTimer or OneShotTimer. These timers are asynchronous events that fire at a given time.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	Timer(HighResolutionTime<?> time, AsyncBaseEventHandler 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) Deprecated. since RTSJ 2.0

Method Summary

Modifier and Type	Method and Description
void	bindTo(String happening) Deprecated. since RTSJ 2.0
ReleaseParameters<?>	createReleaseParameters() createReleaseParameters creates the default release parameters for this event.
void	destroy() Deprecated. since RTSJ 2.0
protected void	finalize() Called by the garbage collector on an object when garbage collection determines that there are no more references to the object.
void	fire() fires this event unless firing is disabled and reschedules the timer in case it is periodic.
Clock	getClock() getClock returns the clock this timer was based on.
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() getFireTime returns the time at which this timer is expected to fire or skip firing (because it is disabled) next.
AbsoluteTime	getFireTime(AbsoluteTime dest) getFireTime returns the time at which this timer is expected to fire or skip firing (because it is disabled) next.
HighResolutionTime<?>	getStart() Gets the start time of this Timer.
boolean	isActive() Determines the activation state of this event, i.e., it has been started but not yet stopped again.
boolean	isRunning() isRunning returns true if this timer has been started (it is active) and it has not been disabled.
void	reschedule(HighResolutionTime<?> time) reschedule changes the time for this event.
TimeDispatcher	setDispatcher(TimeDispatcher dispatcher) Change the current dispatcher for this event.
void	start() start this timer, i.e., make it active and enabled
void	start(boolean disabled) start this timer, i.e., make it active.
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() stop stops this active timer changing its state to not-active and disabled.

Methods inherited from class javax.realtime.AsyncEvent

addHandler, handledBy, removeHandler, setHandler, unbindTo

Methods inherited from class javax.realtime.AsyncBaseEvent

addHandler, disable, enable, handledBy, hasHandlers, removeHandler, setHandler

Methods inherited from class java.lang.Object

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

Methods inherited from interface javax.realtime.ActiveEvent

disable, enable

Constructor Detail

Timer

@Deprecated
protected Timer(HighResolutionTime<?> time,
                            Clock clock,
                            AsyncEventHandler handler)

Deprecated. since RTSJ 2.0

Constructor to create a timer with the given time, clock and handler.

Throws:

StaticIllegalArgumentException - if time is a negative RelativeTime.

Parameters:

time - The time when this timer should fire. May be null, in this case this is equal to new RelativeTime(0, 0) and the firing will occur immediately after a call to start().

clock - the clock this timer should be based upon. May be null to use the default System.getRealtimeClock().

handler - The handler that will be released when this timer fires. May be null to have no handler until one will be added via addHandler.

Timer

protected Timer(HighResolutionTime<?> time,
                AsyncBaseEventHandler 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.

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.

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.

Since:

RTSJ 2.0

Method Detail

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>

Throws:

UnsupportedOperationException - always, since it is not yet implemented.

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>

Throws:

UnsupportedOperationException - always, since it is not yet implemented.

Returns:

the dispatcher associated with this event.

isRunning

public boolean isRunning()

isRunning returns true if this timer has been started (it is active) and it has not been disabled.

Specified by:

isRunning in interface ActiveEvent<Timer,TimeDispatcher>

Overrides:

isRunning in class AsyncBaseEvent

Returns:

true if this timer expects to fire.

isActive

public boolean isActive()

Description copied from interface: ActiveEvent

Determines the activation state of this event, i.e., it has been started but not yet stopped again.

Specified by:

isActive in interface ActiveEvent<Timer,TimeDispatcher>

Returns:

true when active, false otherwise.

start

public void start()

start this timer, i.e., make it active and enabled

Specified by:

start in interface ActiveEvent<Timer,TimeDispatcher>

start

public void start(boolean disabled)

start this timer, i.e., make it active.

Specified by:

start in interface ActiveEvent<Timer,TimeDispatcher>

Throws:

StaticIllegalStateException - if this timer is destroyed.

Parameters:

disabled - true to make this timer active but disabled.

start

public void start(PhasingPolicy phasingPolicy)
           throws LateStartException,
                  StaticIllegalArgumentException

Starts the timer with the specified PhasingPolicy.

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.

Parameters:

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

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.

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.

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.

Since:

RTSJ 2.0

stop

public boolean stop()

stop stops this active timer changing its state to not-active and disabled.

Specified by:

stop in interface ActiveEvent<Timer,TimeDispatcher>

Throws:

StaticIllegalStateException - if this timer is destroyed.

Returns:

true if this timer was active before the call, false if it was not.

createReleaseParameters

public ReleaseParameters<?> createReleaseParameters()

createReleaseParameters creates the default release parameters for this event. The default implementation creates AperiodicParemters without cost/ deadline and without overrun or miss handler.

Overrides:

createReleaseParameters in class AsyncEvent

Throws:

StaticIllegalStateException - if this timer is destroyed.

Returns:

An instance of ReleaseParameters appropriate for handlers for this event.

destroy

@Deprecated
public void destroy()

Deprecated. since RTSJ 2.0

destroy destroys this timer, i.e., stops it from counting. This will release important resources that were allocated for this timer, it may free a thread that was generated for this counter.

Throws:

StaticIllegalStateException - if this timer has been destroyed.

getClock

public Clock getClock()

getClock returns the clock this timer was based on.

Throws:

StaticIllegalStateException - if this timer has been destroyed.

Returns:

the clock of this timer.

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

Throws:

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

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

Returns:

the time this actually started.

Since:

RTSJ 2.0

getEffectiveStartTime

public AbsoluteTime getEffectiveStartTime(AbsoluteTime dest)
                                   throws StaticIllegalStateException,
                                          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.

Throws:

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

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

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.

Since:

RTSJ 2.0

getFireTime

public AbsoluteTime getFireTime()

getFireTime returns the time at which this timer is expected to fire or skip firing (because it is disabled) next.

Throws:

StaticIllegalStateException - if this timer has been destroyed or it is not active.

Returns:

a new instance of AbsoluteTime that holds the next firing time.

getFireTime

public AbsoluteTime getFireTime(AbsoluteTime dest)

getFireTime returns the time at which this timer is expected to fire or skip firing (because it is disabled) next.

Throws:

StaticIllegalStateException - if this timer has been destroyed or it is not active.

Parameters:

dest - the AbsoluteTime which will be updated and returned if not null. If dest is null, a new instance of AbsoluteTime will be returned.

Returns:

the updated given AbsoluteTime or a new instance that holds the next firing time.

reschedule

public void reschedule(HighResolutionTime<?> time)

reschedule changes the time for this event. This changes the first time a timer fires.

Throws:

StaticIllegalStateException - if this timer has been destroyed.

Parameters:

time - the new time parameter.

fire

public void fire()
          throws MITViolationException,
                 ArrivalTimeQueueOverflowException

fires this event unless firing is disabled and reschedules the timer in case it is periodic.

Overrides:

fire in class AsyncEvent

Throws:

MITViolationException

ArrivalTimeQueueOverflowException

finalize

protected void finalize()
                 throws Throwable

Description copied from class: Object

Called by the garbage collector on an object when garbage collection determines that there are no more references to the object. A subclass overrides the finalize method to dispose of system resources or to perform other cleanup.

The general contract of finalize is that it is invoked if and when the Java™ virtual machine has determined that there is no longer any means by which this object can be accessed by any thread that has not yet died, except as a result of an action taken by the finalization of some other object or class which is ready to be finalized. The finalize method may take any action, including making this object available again to other threads; the usual purpose of finalize, however, is to perform cleanup actions before the object is irrevocably discarded. For example, the finalize method for an object that represents an input/output connection might perform explicit I/O transactions to break the connection before the object is permanently discarded.

The finalize method of class Object performs no special action; it simply returns normally. Subclasses of Object may override this definition.

The Java programming language does not guarantee which thread will invoke the finalize method for any given object. It is guaranteed, however, that the thread that invokes finalize will not be holding any user-visible synchronization locks when finalize is invoked. If an uncaught exception is thrown by the finalize method, the exception is ignored and finalization of that object terminates.

After the finalize method has been invoked for an object, no further action is taken until the Java virtual machine has again determined that there is no longer any means by which this object can be accessed by any thread that has not yet died, including possible actions by other objects or classes which are ready to be finalized, at which point the object may be discarded.

The finalize method is never invoked more than once by a Java virtual machine for any given object.

Any exception thrown by the finalize method causes the finalization of this object to be halted, but is otherwise ignored.

JamaicaVM: Realtime code requires special care when using finalize:

NOTE: The use of finalize() is strongly discouraged for realtime or safety-critical code. This method should only be used for debugging purposes. If used as a last resort to reclaim non-memory resources, finalize() should indicate the resource leak with a loud error message.

There is no guarantee that finalize() will be called, the memory management may decide not to reclaim this object's memory or to delay the call to finalize() to an unspecified point in time. It is therefore recommended never to use the finalize method to release any resources (files, network connections, non-Java memory, etc.) since releasing of these resource may be delayed perpetually.

The order of finalization is not specified, i.e., the finalize method of any two objects that become unreachable may be called in an arbitrary order. It therefore has to be assumed that when finalize() is called on an object, that the finalize() method of any object that is only reachable through this object() has been called as well or is called simultaneously by another thread.

The presence of a finalize-method in any sub-class of Object causes the reclamation of the memory of this object to be delayed until the finalize() method has been executed. The finalize() method is typically executed by the finalizer thread (that may run at a low priority) or by a call to Runtime.runFinalization().

Any code sequence that creates instances of a class that defines a finalize() method must therefore ensure that sufficient CPU time is allocated to the finalizer thread or that Runtime.runFinalization() is called regularly such that the finalize() methods can be executed and the object's memory can be reclaimed.

The finalize method itself should never block or run for long times since it would otherwise block the finalizer thread or the thread that called Runtime.runFinalization() and prevent the execution other finalize() method and consequently prevent the reclamation of these object's memory.

For objects that are allocated in a javax.realtime.memory.ScopedMemory, the finalize() methods will be called when this scoped memory is exited by the last thread. Unlike HeapMemory, which is controlled by the garbage collector, ScopedMemory provides a defined execution point for the finalize() mehods and it is therefore safer to use finalize() here.

Overrides:

finalize in class AsyncBaseEvent

Throws:

Throwable - the Exception raised by this method

See Also:

WeakReference, PhantomReference

bindTo

@Deprecated
public void bindTo(String happening)
                        throws UnsupportedOperationException

Deprecated. since 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

Throws:

UnsupportedOperationException - everytime, since this operation is not supported.

Parameters:

happening - to which to bind.