RFR(s) #2: 6344935: (spec) clarify specifications for Object.wait overloads
stuart.marks at oracle.com
Fri Aug 25 01:50:56 UTC 2017
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
(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.)
More information about the core-libs-dev