edu.emory.mathcs.backport.java.util.concurrent.helpers
Class Utils

java.lang.Object
  edu.emory.mathcs.backport.java.util.concurrent.helpers.Utils

public final class Utils

extends java.lang.Object

This class groups together the functionality of java.util.concurrent that cannot be fully and reliably implemented in backport, but for which some form of emulation is possible.

Currently, this class contains methods related to nanosecond-precision timing, particularly via the nanoTime() method. To measure time accurately, this method by default uses java.sun.Perf on JDK1.4.2 and it falls back to System.currentTimeMillis on earlier JDKs.

Version:

1.0

Author:

Dawid Kurzyniec

Method Summary

static long	awaitNanos(Condition cond, long nanosTimeout) Causes the current thread to wait until it is signalled or interrupted, or the specified waiting time elapses.
static java.lang.Object[]	collectionToArray(java.util.Collection c)
static java.lang.Object[]	collectionToArray(java.util.Collection c, java.lang.Object[] a)
static long	nanoTime() Returns the current value of the most precise available system timer, in nanoseconds.

Methods inherited from class java.lang.Object

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

Method Detail

nanoTime

public static long nanoTime()

Returns the current value of the most precise available system timer, in nanoseconds. This method can only be used to measure elapsed time and is not related to any other notion of system or wall-clock time. The value returned represents nanoseconds since some fixed but arbitrary time (perhaps in the future, so values may be negative). This method provides nanosecond precision, but not necessarily nanosecond accuracy. No guarantees are made about how frequently values change. Differences in successive calls that span greater than approximately 292 years (2^63 nanoseconds) will not accurately compute elapsed time due to numerical overflow.

Implementation note:By default, this method uses sun.misc.Perf on Java 1.4.2, and falls back to System.currentTimeMillis() emulation on earlier JDKs. Custom timer can be provided via the system property edu.emory.mathcs.backport.java.util.concurrent.NanoTimerProvider. The value of the property should name a class implementing NanoTimer interface.

Note: on JDK 1.4.2, sun.misc.Perf timer seems to have resolution of the order of 1 microsecond, measured on Linux.

Returns:

The current value of the system timer, in nanoseconds.

awaitNanos

public static long awaitNanos(Condition cond,
                              long nanosTimeout)
                       throws java.lang.InterruptedException

Causes the current thread to wait until it is signalled or interrupted, or the specified waiting time elapses. This method originally appears in the Condition interface, but it was moved to here since it can only be emulated, with very little accuracy guarantees: the efficient implementation requires accurate nanosecond timer and native support for nanosecond-precision wait queues, which are not usually present in JVMs prior to 1.5. Loss of precision may cause total waiting times to be systematically shorter than specified when re-waits occur.

The lock associated with this condition is atomically released and the current thread becomes disabled for thread scheduling purposes and lies dormant until one of five things happens:

• Some other thread invokes the Condition.signal() method for this Condition and the current thread happens to be chosen as the thread to be awakened; or
• Some other thread invokes the Condition.signalAll() method for this Condition; or
• Some other thread interrupts the current thread, and interruption of thread suspension is supported; or
• The specified waiting time elapses; or
• A "spurious wakeup" occurs.

In all cases, before this method can return the current thread must re-acquire the lock associated with this condition. When the thread returns it is guaranteed to hold this lock.

If the current thread:

• has its interrupted status set on entry to this method; or
• is interrupted while waiting and interruption of thread suspension is supported,

then InterruptedException is thrown and the current thread's interrupted status is cleared. It is not specified, in the first case, whether or not the test for interruption occurs before the lock is released.

The method returns an estimate of the number of nanoseconds remaining to wait given the supplied nanosTimeout value upon return, or a value less than or equal to zero if it timed out. Accuracy of this estimate is directly dependent on the accuracy of nanoTime(). This value can be used to determine whether and how long to re-wait in cases where the wait returns but an awaited condition still does not hold. Typical uses of this method take the following form:

 synchronized boolean aMethod(long timeout, TimeUnit unit) {
   long nanosTimeout = unit.toNanos(timeout);
   while (!conditionBeingWaitedFor) {
     if (nanosTimeout > 0)
         nanosTimeout = theCondition.awaitNanos(nanosTimeout);
      else
        return false;
   }
   // ...
 }
 

Implementation Considerations

The current thread is assumed to hold the lock associated with this Condition when this method is called. It is up to the implementation to determine if this is the case and if not, how to respond. Typically, an exception will be thrown (such as IllegalMonitorStateException) and the implementation must document that fact.

A condition implementation can favor responding to an interrupt over normal method return in response to a signal, or over indicating the elapse of the specified waiting time. In either case the implementation must ensure that the signal is redirected to another waiting thread, if there is one.

Parameters:

cond - the condition to wait for

nanosTimeout - the maximum time to wait, in nanoseconds

Returns:

A value less than or equal to zero if the wait has timed out; otherwise an estimate, that is strictly less than the nanosTimeout argument, of the time still remaining when this method returned.

Throws:

java.lang.InterruptedException - if the current thread is interrupted (and interruption of thread suspension is supported).

collectionToArray

public static java.lang.Object[] collectionToArray(java.util.Collection c)

collectionToArray

public static java.lang.Object[] collectionToArray(java.util.Collection c,
                                                   java.lang.Object[] a)