Add documentation around zero-length timeouts

Add documentation to cover the fact that wait()
and join() treat zero-length timeouts as "wait indefinitely".
Improved documentation for when a thread is already
interrupted when the various sleep/join/wait calls are made,
and what happens to the interrupted state.

Bug: 12931322
Change-Id: I4e8353cb556ff335df187fd5efa1f42c9b196cd6

2 files changed, 56 insertions, 48 deletions

diff --git a/libart/src/main/java/java/lang/Object.java b/libart/src/main/java/java/lang/Object.java
index 9c59870..81e3872 100644
--- a/libart/src/main/java/java/lang/Object.java
+++ b/libart/src/main/java/java/lang/Object.java
@@ -278,10 +278,9 @@ public class Object {
      * that called {@code notify()} has to release the object's monitor first.
      * Also, the chosen thread still has to compete against other threads that
      * try to synchronize on the same object.
-     * <p>
-     * This method can only be invoked by a thread which owns this object's
+     *
+     * <p>This method can only be invoked by a thread which owns this object's
      * monitor. A thread becomes owner of an object's monitor
-     * </p>
      * <ul>
      * <li>by executing a synchronized method of that object;</li>
      * <li>by executing the body of a {@code synchronized} statement that
@@ -304,10 +303,9 @@ public class Object {
      * will not run immediately. The thread that called {@code notify()} has to
      * release the object's monitor first. Also, the threads still have to
      * compete against other threads that try to synchronize on the same object.
-     * <p>
-     * This method can only be invoked by a thread which owns this object's
+     *
+     * <p>This method can only be invoked by a thread which owns this object's
      * monitor. A thread becomes owner of an object's monitor
-     * </p>
      * <ul>
      * <li>by executing a synchronized method of that object;</li>
      * <li>by executing the body of a {@code synchronized} statement that
@@ -349,23 +347,22 @@ public class Object {
      * notify()} or {@code notifyAll()} method of this object. This method can
      * only be invoked by a thread which owns this object's monitor; see
      * {@link #notify()} on how a thread can become the owner of a monitor.
-     * <p>
-     * A waiting thread can be sent {@code interrupt()} to cause it to
+     *
+     * <p>A waiting thread can be sent {@code interrupt()} to cause it to
      * prematurely stop waiting, so {@code wait} should be called in a loop to
      * check that the condition that has been waited for has been met before
      * continuing.
-     * </p>
-     * <p>
-     * While the thread waits, it gives up ownership of this object's monitor.
-     * When it is notified (or interrupted), it re-acquires the monitor before
-     * it starts running.
-     * </p>
+     *
+     * <p>While the thread waits, it gives up ownership of this object's
+     * monitor. When it is notified (or interrupted), it re-acquires the monitor
+     * before it starts running.
      *
      * @throws IllegalMonitorStateException
      *             if the thread calling this method is not the owner of this
      *             object's monitor.
-     * @throws InterruptedException
-     *             if another thread interrupts this thread while it is waiting.
+     * @throws InterruptedException if the current thread has been interrupted.
+     *             The interrupted status of the current thread will be cleared before the exception
+     *             is thrown.
      * @see #notify
      * @see #notifyAll
      * @see #wait(long)
@@ -380,17 +377,18 @@ public class Object {
      * specified timeout expires. This method can only be invoked by a thread
      * which owns this object's monitor; see {@link #notify()} on how a thread
      * can become the owner of a monitor.
-     * <p>
-     * A waiting thread can be sent {@code interrupt()} to cause it to
+     *
+     * <p>A waiting thread can be sent {@code interrupt()} to cause it to
      * prematurely stop waiting, so {@code wait} should be called in a loop to
      * check that the condition that has been waited for has been met before
      * continuing.
-     * </p>
-     * <p>
-     * While the thread waits, it gives up ownership of this object's monitor.
-     * When it is notified (or interrupted), it re-acquires the monitor before
-     * it starts running.
-     * </p>
+     *
+     * <p>While the thread waits, it gives up ownership of this object's
+     * monitor. When it is notified (or interrupted), it re-acquires the monitor
+     * before it starts running.
+     *
+     * <p>A timeout of zero means the calling thread should wait forever unless interrupted or
+     * notified.
      *
      * @param millis
      *            the maximum time to wait in milliseconds.
@@ -399,8 +397,9 @@ public class Object {
      * @throws IllegalMonitorStateException
      *             if the thread calling this method is not the owner of this
      *             object's monitor.
-     * @throws InterruptedException
-     *             if another thread interrupts this thread while it is waiting.
+     * @throws InterruptedException if the current thread has been interrupted.
+     *             The interrupted status of the current thread will be cleared before the exception
+     *             is thrown.
      * @see #notify
      * @see #notifyAll
      * @see #wait()
@@ -417,17 +416,18 @@ public class Object {
      * specified timeout expires. This method can only be invoked by a thread
      * that owns this object's monitor; see {@link #notify()} on how a thread
      * can become the owner of a monitor.
-     * <p>
-     * A waiting thread can be sent {@code interrupt()} to cause it to
+     *
+     * <p>A waiting thread can be sent {@code interrupt()} to cause it to
      * prematurely stop waiting, so {@code wait} should be called in a loop to
      * check that the condition that has been waited for has been met before
      * continuing.
-     * </p>
-     * <p>
-     * While the thread waits, it gives up ownership of this object's monitor.
-     * When it is notified (or interrupted), it re-acquires the monitor before
-     * it starts running.
-     * </p>
+     *
+     * <p>While the thread waits, it gives up ownership of this object's
+     * monitor. When it is notified (or interrupted), it re-acquires the monitor
+     * before it starts running.
+     *
+     * <p>A timeout of zero means the calling thread should wait forever unless interrupted or
+     * notified.
      *
      * @param millis
      *            the maximum time to wait in milliseconds.
@@ -440,8 +440,9 @@ public class Object {
      * @throws IllegalMonitorStateException
      *             if the thread calling this method is not the owner of this
      *             object's monitor.
-     * @throws InterruptedException
-     *             if another thread interrupts this thread while it is waiting.
+     * @throws InterruptedException if the current thread has been interrupted.
+     *             The interrupted status of the current thread will be cleared before the exception
+     *             is thrown.
      * @see #notify
      * @see #notifyAll
      * @see #wait()
diff --git a/libart/src/main/java/java/lang/Thread.java b/libart/src/main/java/java/lang/Thread.java
index 2cc2857..9bcae86 100644
--- a/libart/src/main/java/java/lang/Thread.java
+++ b/libart/src/main/java/java/lang/Thread.java
@@ -712,8 +712,9 @@ public class Thread implements Runnable {
      * Blocks the current Thread (<code>Thread.currentThread()</code>) until
      * the receiver finishes its execution and dies.
      *
-     * @throws InterruptedException if <code>interrupt()</code> was called for
-     *         the receiver while it was in the <code>join()</code> call
+     * @throws InterruptedException if the current thread has been interrupted.
+     *         The interrupted status of the current thread will be cleared before the exception is
+     *         thrown.
      * @see Object#notifyAll
      * @see java.lang.ThreadDeath
      */
@@ -730,9 +731,12 @@ public class Thread implements Runnable {
      * the receiver finishes its execution and dies or the specified timeout
      * expires, whatever happens first.
      *
+     * <p>A timeout of zero means the calling thread should wait forever unless interrupted.
+     *
      * @param millis The maximum time to wait (in milliseconds).
-     * @throws InterruptedException if <code>interrupt()</code> was called for
-     *         the receiver while it was in the <code>join()</code> call
+     * @throws InterruptedException if the current thread has been interrupted.
+     *         The interrupted status of the current thread will be cleared before the exception is
+     *         thrown.
      * @see Object#notifyAll
      * @see java.lang.ThreadDeath
      */
@@ -745,10 +749,13 @@ public class Thread implements Runnable {
      * the receiver finishes its execution and dies or the specified timeout
      * expires, whatever happens first.
      *
+     * <p>A timeout of zero means the calling thread should wait forever unless interrupted.
+     *
      * @param millis The maximum time to wait (in milliseconds).
      * @param nanos Extra nanosecond precision
-     * @throws InterruptedException if <code>interrupt()</code> was called for
-     *         the receiver while it was in the <code>join()</code> call
+     * @throws InterruptedException if the current thread has been interrupted.
+     *         The interrupted status of the current thread will be cleared before the exception is
+     *         thrown.
      * @see Object#notifyAll
      * @see java.lang.ThreadDeath
      */
@@ -969,9 +976,9 @@ public class Thread implements Runnable {
      *
      * @param time
      *            The time to sleep in milliseconds.
-     * @throws InterruptedException
-     *             if <code>interrupt()</code> was called for this Thread while
-     *             it was sleeping
+     * @throws InterruptedException if the current thread has been interrupted.
+     *            The interrupted status of the current thread will be cleared before the exception
+     *            is thrown.
      * @see Thread#interrupt()
      */
     public static void sleep(long time) throws InterruptedException {
@@ -987,9 +994,9 @@ public class Thread implements Runnable {
      *            The time to sleep in milliseconds.
      * @param nanos
      *            Extra nanosecond precision
-     * @throws InterruptedException
-     *             if <code>interrupt()</code> was called for this Thread while
-     *             it was sleeping
+     * @throws InterruptedException if the current thread has been interrupted.
+     *            The interrupted status of the current thread will be cleared before the exception
+     *            is thrown.
      * @see Thread#interrupt()
      */
     public static void sleep(long millis, int nanos) throws InterruptedException {