JDK-6321234 : (spec thread) Thread.sleep() references Object.notify()
  • Type: Bug
  • Component: core-libs
  • Sub-Component: java.lang
  • Affected Version: 5.0
  • Priority: P3
  • Status: Closed
  • Resolution: Fixed
  • OS: windows_xp
  • CPU: x86
  • Submitted: 2005-09-08
  • Updated: 2011-05-18
  • Resolved: 2011-05-18
The Version table provides details related to the release that this issue/RFE will be addressed.

Unresolved : Release in which this issue/RFE will be addressed.
Resolved: Release in which this issue/RFE has been resolved.
Fixed : Release in which this issue/RFE has been fixed. The release containing this fix may be available for download as an Early Access Release or a General Availability Release.

To download the current JDK release, click here.
JDK 7 Other
7 b16Fixed OpenJDK6Fixed
Related Reports
Relates :  
JDK-6317167 - (thread spec) Make Thread.sleep javadoc fully in line with JLS 17.9
Description
FULL PRODUCT VERSION :
java version "1.5.0_04"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.5.0_04-b05)
Java HotSpot(TM) Client VM (build 1.5.0_04-b05, mixed mode, sharing)

ADDITIONAL OS VERSION INFORMATION :
all operating systems

A DESCRIPTION OF THE PROBLEM :
When you read the JavaDoc for
java.lang.Thread.sleep(long) or
java.lang.Thread.sleep(long,int),
then you'll find an entry
"See Also: Object.notify()".

This makes the reader think that Object.notify()
could possibly awake a sleeping Thread,
like it awakes a waiting Thread -- waiting by Object.wait().

As far as I know, this is false.

So the "See also:" field should be empty or
it could mention java.lang.Object.wait(long)
respectively java.lang.Object.wait(long,int).


STEPS TO FOLLOW TO REPRODUCE THE PROBLEM :
Read the JavaDoc for java.lang.Thread.sleep().

EXPECTED VERSUS ACTUAL BEHAVIOR :
EXPECTED -
You'll find a documentation with a bug.
ACTUAL -
I found a documentation with a bug.

REPRODUCIBILITY :
This bug can be reproduced always.
Comments
EVALUATION removed @see tags from method descriptions.
25-06-2007
SUGGESTED FIX --- /home/psoper/public_html/webrev/6321234_070507130932/./src/share/classes/java/lang/Thread.java- Mon May 7 13:12:16 2007 +++ Thread.java Mon May 7 13:09:22 2007 @@ -120,11 +120,11 @@ * Every thread has a name for identification purposes. More than * one thread may have the same name. If a name is not specified when * a thread is created, a new name is generated for it. * * @author unascribed - * @version 1.177, 03/13/07 + * @version 1.178, 05/07/07 * @see Runnable * @see Runtime#exit(int) * @see #run() * @see #stop() * @since JDK1.0 @@ -275,11 +275,10 @@ * * @param millis the length of time to sleep in milliseconds. * @exception InterruptedException if any thread has interrupted * the current thread. The <i>interrupted status</i> of the * current thread is cleared when this exception is thrown. - * @see Object#notify() */ public static native void sleep(long millis) throws InterruptedException; /** * Causes the currently executing thread to sleep (cease execution) @@ -294,11 +293,10 @@ * negative or the value of nanos is not in the range * 0-999999. * @exception InterruptedException if any thread has interrupted * the current thread. The <i>interrupted status</i> of the * current thread is cleared when this exception is thrown. - * @see Object#notify() */ public static void sleep(long millis, int nanos) throws InterruptedException { if (millis < 0) { throw new IllegalArgumentException("timeout value is negative");
07-05-2007
EVALUATION Will be fixed in combination with 6317167, which will finish pulling the current JLS Thread.sleep spec into the javadoc. This explicitly indicates the lack of any synchronization semantics for sleep but having the see also point to the timed signature of wait will be a good improvement detail.
08-09-2005