RFR(xs): 6344935: Clarify Object.wait javadoc with respect to spurious wakeups

[Lance Andersen]

Looks fine Stuart


> On Aug 11, 2017, at 2:25 PM, Stuart Marks <stuart.marks at oracle.com> wrote:
> 
> This is an old spec bug. The Object.wait spec lists several different reasons a thread could be awakened, but it omits spurious wakeup -- even though spurious wakeup is described later on. The fix is simply to add spurious wakeup to the list.
> 
> There is some discussion in the original bug report:
> 
>    https://bugs.openjdk.java.net/browse/JDK-6344935
> 
> Patch appended below.
> 
> Thanks,
> 
> s'marks
> 
> 
> 
> # HG changeset patch
> # User smarks
> # Date 1502475871 25200
> #      Fri Aug 11 11:24:31 2017 -0700
> # Node ID ebd66cd27b298d5bbbdfd348164505ef1195f90e
> # Parent  27b08ab97a607df3a4abff83d8d1a2a1882e5bf1
> 6344935: Clarify Object.wait javadoc with respect to spurious wakeups
> Reviewed-by: XXX
> 
> diff -r 27b08ab97a60 -r ebd66cd27b29 src/java.base/share/classes/java/lang/Object.java
> --- a/src/java.base/share/classes/java/lang/Object.java	Thu Aug 03 09:04:47 2017 -0700
> +++ b/src/java.base/share/classes/java/lang/Object.java	Fri Aug 11 11:24:31 2017 -0700
> @@ -318,7 +318,7 @@
>      * place itself in the wait set for this object and then to relinquish
>      * any and all synchronization claims on this object. Thread <var>T</var>
>      * becomes disabled for thread scheduling purposes and lies dormant
> -     * until one of four things happens:
> +     * until one of five things happens:
>      * <ul>
>      * <li>Some other thread invokes the {@code notify} method for this
>      * object and thread <var>T</var> happens to be arbitrarily chosen as
> @@ -330,7 +330,9 @@
>      * <li>The specified amount of real time has elapsed, more or less.  If
>      * {@code timeout} is zero, however, then real time is not taken into
>      * consideration and the thread simply waits until notified.
> +     * <li>Thread <var>T</var> is awakened spuriously. (See below.)
>      * </ul>
> +     * <p>
>      * The thread <var>T</var> is then removed from the wait set for this
>      * object and re-enabled for thread scheduling. It then competes in the
>      * usual manner with other threads for the right to synchronize on the
> 

 <http://oracle.com/us/design/oracle-email-sig-198324.gif>
 <http://oracle.com/us/design/oracle-email-sig-198324.gif> <http://oracle.com/us/design/oracle-email-sig-198324.gif>
 <http://oracle.com/us/design/oracle-email-sig-198324.gif>Lance Andersen| Principal Member of Technical Staff | +1.781.442.2037
Oracle Java Engineering 
1 Network Drive 
Burlington, MA 01803
Lance.Andersen at oracle.com <mailto:Lance.Andersen at oracle.com>