Class 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.

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


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 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.

The current value of the system timer, in nanoseconds.


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:

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:

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);
        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.

cond - the condition to wait for
nanosTimeout - the maximum time to wait, in nanoseconds
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.
java.lang.InterruptedException - if the current thread is interrupted (and interruption of thread suspension is supported).


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


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