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

[Martin Buchholz]

There's also an existing paragraph in Condition that goes
"When waiting upon a Condition, a spurious ... "

On Fri, Aug 11, 2017 at 11:50 AM, Martin Buchholz <martinrb at google.com>
wrote:

> Can we align the wording with existing wording in either LockSupport or
> Condition?
>
> On Fri, Aug 11, 2017 at 11:25 AM, 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/ja
>> va/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
>>
>>
>