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

[David Holmes]

On 12/08/2017 10:58 AM, Hans Boehm wrote:
> 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.

You mean because it does not recompute the timeout and so will possibly 
wait longer than intended?

David

> 
> On Fri, Aug 11, 2017 at 4:43 PM, David Holmes <david.holmes at oracle.com 
> <mailto: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
> 
>