javax.realtime
Class Clock

java.lang.Object
  javax.realtime.Clock

Direct Known Subclasses:

HighResolutionClock, RealtimeClock

public abstract class Clock

extends Object

A clock advances from the past, through the present, into the future. It has a concept of now that can be queried through Clock.getTime(), and it can have events queued on it which will be fired when their appointed time is reached. There are many possible subclasses of clocks: real-time clocks, user time clocks, simulation time clocks. The idea of using multiple clocks may at first seem unusual but we allow it as a possible resource allocation strategy. Consider a real-time system where the natural events of the system have different tolerances for jitter (jitter refers to the distribution of the differences between when the events are actually raised or noticed by the software and when they should have really occurred according to time in the real-world). Assume the system functions properly if event A is noticed or raised within plus or minus 100 seconds of the actual time it should occur but event B must be noticed or raised within 100 microseconds of its actual time. Further assume, without loss of generality, that events A and B are periodic. An application could then create two instances of PeriodicTimer based on two clocks. The timer for event B should be based on a Clock which checks its queue at least every 100 microseconds but the timer for event A could be based on a Clock that checked its queue only every 100 seconds. This use of two clocks reduces the queue size of the accurate clock and thus queue management overhead is reduced.

Author:

Angelo Corsaro, Morgan Deters

Constructor Summary

Clock()
Constructor for the abstract class.

Method Summary

abstract RelativeTime	getEpochOffset() Gets the relative time of the offset of the epoch of this Clock from the Epoch.
static Clock	getRealtimeClock() There is always one clock object available: a realtime clock that advances in sync with the external world> This is the default Clock.
abstract RelativeTime	getResolution() Return the resolution of the clock -- the interval between ticks.
abstract AbsoluteTime	getTime() Return the current time in a freshly allocated object.
abstract AbsoluteTime	getTime(AbsoluteTime time) Return the current time in an existing object.
abstract void	setResolution(RelativeTime resolution) Set the resolution of this.

Methods inherited from class java.lang.Object

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

Constructor Detail

Clock

public Clock()

Constructor for the abstract class.

Method Detail

getEpochOffset

public abstract RelativeTime getEpochOffset()

Gets the relative time of the offset of the epoch of this Clock from the Epoch. The realtime Clock returns RelativeTime(0,0).

Returns:

a newly-allocated RelativeTime object representing the offset of the epoch; the returned object is associated with this Clock

Throws:

UnsupportedOperationException - if this Clock does not have a concept of dates

Since:

0.4.0

getRealtimeClock

public static Clock getRealtimeClock()

There is always one clock object available: a realtime clock that advances in sync with the external world> This is the default Clock.

Returns:

an instance of the default Clock.

getResolution

public abstract RelativeTime getResolution()

Return the resolution of the clock -- the interval between ticks.

Returns:

A RelativeTime object representing the resolution of this.

setResolution

public abstract void setResolution(RelativeTime resolution)

Set the resolution of this. For some hardwhere clocks setting resolution impossible and if called on those nothing happens.

Implementation Note: If the requested resolution overceeds the one obtainable by the underlying hardware this method guarantees that the finest resolution possible is set.

Parameters:

resolution - The new resolution of this.

getTime

public abstract AbsoluteTime getTime()

Return the current time in a freshly allocated object.

Returns:

An AbsoluteTime object representing the current time.

getTime

public abstract AbsoluteTime getTime(AbsoluteTime time)

Return the current time in an existing object. The time represented by the given AbsoluteTime is changed some time between the invocation of the method and the return of the method.

Parameters:

time - The AbsoluteTime object which will have its time changed; if null, this call has no effect

Returns:

time