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

[David Holmes]

I have no further comments on the actual spec.

Here's my suggestion for the timed-wait example :)

while (true) {
   if (!condition)
     wait(timeout, nanos);
   else
     break; // condition holds
   <recompute timeout>
   if (timeout <= 0 && !condition)
     throw new TimedOutException();
}
// Perform action appropriate to condition

Cheers,
David

On 25/08/2017 11:50 AM, Stuart Marks wrote:
> 
> 
> 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
> 
> 
>