ICondition.AwaitNanos(Int64) Method

Reference

Definition

Namespace:: Java.Util.Concurrent.Locks

Assembly:: Mono.Android.dll

Important

Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.

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

[Android.Runtime.Register("awaitNanos", "(J)J", "GetAwaitNanos_JHandler:Java.Util.Concurrent.Locks.IConditionInvoker, Mono.Android, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null")]
public long AwaitNanos (long nanosTimeout);

[<Android.Runtime.Register("awaitNanos", "(J)J", "GetAwaitNanos_JHandler:Java.Util.Concurrent.Locks.IConditionInvoker, Mono.Android, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null")>]
abstract member AwaitNanos : int64 -> int64

Parameters

nanosTimeout: Int64

the maximum time to wait, in nanoseconds

Returns

Int64

an estimate of the nanosTimeout value minus the time spent waiting upon return from this method. A positive value may be used as the argument to a subsequent call to this method to finish waiting out the desired time. A value less than or equal to zero indicates that no time remains.

Attributes: RegisterAttribute

Exceptions

InterruptedException

if the current thread is interrupted (and interruption of thread suspension is supported)

Remarks

Causes the current thread to wait until it is signalled or interrupted, or the specified waiting time 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: <ul> <li>Some other thread invokes the #signal method for this Condition and the current thread happens to be chosen as the thread to be awakened; or <li>Some other thread invokes the #signalAll method for this Condition; or <li>Some other thread Thread#interrupt interrupts the current thread, and interruption of thread suspension is supported; or <li>The specified waiting time elapses; or <li>A "spurious wakeup" occurs. </ul>

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: <ul> <li>has its interrupted status set on entry to this method; or <li>is Thread#interrupt interrupted while waiting and interruption of thread suspension is supported, </ul> 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. 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:

{@code
            boolean aMethod(long timeout, TimeUnit unit)
                throws InterruptedException {
              long nanosRemaining = unit.toNanos(timeout);
              lock.lock();
              try {
                while (!conditionBeingWaitedFor()) {
                  if (nanosRemaining <= 0L)
                    return false;
                  nanosRemaining = theCondition.awaitNanos(nanosRemaining);
                }
                // ...
                return true;
              } finally {
                lock.unlock();
              }
            }}

Design note: This method requires a nanosecond argument so as to avoid truncation errors in reporting remaining times. Such precision loss would make it difficult for programmers to ensure that total waiting times are not systematically shorter than specified when re-waits occur.

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.

An 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.

Java documentation for java.util.concurrent.locks.Condition.awaitNanos(long).

Portions of this page are modifications based on work created and shared by the Android Open Source Project and used according to terms described in the Creative Commons 2.5 Attribution License.

Applies to