A DESCRIPTION OF THE PROBLEM :
The usage of Thread.yield() vs Thread.sleep(0) or Thead.sleep(0,0) is unclear (usage of join(0) is clear).  What is clear is sleep method may throw an InterruptedException if the current thread is interrupted and yield does not. Is the interrupt bit checked when the timeout is zero?

EXPECTED VERSUS ACTUAL BEHAVIOR :
EXPECTED -
Thread.sleep()  should specify what happens when a zero timeout is given as an argument.  It is unclear if the call is ignored (no-op) or if it still provides a hint to the scheduler.  The method should specify if interruption is favored over normal execution.

It would be nice if Thread.yield() and Thread.sleep() specified how each of these methods work with other threads with respect to higher and lower priorities.  Even if the behavior is unspecified and left up to the JVM it should be noted in these methods.

Thread.yield() is missing the line: "The thread does not lose ownership of any monitors."

ACTUAL -
========================================================
yield
public static void yield()Causes the currently executing thread object to temporarily pause and allow other threads to execute.
========================================================
sleep
public static void sleep(long millis)
                  throws InterruptedExceptionCauses the currently executing thread to sleep (temporarily cease execution) for the specified number of milliseconds. The thread does not lose ownership of any monitors.

Parameters:
millis - the length of time to sleep in milliseconds.
Throws:
InterruptedException - if another thread has interrupted the current thread. The interrupted status of the current thread is cleared when this exception is thrown.
See Also:
Object.notify()
========================================================
sleep
public static void sleep(long millis,
                         int nanos)
                  throws InterruptedExceptionCauses the currently executing thread to sleep (cease execution) for the specified number of milliseconds plus the specified number of nanoseconds. The thread does not lose ownership of any monitors.

Parameters:
millis - the length of time to sleep in milliseconds.
nanos - 0-999999 additional nanoseconds to sleep.
Throws:
IllegalArgumentException - if the value of millis is negative or the value of nanos is not in the range 0-999999.
InterruptedException - if another thread has interrupted the current thread. The interrupted status of the current thread is cleared when this exception is thrown.
See Also:
Object.notify()


URL OF FAULTY DOCUMENTATION :
http://java.sun.com/j2se/1.5.0/docs/api/java/lang/Thread.html
###@###.### 2005-04-06 07:02:20 GMT