RFR(s) #2: 6344935: (spec) clarify specifications for Object.wait overloads

[Stuart Marks]

On 8/20/17 6:32 PM, David Holmes wrote:
> You're a brave man :)

"It's a dirty job, but somebody's gotta do it." :-)

I have a personal interest in this, as back in the 1.3 days I was trying to nail 
down some multi-threaded code, and I found the wait() docs to be quite lacking. 
In particular, they didn't cover what happened if a thread had been interrupted 
*before* wait was called; they didn't cover spurious wakeup; and there was no 
recommendation to call wait() from within a loop. This last was particularly 
frustrating because it was something that "everybody knew" should be done but it 
wasn't actually documented. I'm pleased that these issues have been addressed, 
though some cleaning up remains -- hence this changeset.

I've made a few more changes and non-changes in response to comments.

1) Added comma in @param timeout in two locations, per Martin.

2) I didn't remove @see links where similar links occurred in the text. I think 
it's important that all the wait methods have @see links to both notify and 
notifyAll and to the other two methods in the wait family.

3) I left the bullet point "The specified amount of real time has elapsed, more 
or less" unchanged, as it seems Martin is still unable to convince David even 
after all these years.

4) Restored the sentence about clearing the thread's interrupted status, in 
three locations of @throws InterruptedException, per David.

5) I see there was a long discussion about the code snippet. I had to take some 
liberties with the logic here, as adding timeout recomputation pseudo-code as 
suggested by Hans Boehm clearly begged the question of what to do with the loop 
condition if the timeout has elapsed. I rather sidestepped this by adding a 
"<timeout not exceeded>" clause in the while-condition. I think this satisfies 
Hans' original comment, and it's not incorrect, but it does leave several of 
questions unanswered about how timed-wait logic should be implemented, and how 
to distinguish between a timeout and a notification. Martin suggested that I 
just proceed with this, and that the examples can be revisited when/if the 
TimeUnit.timedWait example is updated. I'm fine with that. I hope everybody else 
is too.

Revised webrev:

     http://cr.openjdk.java.net/~smarks/reviews/6344935/webrev.2/

Javadoc output:

     http://cr.openjdk.java.net/~smarks/reviews/6344935/java/lang/Object.html#wait--

(Note, this is just a single, unstyled HTML file, so the formatting is somewhat 
odd. The text of the wait methods should be fairly readable, though.)

s'marks