- * The current thread must own this object's monitor. - *
- * This method causes the current thread (call it T) to - * place itself in the wait set for this object and then to relinquish - * any and all synchronization claims on this object. Thread T - * becomes disabled for thread scheduling purposes and lies dormant - * until one of four things happens: + * Causes the current thread to wait until it is awakened, typically + * by being notified or interrupted. + *
+ * 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 interrupted status 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 notified or interrupted, or until a + * certain amount of real time has elapsed. + *
+ * In all respects, this method behaves as if {@code wait(timeout, 0)} + * had been called. See the specification of the {@link #wait(long, int)} method + * for details. + * + * @param timeout the maximum time to wait, in milliseconds + * @throws IllegalArgumentException if the value of {@code timeout} 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 interrupted status 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 timeout) throws InterruptedException; + + /** + * Causes the current thread to wait until it is awakened, typically + * by being notified or interrupted, or until a + * certain amount of real time has elapsed. + *
+ * 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. + *
+ * This method causes the current thread (referred to here as T) 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. + *
+ * Thread T then becomes disabled for thread scheduling purposes + * and lies dormant until one of the following five things occurs: *
* The thread T is then removed from the wait set for this - * object and re-enabled for thread scheduling. It then competes in the + * 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 gained control of the object, all its + * 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 T then returns from the @@ -343,119 +396,54 @@ * thread {@code T} is exactly as it was when the {@code wait} method * was invoked. *
- * A thread can also wake up without being notified, interrupted, or - * timing out, a so-called spurious wakeup. 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. In other words, - * waits should always occur in loops, like this one: - *
- * synchronized (obj) {
- * while (<condition does not hold>)
- * obj.wait(timeout);
- * ... // Perform action appropriate to condition
- * }
- *
- *
+ * A thread can wake up without being notified, interrupted, or timing out, a
+ * so-called spurious wakeup. 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.
+ * * (For more information on this topic, see section 14.2, - * Condition Queues, in Brian Goetz and others' "Java Concurrency - * in Practice" (Addison-Wesley, 2006) or Item 69 in Joshua - * Bloch's "Effective Java (Second Edition)" (Addison-Wesley, + * "Condition Queues," in Brian Goetz and others' Java Concurrency + * in Practice (Addison-Wesley, 2006) or Item 69 in Joshua + * Bloch's Effective Java, Second Edition (Addison-Wesley, * 2008). - * - *
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. This exception is not - * thrown until the lock status of this object has been restored as - * described above. - * *
- * Note that the {@code wait} method, as it places the current thread - * into the wait set for this object, unlocks only this object; any - * other objects on which the current thread may be synchronized remain - * locked while the thread waits. - *
- * This method should only be called by a thread that is the owner - * of this object's monitor. See the {@code notify} method for a - * description of the ways in which a thread can become the owner of - * a monitor. + * 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 interrupted status 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. * - * @param timeout the maximum time to wait in milliseconds. - * @throws IllegalArgumentException if the value of timeout 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 for a notification. The interrupted - * status of the current thread is cleared when - * this exception is thrown. - * @see java.lang.Object#notify() - * @see java.lang.Object#notifyAll() - */ - public final native void wait(long timeout) throws InterruptedException; - - /** - * Causes the current thread to wait until another thread invokes the - * {@link java.lang.Object#notify()} method or the - * {@link java.lang.Object#notifyAll()} method for this object, or - * some other thread interrupts the current thread, or a certain - * amount of real time has elapsed. - *
- * This method is similar to the {@code wait} method of one - * argument, but it allows finer control over the amount of time to - * wait for a notification before giving up. The amount of real time, - * measured in nanoseconds, is given by: - *
- *- *- * 1000000*timeout+nanos
- * In all other respects, this method does the same thing as the - * method {@link #wait(long)} of one argument. In particular, - * {@code wait(0, 0)} means the same thing as {@code wait(0)}. - *
- * The current thread must own this object's monitor. The thread - * releases ownership of this monitor and waits until either of the - * following two conditions has occurred: - *
- * The thread then waits until it can re-obtain ownership of the - * monitor and resumes execution. - *
- * As in the one argument version, interrupts and spurious wakeups are - * possible, and this method should always be used in a loop: - *
+ * @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.
+ *
+ * {@code
* synchronized (obj) {
- * while (<condition does not hold>)
+ * while ( and ) {
+ * long timeout = ... ; // recompute timeout values
+ * int nanos = ... ;
* obj.wait(timeout, nanos);
- * ... // Perform action appropriate to condition
+ * }
+ * ... // Perform action appropriate to condition or timeout
* }
- *
- * This method should only be called by a thread that is the owner
- * of this object's monitor. See the {@code notify} method for a
- * description of the ways in which a thread can become the owner of
- * a monitor.
+ * }
*
- * @param timeout the maximum time to wait in milliseconds.
- * @param nanos additional time, in nanoseconds range
- * 0-999999.
- * @throws IllegalArgumentException if the value of timeout is
- * negative or the value of nanos is
- * not in the range 0-999999.
- * @throws IllegalMonitorStateException if the current thread is not
- * the owner of this object's monitor.
- * @throws InterruptedException if any thread interrupted the
- * current thread before or while the current thread
- * was waiting for a notification. The interrupted
- * status of the current thread is cleared when
- * this exception is thrown.
+ * @param timeout the maximum time to wait, in milliseconds
+ * @param nanos additional time, in nanoseconds, in the range range 0-999999 inclusive
+ * @throws IllegalArgumentException if the value of {@code timeout} 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 interrupted status 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 timeout, int nanos) throws InterruptedException {
if (timeout < 0) {
@@ -475,48 +463,6 @@
}
/**
- * Causes the current thread to wait until another thread invokes the
- * {@link java.lang.Object#notify()} method or the
- * {@link java.lang.Object#notifyAll()} method for this object.
- * In other words, this method behaves exactly as if it simply
- * performs the call {@code wait(0)}.
- * - * The current thread must own this object's monitor. The thread - * releases ownership of this monitor and waits until another thread - * notifies threads waiting on this object's monitor to wake up - * either through a call to the {@code notify} method or the - * {@code notifyAll} method. The thread then waits until it can - * re-obtain ownership of the monitor and resumes execution. - *
- * As in the one argument version, interrupts and spurious wakeups are - * possible, and this method should always be used in a loop: - *
- * synchronized (obj) {
- * while (<condition does not hold>)
- * obj.wait();
- * ... // Perform action appropriate to condition
- * }
- *
- * This method should only be called by a thread that is the owner
- * of this object's monitor. See the {@code notify} method for a
- * description of the ways in which a thread can become the owner of
- * a monitor.
- *
- * @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 for a notification. The interrupted
- * status of the current thread is cleared when
- * this exception is thrown.
- * @see java.lang.Object#notify()
- * @see java.lang.Object#notifyAll()
- */
- public final void wait() throws InterruptedException {
- wait(0);
- }
-
- /**
* Called by the garbage collector on an object when garbage collection
* determines that there are no more references to the object.
* A subclass overrides the {@code finalize} method to dispose of