Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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)

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD