CompatTime

java.lang.Object
- vona.compat.CompatTime

```
public class CompatTime
extends java.lang.Object
```
Vona's java time compatibility utilities.

This class provides sleep(double) and getTime() implementations which attempt to provide high resolution.

For sleep() "resolution" means essentially the minimum sleep duration, and also the granularity of the sleep. That is, a request to sleep for S seconds will actually sleep at least ceil(S)*resolution seconds.

For getTime() "resolution" means the minimum time a caller must wait between successive calls if the caller expects the return value to differ.

All notions of "time" in this class are wall-clock time relative to an arbitrary epoch.

Java provides multiple APIs for asking the system what time it is. See the TIME_STRATEGY* constants. Unfortunately, not all of them are available on all platform/JVM/JRE combinations, and of those available it is not always clear which provides highest resolution. chooseTimeStrategy(java.io.PrintStream), called automatically by a static initializer, attempts to introspect which methods are available and which one of those provides the highest resolution.

Similarly, there are a few different ways to implement a "sleep" in Java. Among these are Thread.sleep() and a busy loop that waits an appropriate amount of time (subject to the caveat of actually being able to measure time at an appropriate resolution, see above). It would be nice if we could always just rely on Thread.sleep(), but unfortunately it seems to have a minium sleep time (i.e. resolution or granularity) on some platforms that is on the order of 10s of milliseconds (see getSleepGranularity()). In Java 1.5 and above the java.util.concurrentl.locks.LockSupport.parkNanos() API provides higher resolution sleep, and chooseSleepStrategy(java.io.PrintStream), also called automatically by a static initializer, will select this API if available. If not, measureSleepGranularity(java.io.PrintStream) is called to measure the miniumum Thread.sleep() duration, and calls to sleep(double) will then be broken down into a call to Thread.sleep() for an integral multiple of the sleep granularity, and the rest as a busy loop which Thread.yield()s every YIELD_INTERVAL. Thus sleep() should effectively have a resolution near 1ms.

Copyright (C) 2008, Marsette A. Vona, III

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

Author:

Marsette (Marty) A. Vona, III

Field Summary

Fields
Modifier and Type	Field and Description
`static int`	`NUM_TEST_SLEEPS` Number of test calls to `Thread.sleep()` in `measureSleepGranularity(java.io.PrintStream)`.
`static double`	`SAMPLE_PERIOD_MS` Number of milliseconds to sample timing per trial.
`protected static double`	`secPerTick` Conversion factor from API ticks to real-world seconds.
`protected static double`	`secPerTickSave` `save()` slot.
`static int`	`SLEEP_STRATEGY_DEFAULT` the default sleep strategy, use `Thread.sleep()`
`static java.lang.String[]`	`SLEEP_STRATEGY_NAME` Human-readable names for the `SLEEP_STRATEGY*` constants.
`static int`	`SLEEP_STRATEGY_PARK_NANOS` use `java.util.concurrent.locks.LockSupport.parkNanos()`
`protected static double`	`sleepGranularity` The granularity of `Thread.sleep` in seconds.
`protected static int`	`sleepStrategy` The current sleep strategy, set by `chooseSleepStrategy(java.io.PrintStream)`.
`protected static int`	`sleepStrategySave` `save()` slot.
`protected static long`	`startTicks` Initial API epoch.
`protected static long`	`startTicksSave` `save()` slot.
`static double`	`SWITCH_FACTOR` Switch to a different policy if it provides a resolution less than this factor times the best current resolution.
`protected static double`	`ticksPerSec` Conversion factor from real-world seconds to API ticks.
`protected static double`	`ticksPerSecSave` `save()` slot.
`static int`	`TIME_STRATEGY_DEFAULT` The default time strategy, use `System.currentTimeMillis()`.
`static java.lang.String[]`	`TIME_STRATEGY_NAME` Human-readable names for the `TIME_STRATEGY*` constants.
`static int`	`TIME_STRATEGY_NANO` Use `System.nanoTime()`.
`protected static double`	`timeResolution` The resolution of `getTime()` in seconds.
`protected static double`	`timeResolutionSave` `save()` slot.
`protected static int`	`timeStrategy` The current time strategy, set by `chooseTimeStrategy(java.io.PrintStream)`.
`protected static int`	`timeStrategySave` `save()` slot.
`static double`	`YIELD_INTERVAL` Max duration between `Thread.yield()`s in `sleep(double)`.

Constructor Summary

Constructors
Constructor and Description

CompatTime()

Constructors
Constructor and Description
`CompatTime()`

Method Summary

Methods
Modifier and Type	Method and Description
`static void`	`chooseSleepStrategy(java.io.PrintStream out)` Choose the sleep strategy.
`static void`	`chooseTimeStrategy(java.io.PrintStream out)` Choose the time strategy.
`static void`	`dump()` `dump(PrintStream)` to `System.out`.
`static void`	`dump(java.io.PrintStream out)` Dump the strategy info to the specified destination.
`static double`	`getSleepGranularity()` Get the granularity of `Thread.sleep()` in seconds.
`static double`	`getTime()` Get the current real-world time in seconds relative to an arbitrary epoch.
`static double`	`getTimeResolution()` Get the minimum granularity of `getTime()` in seconds.
`static int`	`getTimeStrategy()` Get the strategy used for `getTime()`.
`static void`	`init()` Does nothing, but calling this will ensure that the static intializers have run.
`static void`	`main(java.lang.String[] arg)` Test driver dumps dbg to System.out.
`static void`	`measureSleepGranularity(java.io.PrintStream out)` Measure the `Thread.sleep()` granularity under the current policy.
`protected static double`	`measureTimeResolution(java.io.PrintStream out)` Measure the time resolution under the current policy.
`protected static void`	`restore()` Restore the time policy and related state from the most recent `save()`.
`protected static void`	`save()` Save the current time policy and related state.
`static void`	`sleep(double seconds)` Sleep the calling thread for the specified number of seconds.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - TIME_STRATEGY_DEFAULT
```
public static final int TIME_STRATEGY_DEFAULT
```
    The default time strategy, use System.currentTimeMillis().
    
    See Also:
    Constant Field Values
  - TIME_STRATEGY_NANO
```
public static final int TIME_STRATEGY_NANO
```
    Use System.nanoTime().
    
    See Also:
    Constant Field Values
  - TIME_STRATEGY_NAME
```
public static final java.lang.String[] TIME_STRATEGY_NAME
```
    Human-readable names for the TIME_STRATEGY* constants.
  - SLEEP_STRATEGY_DEFAULT
```
public static final int SLEEP_STRATEGY_DEFAULT
```
    the default sleep strategy, use Thread.sleep()
    
    See Also:
    Constant Field Values
  - SLEEP_STRATEGY_PARK_NANOS
```
public static final int SLEEP_STRATEGY_PARK_NANOS
```
    use java.util.concurrent.locks.LockSupport.parkNanos()
    
    See Also:
    Constant Field Values
  - SLEEP_STRATEGY_NAME
```
public static final java.lang.String[] SLEEP_STRATEGY_NAME
```
    Human-readable names for the SLEEP_STRATEGY* constants.
  - SAMPLE_PERIOD_MS
```
public static final double SAMPLE_PERIOD_MS
```
    Number of milliseconds to sample timing per trial.
    
    See Also:
    Constant Field Values
  - NUM_TEST_SLEEPS
```
public static final int NUM_TEST_SLEEPS
```
    Number of test calls to Thread.sleep() in measureSleepGranularity(java.io.PrintStream).
    
    See Also:
    Constant Field Values
  - SWITCH_FACTOR
```
public static final double SWITCH_FACTOR
```
    Switch to a different policy if it provides a resolution less than this factor times the best current resolution.
    
    See Also:
    Constant Field Values
  - YIELD_INTERVAL
```
public static final double YIELD_INTERVAL
```
    Max duration between Thread.yield()s in sleep(double).
    
    See Also:
    Constant Field Values
  - timeStrategy
```
protected static int timeStrategy
```
    The current time strategy, set by chooseTimeStrategy(java.io.PrintStream).
  - timeStrategySave
```
protected static int timeStrategySave
```
    save() slot.
  - sleepStrategy
```
protected static int sleepStrategy
```
    The current sleep strategy, set by chooseSleepStrategy(java.io.PrintStream).
  - sleepStrategySave
```
protected static int sleepStrategySave
```
    save() slot.
  - startTicks
```
protected static long startTicks
```
    Initial API epoch.
  - startTicksSave
```
protected static long startTicksSave
```
    save() slot.
  - ticksPerSec
```
protected static double ticksPerSec
```
    Conversion factor from real-world seconds to API ticks.
  - ticksPerSecSave
```
protected static double ticksPerSecSave
```
    save() slot.
  - secPerTick
```
protected static double secPerTick
```
    Conversion factor from API ticks to real-world seconds.
  - secPerTickSave
```
protected static double secPerTickSave
```
    save() slot.
  - sleepGranularity
```
protected static double sleepGranularity
```
    The granularity of Thread.sleep in seconds.
    
    See the class header doc.
  - timeResolution
```
protected static double timeResolution
```
    The resolution of getTime() in seconds.
    
    See the class header doc.
  - timeResolutionSave
```
protected static double timeResolutionSave
```
    save() slot.
- Constructor Detail
  - CompatTime
```
public CompatTime()
```
- Method Detail
  - sleep
```
public static void sleep(double seconds)
                  throws java.lang.InterruptedException
```
    Sleep the calling thread for the specified number of seconds.
    
    See the class header doc for an explanation of what actually might be happening when you call this.
    
    Parameters:
    seconds - the number of seconds to sleep
    
    Throws:
    
    java.lang.InterruptedException
  - getTime
```
public static double getTime()
```
    Get the current real-world time in seconds relative to an arbitrary epoch.
    
    See the class header doc for an explanation of what actually might be happening when you call this.
    
    See getTimeResolution() and getTimeStrategy().
    
    Returns:
    the current real-world time in seconds relative to an arbitrary epoch
  - getTimeResolution
```
public static double getTimeResolution()
```
    Get the minimum granularity of getTime() in seconds.
    
    See the class header doc.
    
    Returns:
    the minimum granularity of getTime() in seconds
  - getTimeStrategy
```
public static int getTimeStrategy()
```
    Get the strategy used for getTime().
    
    See the class header doc.
    
    Returns:
    the strategy used for getTime, one of the TIME_STRATEGY* constants
  - getSleepGranularity
```
public static double getSleepGranularity()
```
    Get the granularity of Thread.sleep() in seconds.
    
    See the class header doc.
    
    Returns:
    the minimum granularity of Thread.sleep() in seconds
  - init
```
public static void init()
```
    Does nothing, but calling this will ensure that the static intializers have run.
  - chooseTimeStrategy
```
public static void chooseTimeStrategy(java.io.PrintStream out)
                               throws java.lang.InterruptedException
```
    Choose the time strategy.
    
    Called automatically by a static initializer.
    
    See the class header doc.
    
    Throws:
    
    java.lang.InterruptedException
  - chooseSleepStrategy
```
public static void chooseSleepStrategy(java.io.PrintStream out)
```
    Choose the sleep strategy.
    
    Called automatically by a static initializer.
    
    See the class header doc.
  - measureTimeResolution
```
protected static double measureTimeResolution(java.io.PrintStream out)
```
    Measure the time resolution under the current policy.
    
    Parameters:
    out - a stream to dump dbg to or null for none
    
    Returns:
    the time resolution in seconds under the current policy
  - measureSleepGranularity
```
public static void measureSleepGranularity(java.io.PrintStream out)
                                    throws java.lang.InterruptedException
```
    Measure the Thread.sleep() granularity under the current policy.
    
    Called automatically by a static constructor.
    
    Parameters:
    out - a stream to dump dbg to or null for none
    
    Throws:
    
    java.lang.InterruptedException
  - save
```
protected static void save()
```
    Save the current time policy and related state.
  - restore
```
protected static void restore()
```
    Restore the time policy and related state from the most recent save().
  - dump
```
public static void dump()
```
    dump(PrintStream) to System.out.
  - dump
```
public static void dump(java.io.PrintStream out)
```
    Dump the strategy info to the specified destination.
    
    Parameters:
    out - the dump destination
  - main
```
public static void main(java.lang.String[] arg)
                 throws java.lang.Exception
```
    Test driver dumps dbg to System.out.
    
    Throws:
    
    java.lang.Exception

Class CompatTime

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

TIME_STRATEGY_DEFAULT

TIME_STRATEGY_NANO

TIME_STRATEGY_NAME

SLEEP_STRATEGY_DEFAULT

SLEEP_STRATEGY_PARK_NANOS

SLEEP_STRATEGY_NAME

SAMPLE_PERIOD_MS

NUM_TEST_SLEEPS

SWITCH_FACTOR

YIELD_INTERVAL

timeStrategy

timeStrategySave

sleepStrategy

sleepStrategySave

startTicks

startTicksSave

ticksPerSec

ticksPerSecSave

secPerTick

secPerTickSave

sleepGranularity

timeResolution

timeResolutionSave

Constructor Detail

CompatTime

Method Detail

sleep

getTime

getTimeResolution

getTimeStrategy

getSleepGranularity

init

chooseTimeStrategy

chooseSleepStrategy

measureTimeResolution

measureSleepGranularity

save

restore

dump

dump

main