Causes the current thread to wait until it is signalled or interrupted, or the specified deadline elapses.

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 ICondition.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 ICondition.SignalAll method for this Condition; or
• Some other thread Java.Lang.Thread.Interrupt the current thread, and interruption of thread suspension is supported; or
• The specified deadline 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 Java.Lang.Thread.Interrupt while waiting and interruption of thread suspension is supported,

The return value indicates whether the deadline has elapsed, which can be used as follows:

boolean aMethod(Date deadline) {
   boolean stillWaiting = true;
   lock.lock();
   try {
     while (!conditionBeingWaitedFor()) {
       if (!stillWaiting)
         return false;
       stillWaiting = theCondition.awaitUntil(deadline);
     
     // ...
   } finally {
     lock.unlock();
   }
 }}

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 Java.Lang.IllegalMonitorStateException) and the implementation must document that fact.

An implementation can favor responding to an interrupt over normal method return in response to a signal, or over indicating the passing of the specified deadline. In either case the implementation must ensure that the signal is redirected to another waiting thread, if there is one.

[Android Documentation]