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

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.

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 Object[]
collectionToArray(Collection c)
static Object[]
collectionToArray(Collection c, Object[] a)
static long
nanoTime()
Returns the current value of the most precise available system timer, in nanoseconds.

Method Details

awaitNanos

public static long awaitNanos(Condition cond,
                              long nanosTimeout)
            throws 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.

collectionToArray

public static Object[] collectionToArray(Collection c)

collectionToArray

public static Object[] collectionToArray(Collection c,
                                         Object[] a)

nanoTime

public static long nanoTime()
Returns:
The current value of the system timer, in nanoseconds.