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

[Stuart Marks]

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.

> 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