| 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
org.apache.beehive.netui.util.concurrent.locks.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
org.apache.beehive.netui.util.concurrent.locks.Condition.signalAll method for this
Condition; or
- Some other thread
Thread.interrupt 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
Thread.interrupt 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
Utils.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
Parameters:
nanosTimeout - the maximum time to wait, in nanoseconds A value less than or equal to zero if the wait hastimed out; otherwise an estimate, thatis strictly less than the nanosTimeout argument,of the time still remaining when this method returned.
throws:
InterruptedException - if the current thread is interrupted (andinterruption of thread suspension is supported). |
