edu.emory.mathcs.backport.java.util.concurrent.helpers
public final class Utils extends 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 Utils 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
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. |
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:
Thread#interrupt interrupts
the current
thread, and interruption of thread suspension is supported; or
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:
Thread#interrupt interrupted
while waiting
and interruption of thread suspension is supported,
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 Utils. 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: InterruptedException if the current thread is interrupted (and interruption of thread suspension is supported).
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.