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 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.
2.1.1 Fixed Up Wallclock
This monotonic clock source is the most generally applicable implementation and should work across all supported platforms. It uses the standard wallclock as a clock source and then attempts to detect and correct for any user adjustments. This ensures that the clock source is monotonic, but it will increment at an unpredictable rate whenever adjustments to the wallclock are made. This is the default option since it is applicable to all platforms and is provided in the utilities package as FixedUpMonotonicClock.
2.1.2 Java Monotonic Clock
This monotonic clock source may be used when running the Reaction framework in a Java environment which provides System.nanoTime and the underlying operating system is known to provide the JVM with a monotonic clock. This is typically the case with POSIX compliant systems that provide CLOCK_MONOTONIC support. This option is provided in the utilities package as JavaMonotonicClock.
2.1.3 Native Monotonic Clock
This monotonic clock source may be used when running the Reaction framework on a platform which provides a non-standard native monotonic clock, often as a dedicated hardware peripheral. This assumes that monotonic clock support is provided using native routines accessed via the Java native interface[6]. The class definition is provided in the utilities package as NativeMonotonicClock but no native library is provided as this is obviously platform specific.