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

[Hans Boehm]

Any chance the example code in the documentation that is quoted below could
also be adjusted to e.g.

     synchronized (obj) {
         while (<condition does not hold>) {
             <compute remaining timeout>;
             obj.wait(<timeout>);
         }
         ... // Perform action appropriate to condition
     }

and similarly for the nanos case?

It has long bothered me that the documentation for java.lang.Object
recommends buggy code. If there
are frequent notifyAll()s signalling the establishment of other conditions,
the current example code is badly
broken in a way that's not obvious to every user.


On Fri, Aug 11, 2017 at 4:43 PM, David Holmes <david.holmes at oracle.com>
wrote:

> On 12/08/2017 5:14 AM, Stuart Marks wrote:
>
>> In general, I'm in favor of ensuring that wording in various bits of the
>> specification is well aligned. I don't see specifically what would need to
>> be improved in this case, though.
>>
>
> If you start trying to align things too much you end up rewriting a heap
> of stuff. I would not be concerned with the differences between
> LockSupport/Condition and Object.wait wording.
>
> If anything should be aligned it is perhaps the awkwardly formed docs for
> wait(long, int) which only lists 2 reasons for waking, then adds "and of
> course interrupt and spurious wakeup can also happen" [sic] That is in a
> way consistent with wait(long) only listing 4 reasons and then adding the
> note about spurious wakeups.
>
> Cheers,
> David
>
>
> Can we align the wording with existing wording in either LockSupport or
>>> Condition?
>>>
>>
>> The various LockSupport.park methods have a similar bullet list, and
>> among them is the following:
>>
>>      * The call spuriously (that is, for no reason) returns.
>>
>> But note this says that the park call returns, whereas the wait call does
>> NOT necessarily return because of spurious wakeup; it's merely removed from
>> the wait set. Thus the proposed text says
>>
>>      * Thread <var>T</var> is awakened spuriously. (See below.)
>>
>> and subsequent paragraphs talk about removal from wait set, competing to
>> re-acquire the lock, and spurious wakeup.
>>
>>
>> There's also an existing paragraph in Condition that goes "When waiting
>>> upon
>>> a Condition, a spurious ... "
>>>
>>
>> This paragraph from the Condition specification says,
>>
>> When waiting upon a Condition, a "spurious wakeup" is permitted to occur,
>>> in
>>> general, as a concession to the underlying platform semantics. This has
>>> little practical impact on most application programs as a Condition
>>> should
>>> always be waited upon in a loop, testing the state predicate that is
>>> being
>>> waited for. An implementation is free to remove the possibility of
>>> spurious
>>> wakeups but it is recommended that applications programmers always assume
>>> that they can occur and so always wait in a loop.
>>>
>>
>> whereas the one in Object.wait(long) says:
>>
>> A thread can also wake up without being notified, interrupted, or timing
>>> out,
>>> a so-called spurious wakeup. While this will rarely occur in practice,
>>> applications must guard against it by testing for the condition that
>>> should
>>> have caused the thread to be awakened, and continuing to wait if the
>>> condition is not satisfied. In other words, waits should always occur in
>>> loops, like this one:
>>> 
>>>      synchronized (obj) {
>>>          while (<condition does not hold>)
>>>              obj.wait(timeout);
>>>          ... // Perform action appropriate to condition
>>>      }
>>>
>>
>> These mostly say the same thing, though the Condition spec talks about
>> the underlying implementation, whereas the Object.wait spec is strongly
>> oriented toward the application programmer. I think this is ok.
>>
>> If there's some bit of wording that needs to be corrected somewhere,
>> please suggest it.
>>
>> s'marks
>>
>>