2.1 The Monotonic Clock
The first ancillary component required by the reactor is a monotonic clock. A monotonic clock is essentially a counter which when read returns a value which is guaranteed never to be less than any previously read value and which increments at a fixed rate. This seems to be such an obviously useful feature that there must be a standard Java implementation; and there is - sometimes.
Early versions of Java only provided the System.currentTimeMillis call, which returns the integer number of milliseconds since the UNIX epoch at midnight on the 1st of January 1970. This is the wallclock time which can typically be adjusted by the system user. Because the wallclock time is adjustable in this way the values returned by System.currentTimeMillis cannot be guaranteed to be monotonic - being prone to large jumps forwards and backwards as the wallclock time is adjusted.
The situation was improved with the addition of the System.nanoTime call to Java 5.0. This will attempt to use the host system's monotonic clock when available. However, not all host systems provide a monotonic clock and under those circumstances System.nanoTime falls back to using the non-monotonic wallclock.
A final complication is that if the host does not have a standard monotonic clock, there may be one available as a hardware peripheral. This may be the case when running on on an embedded platform or using a hardware security peripheral.
Given that there is no standard way of effectively implementing a monotonic clock source across all possible target platforms this functionality has been factored out of the reactor core. Alternate monotonic clock implementations can therefore be provided as part of the utility package. The common interface to a monotonic clock implementation is defined in Listing 2.1.
The init method is called on reactor startup and is used to reset the monotonic clock to zero. This means that any value subsequently read back is equivalent to the reactor's uptime. The getMsTime method returns the current value of monotonic clock's timer counter. This encodes the number of milliseconds since the clock was reset as a Java native long integer.
There are three standard implementations of the monotonic clock source present in the utility package. Each one is applicable to a different host environment, as discussed in the following sections.
Subsections