Home / cs-notes / Language / Java / Basic / Object / wait
/**
* Causes the current thread to wait until it is awakened, typically
* by being <em>notified</em> or <em>interrupted</em>.
* <p>
* In all respects, this method behaves as if {@code wait(0L, 0)}
* had been called. See the specification of the {@link #wait(long, int)} method
* for details.
*
* @throws IllegalMonitorStateException if the current thread is not
* the owner of the object's monitor
* @throws InterruptedException if any thread interrupted the current thread before or
* while the current thread was waiting. The <em>interrupted status</em> of the
* current thread is cleared when this exception is thrown.
* @see #notify()
* @see #notifyAll()
* @see #wait(long)
* @see #wait(long, int)
*/
public final void wait() throws InterruptedException {
wait(0L);
}
/**
* Causes the current thread to wait until it is awakened, typically
* by being <em>notified</em> or <em>interrupted</em>, or until a
* certain amount of real time has elapsed.
* <p>
* In all respects, this method behaves as if {@code wait(timeoutMillis, 0)}
* had been called. See the specification of the {@link #wait(long, int)} method
* for details.
*
* @param timeoutMillis the maximum time to wait, in milliseconds
* @throws IllegalArgumentException if {@code timeoutMillis} is negative
* @throws IllegalMonitorStateException if the current thread is not
* the owner of the object's monitor
* @throws InterruptedException if any thread interrupted the current thread before or
* while the current thread was waiting. The <em>interrupted status</em> of the
* current thread is cleared when this exception is thrown.
* @see #notify()
* @see #notifyAll()
* @see #wait()
* @see #wait(long, int)
*/
public final native void wait(long timeoutMillis) throws InterruptedException;
/**
* Causes the current thread to wait until it is awakened, typically
* by being <em>notified</em> or <em>interrupted</em>, or until a
* certain amount of real time has elapsed.
* <p>
* The current thread must own this object's monitor lock. See the
* {@link #notify notify} method for a description of the ways in which
* a thread can become the owner of a monitor lock.
* <p>
* This method causes the current thread (referred to here as <var>T</var>) to
* place itself in the wait set for this object and then to relinquish any
* and all synchronization claims on this object. Note that only the locks
* on this object are relinquished; any other objects on which the current
* thread may be synchronized remain locked while the thread waits.
* <p>
* Thread <var>T</var> then becomes disabled for thread scheduling purposes
* and lies dormant until one of the following occurs:
* <ul>
* <li>Some other thread invokes the {@code notify} method for this
* object and thread <var>T</var> happens to be arbitrarily chosen as
* the thread to be awakened.
* <li>Some other thread invokes the {@code notifyAll} method for this
* object.
* <li>Some other thread {@linkplain Thread#interrupt() interrupts}
* thread <var>T</var>.
* <li>The specified amount of real time has elapsed, more or less.
* The amount of real time, in nanoseconds, is given by the expression
* {@code 1000000 * timeoutMillis + nanos}. If {@code timeoutMillis} and {@code nanos}
* are both zero, then real time is not taken into consideration and the
* thread waits until awakened by one of the other causes.
* <li>Thread <var>T</var> is awakened spuriously. (See below.)
* </ul>
* <p>
* The thread <var>T</var> is then removed from the wait set for this
* object and re-enabled for thread scheduling. It competes in the
* usual manner with other threads for the right to synchronize on the
* object; once it has regained control of the object, all its
* synchronization claims on the object are restored to the status quo
* ante - that is, to the situation as of the time that the {@code wait}
* method was invoked. Thread <var>T</var> then returns from the
* invocation of the {@code wait} method. Thus, on return from the
* {@code wait} method, the synchronization state of the object and of
* thread {@code T} is exactly as it was when the {@code wait} method
* was invoked.
* <p>
* A thread can wake up without being notified, interrupted, or timing out, a
* so-called <em>spurious wakeup</em>. While this will rarely occur in practice,
* applications must guard against it by testing for the condition that should
* have caused the thread to be awakened, and continuing to wait if the condition
* is not satisfied. See the example below.
* <p>
* For more information on this topic, see section 14.2,
* "Condition Queues," in Brian Goetz and others' <em>Java Concurrency
* in Practice</em> (Addison-Wesley, 2006) or Item 69 in Joshua
* Bloch's <em>Effective Java, Second Edition</em> (Addison-Wesley,
* 2008).
* <p>
* If the current thread is {@linkplain java.lang.Thread#interrupt() interrupted}
* by any thread before or while it is waiting, then an {@code InterruptedException}
* is thrown. The <em>interrupted status</em> of the current thread is cleared when
* this exception is thrown. This exception is not thrown until the lock status of
* this object has been restored as described above.
*
* @apiNote
* The recommended approach to waiting is to check the condition being awaited in
* a {@code while} loop around the call to {@code wait}, as shown in the example
* below. Among other things, this approach avoids problems that can be caused
* by spurious wakeups.
*
* <pre>{@code
* synchronized (obj) {
* while (<condition does not hold> and <timeout not exceeded>) {
* long timeoutMillis = ... ; // recompute timeout values
* int nanos = ... ;
* obj.wait(timeoutMillis, nanos);
* }
* ... // Perform action appropriate to condition or timeout
* }
* }</pre>
*
* @param timeoutMillis the maximum time to wait, in milliseconds
* @param nanos additional time, in nanoseconds, in the range range 0-999999 inclusive
* @throws IllegalArgumentException if {@code timeoutMillis} is negative,
* or if the value of {@code nanos} is out of range
* @throws IllegalMonitorStateException if the current thread is not
* the owner of the object's monitor
* @throws InterruptedException if any thread interrupted the current thread before or
* while the current thread was waiting. The <em>interrupted status</em> of the
* current thread is cleared when this exception is thrown.
* @see #notify()
* @see #notifyAll()
* @see #wait()
* @see #wait(long)
*/
public final void wait(long timeoutMillis, int nanos) throws InterruptedException {
if (timeoutMillis < 0) {
throw new IllegalArgumentException("timeoutMillis value is negative");
}
if (nanos < 0 || nanos > 999999) {
throw new IllegalArgumentException(
"nanosecond timeout value out of range");
}
if (nanos > 0) {
timeoutMillis++;
}
wait(timeoutMillis);
}