JDK-6416721 : (spec thread) Fix Thread.yield() javadoc
  • Type: Bug
  • Component: core-libs
  • Sub-Component: java.lang
  • Affected Version: 6
  • Priority: P3
  • Status: Closed
  • Resolution: Fixed
  • OS: generic
  • CPU: generic
  • Submitted: 2006-04-21
  • 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 b19Fixed OpenJDK6Fixed
Related Reports
Relates :  
JDK-4189292 - (thread spec) ThreadGroup and Thread need better and tighter specs
Relates :  
JDK-6584700 - JLSv3 section 17.9 "Sleep and Yield" needs statement about observable effects removed
Relates :  
JDK-6598810 - (thread spec) Thread.yield() not clear with respect to monitor ownership
Relates :  
JDK-6251168 - Addition documentation for Thread.yield() and Thread.sleep(0)
Description
The current spec for Thread.yield

"Causes the currently executing thread object to temporarily pause and allow other threads to execute."

is inadequate because
- there is no guarantee that the thread will or will not pause.
- if there are idle processors it is unlikely to pause.
- it should be clearer that this is a hint to the implementation, almost a "no-op".
- it should be made clear that ordinary application developers should not use this
  method.  It is only appropriate in unusual circumstances.  That is, it should be
  denigrated.
Comments
EVALUATION It is also instructive here to consult the history books :) The first edition of the Java Language Specification - the edition that contained the original specification for all the core classes - states for yield: "This method causes the current thread to yield, allowing the thread scheduler to choose another runnable thread for execution." This clearly states the intent of yield(), and that it was a scheduler dependent operation. And the fact the scheduler could "choose" introduced flexibility in the implementation as to exactly what had to happen. Unfortunately back in the late 90's when the decision was made that "the JavaDoc is the specification", they forgot to actually sync the JavaDoc with the JLS and we shortly thereafter got some very different API specs. [Edited to correct dates.]
24-05-2009
EVALUATION Updated the spec as follows: public static void yield() A hint to the scheduler that the current thread is willing to yield its current use of a processor. The scheduler is free to ignore this hint. Yield is a heuristic attempt to improve relative progression between threads that would otherwise over-utilise a CPU. Its use should be combined with detailed profiling and benchmarking to ensure that it actually has the desired effect. It is rarely appropriate to use this method. It may be useful for debugging or testing purposes, where it may help to reproduce bugs due to race conditions. It may also be useful when designing concurrency control constructs such as the ones in the java.util.concurrent.locks package.
31-07-2007
WORK AROUND A Java concurency and virtual machine expert suggests the following text and the Dolphin javadoc will likely cover these points for Thread.yield: "A hint to the scheduler that the current thread is willing to yield its current use of a processor. The scheduler is free to ignore this hint if the following progression guarantee is not violated: - The progression guarantee states that if two threads of the same priority are CPU bound and they each use Thread.yield, then each thread is guaranteed to make progression. In many systems the scheduler will not need to actively do anything to ensure the progression guarantee. The use of Thread.yield is a heuristic attempt by the program to influence scheduling decisions in circumstances where yielding the current thread might allow the application as whole to make progress quicker - such as when the current thread performs a busy-wait that relies on some other thread making progress; or when a pseudo-random delay might be needed in a back-off algorithm."
02-05-2006
EVALUATION This CR stemmed from discussion of some doc review related to concurrency. The sentiment of this bug is shared by many: as things stand, after so many many years with proper OS and VM threading support for preemptive scheduling, Thread.yield is just about the last method Java developers should expect to employ outside of special cases. The current javadoc is both misleading and guilty of sins of omission. Although "denigrate" may not find a place in the formal Java lexicon, this method's docs really need to spell out when, exactly, usage may be required to ensure proper program progress on some platforms and when it is useful to experienced developers for optimization and as a temporary source of stress during testing.
24-04-2006