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

[David Holmes]

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
>