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

classic Classic list List threaded Threaded
11 messages Options
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

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

Stuart Marks
This is an old spec bug. The Object.wait spec lists several different reasons a
thread could be awakened, but it omits spurious wakeup -- even though spurious
wakeup is described later on. The fix is simply to add spurious wakeup to the list.

There is some discussion in the original bug report:

     https://bugs.openjdk.java.net/browse/JDK-6344935

Patch appended below.

Thanks,

s'marks



# HG changeset patch
# User smarks
# Date 1502475871 25200
#      Fri Aug 11 11:24:31 2017 -0700
# Node ID ebd66cd27b298d5bbbdfd348164505ef1195f90e
# Parent  27b08ab97a607df3a4abff83d8d1a2a1882e5bf1
6344935: Clarify Object.wait javadoc with respect to spurious wakeups
Reviewed-by: XXX

diff -r 27b08ab97a60 -r ebd66cd27b29
src/java.base/share/classes/java/lang/Object.java
--- a/src/java.base/share/classes/java/lang/Object.java Thu Aug 03 09:04:47 2017
-0700
+++ b/src/java.base/share/classes/java/lang/Object.java Fri Aug 11 11:24:31 2017
-0700
@@ -318,7 +318,7 @@
       * place itself in the wait set for this object and then to relinquish
       * any and all synchronization claims on this object. Thread <var>T</var>
       * becomes disabled for thread scheduling purposes and lies dormant
-     * until one of four things happens:
+     * until one of five things happens:
       * <ul>
       * <li>Some other thread invokes the {@code notify} method for this
       * object and thread <var>T</var> happens to be arbitrarily chosen as
@@ -330,7 +330,9 @@
       * <li>The specified amount of real time has elapsed, more or less.  If
       * {@code timeout} is zero, however, then real time is not taken into
       * consideration and the thread simply waits until notified.
+     * <li>Thread <var>T</var> is awakened spuriously. (See below.)
       * </ul>
+     * <p>
       * The thread <var>T</var> is then removed from the wait set for this
       * object and re-enabled for thread scheduling. It then competes in the
       * usual manner with other threads for the right to synchronize on the

Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

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

Lance Andersen
Looks fine Stuart


> On Aug 11, 2017, at 2:25 PM, Stuart Marks <[hidden email]> wrote:
>
> This is an old spec bug. The Object.wait spec lists several different reasons a thread could be awakened, but it omits spurious wakeup -- even though spurious wakeup is described later on. The fix is simply to add spurious wakeup to the list.
>
> There is some discussion in the original bug report:
>
>    https://bugs.openjdk.java.net/browse/JDK-6344935
>
> Patch appended below.
>
> Thanks,
>
> s'marks
>
>
>
> # HG changeset patch
> # User smarks
> # Date 1502475871 25200
> #      Fri Aug 11 11:24:31 2017 -0700
> # Node ID ebd66cd27b298d5bbbdfd348164505ef1195f90e
> # Parent  27b08ab97a607df3a4abff83d8d1a2a1882e5bf1
> 6344935: Clarify Object.wait javadoc with respect to spurious wakeups
> Reviewed-by: XXX
>
> diff -r 27b08ab97a60 -r ebd66cd27b29 src/java.base/share/classes/java/lang/Object.java
> --- a/src/java.base/share/classes/java/lang/Object.java Thu Aug 03 09:04:47 2017 -0700
> +++ b/src/java.base/share/classes/java/lang/Object.java Fri Aug 11 11:24:31 2017 -0700
> @@ -318,7 +318,7 @@
>      * place itself in the wait set for this object and then to relinquish
>      * any and all synchronization claims on this object. Thread <var>T</var>
>      * becomes disabled for thread scheduling purposes and lies dormant
> -     * until one of four things happens:
> +     * until one of five things happens:
>      * <ul>
>      * <li>Some other thread invokes the {@code notify} method for this
>      * object and thread <var>T</var> happens to be arbitrarily chosen as
> @@ -330,7 +330,9 @@
>      * <li>The specified amount of real time has elapsed, more or less.  If
>      * {@code timeout} is zero, however, then real time is not taken into
>      * consideration and the thread simply waits until notified.
> +     * <li>Thread <var>T</var> is awakened spuriously. (See below.)
>      * </ul>
> +     * <p>
>      * The thread <var>T</var> is then removed from the wait set for this
>      * object and re-enabled for thread scheduling. It then competes in the
>      * usual manner with other threads for the right to synchronize on the
>

 <http://oracle.com/us/design/oracle-email-sig-198324.gif>
 <http://oracle.com/us/design/oracle-email-sig-198324.gif> <http://oracle.com/us/design/oracle-email-sig-198324.gif>
 <http://oracle.com/us/design/oracle-email-sig-198324.gif>Lance Andersen| Principal Member of Technical Staff | +1.781.442.2037
Oracle Java Engineering
1 Network Drive
Burlington, MA 01803
[hidden email] <mailto:[hidden email]>



Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

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

Mandy Chung
In reply to this post by Stuart Marks
On 8/11/17 11:25 AM, Stuart Marks wrote:

>
> diff -r 27b08ab97a60 -r ebd66cd27b29
> src/java.base/share/classes/java/lang/Object.java
> --- a/src/java.base/share/classes/java/lang/Object.java    Thu Aug 03
> 09:04:47 2017 -0700
> +++ b/src/java.base/share/classes/java/lang/Object.java    Fri Aug 11
> 11:24:31 2017 -0700
> @@ -318,7 +318,7 @@
>       * place itself in the wait set for this object and then to
> relinquish
>       * any and all synchronization claims on this object. Thread
> <var>T</var>
>       * becomes disabled for thread scheduling purposes and lies dormant
> -     * until one of four things happens:
> +     * until one of five things happens:
Perhaps to say "until one of the following happens" to avoid the count.

>       * <ul>
>       * <li>Some other thread invokes the {@code notify} method for this
>       * object and thread <var>T</var> happens to be arbitrarily
> chosen as
> @@ -330,7 +330,9 @@
>       * <li>The specified amount of real time has elapsed, more or
> less.  If
>       * {@code timeout} is zero, however, then real time is not taken
> into
>       * consideration and the thread simply waits until notified.
> +     * <li>Thread <var>T</var> is awakened spuriously. (See below.)
>       * </ul>
> +     * <p>
>       * The thread <var>T</var> is then removed from the wait set for
> this
>       * object and re-enabled for thread scheduling. It then competes
> in the
>       * usual manner with other threads for the right to synchronize
> on the
>
Looks fine.

Mandy
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

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

Martin Buchholz-3
In reply to this post by Stuart Marks
Can we align the wording with existing wording in either LockSupport or
Condition?

On Fri, Aug 11, 2017 at 11:25 AM, Stuart Marks <[hidden email]>
wrote:

> This is an old spec bug. The Object.wait spec lists several different
> reasons a thread could be awakened, but it omits spurious wakeup -- even
> though spurious wakeup is described later on. The fix is simply to add
> spurious wakeup to the list.
>
> There is some discussion in the original bug report:
>
>     https://bugs.openjdk.java.net/browse/JDK-6344935
>
> Patch appended below.
>
> Thanks,
>
> s'marks
>
>
>
> # HG changeset patch
> # User smarks
> # Date 1502475871 25200
> #      Fri Aug 11 11:24:31 2017 -0700
> # Node ID ebd66cd27b298d5bbbdfd348164505ef1195f90e
> # Parent  27b08ab97a607df3a4abff83d8d1a2a1882e5bf1
> 6344935: Clarify Object.wait javadoc with respect to spurious wakeups
> Reviewed-by: XXX
>
> diff -r 27b08ab97a60 -r ebd66cd27b29 src/java.base/share/classes/ja
> va/lang/Object.java
> --- a/src/java.base/share/classes/java/lang/Object.java Thu Aug 03
> 09:04:47 2017 -0700
> +++ b/src/java.base/share/classes/java/lang/Object.java Fri Aug 11
> 11:24:31 2017 -0700
> @@ -318,7 +318,7 @@
>       * place itself in the wait set for this object and then to relinquish
>       * any and all synchronization claims on this object. Thread
> <var>T</var>
>       * becomes disabled for thread scheduling purposes and lies dormant
> -     * until one of four things happens:
> +     * until one of five things happens:
>       * <ul>
>       * <li>Some other thread invokes the {@code notify} method for this
>       * object and thread <var>T</var> happens to be arbitrarily chosen as
> @@ -330,7 +330,9 @@
>       * <li>The specified amount of real time has elapsed, more or less.
> If
>       * {@code timeout} is zero, however, then real time is not taken into
>       * consideration and the thread simply waits until notified.
> +     * <li>Thread <var>T</var> is awakened spuriously. (See below.)
>       * </ul>
> +     * <p>
>       * The thread <var>T</var> is then removed from the wait set for this
>       * object and re-enabled for thread scheduling. It then competes in
> the
>       * usual manner with other threads for the right to synchronize on the
>
>
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

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

Martin Buchholz-3
There's also an existing paragraph in Condition that goes
"When waiting upon a Condition, a spurious ... "

On Fri, Aug 11, 2017 at 11:50 AM, Martin Buchholz <[hidden email]>
wrote:

> Can we align the wording with existing wording in either LockSupport or
> Condition?
>
> On Fri, Aug 11, 2017 at 11:25 AM, Stuart Marks <[hidden email]>
> wrote:
>
>> This is an old spec bug. The Object.wait spec lists several different
>> reasons a thread could be awakened, but it omits spurious wakeup -- even
>> though spurious wakeup is described later on. The fix is simply to add
>> spurious wakeup to the list.
>>
>> There is some discussion in the original bug report:
>>
>>     https://bugs.openjdk.java.net/browse/JDK-6344935
>>
>> Patch appended below.
>>
>> Thanks,
>>
>> s'marks
>>
>>
>>
>> # HG changeset patch
>> # User smarks
>> # Date 1502475871 25200
>> #      Fri Aug 11 11:24:31 2017 -0700
>> # Node ID ebd66cd27b298d5bbbdfd348164505ef1195f90e
>> # Parent  27b08ab97a607df3a4abff83d8d1a2a1882e5bf1
>> 6344935: Clarify Object.wait javadoc with respect to spurious wakeups
>> Reviewed-by: XXX
>>
>> diff -r 27b08ab97a60 -r ebd66cd27b29 src/java.base/share/classes/ja
>> va/lang/Object.java
>> --- a/src/java.base/share/classes/java/lang/Object.java Thu Aug 03
>> 09:04:47 2017 -0700
>> +++ b/src/java.base/share/classes/java/lang/Object.java Fri Aug 11
>> 11:24:31 2017 -0700
>> @@ -318,7 +318,7 @@
>>       * place itself in the wait set for this object and then to
>> relinquish
>>       * any and all synchronization claims on this object. Thread
>> <var>T</var>
>>       * becomes disabled for thread scheduling purposes and lies dormant
>> -     * until one of four things happens:
>> +     * until one of five things happens:
>>       * <ul>
>>       * <li>Some other thread invokes the {@code notify} method for this
>>       * object and thread <var>T</var> happens to be arbitrarily chosen as
>> @@ -330,7 +330,9 @@
>>       * <li>The specified amount of real time has elapsed, more or less.
>> If
>>       * {@code timeout} is zero, however, then real time is not taken into
>>       * consideration and the thread simply waits until notified.
>> +     * <li>Thread <var>T</var> is awakened spuriously. (See below.)
>>       * </ul>
>> +     * <p>
>>       * The thread <var>T</var> is then removed from the wait set for this
>>       * object and re-enabled for thread scheduling. It then competes in
>> the
>>       * usual manner with other threads for the right to synchronize on
>> the
>>
>>
>
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: 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

Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

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

David Holmes
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
>
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

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

Hans Boehm-2
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.


On Fri, Aug 11, 2017 at 4:43 PM, David Holmes <[hidden email]>
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
>>
>>
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

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

Martin Buchholz-3
In reply to this post by Stuart Marks
Thanks for working on Object.wait.  Doc writing is never easy, especially
in Object.java.

In the original proposed patch, the word "also" ends up weird, because
spurious wakeup *was* in the list above; we need to do something about that.

On Fri, Aug 11, 2017 at 11:25 AM, Stuart Marks <[hidden email]>
wrote:

> This is an old spec bug. The Object.wait spec lists several different
> reasons a thread could be awakened, but it omits spurious wakeup -- even
> though spurious wakeup is described later on. The fix is simply to add
> spurious wakeup to the list.
>
> There is some discussion in the original bug report:
>
>     https://bugs.openjdk.java.net/browse/JDK-6344935
>
> Patch appended below.
>
> Thanks,
>
> s'marks
>
>
>
> # HG changeset patch
> # User smarks
> # Date 1502475871 25200
> #      Fri Aug 11 11:24:31 2017 -0700
> # Node ID ebd66cd27b298d5bbbdfd348164505ef1195f90e
> # Parent  27b08ab97a607df3a4abff83d8d1a2a1882e5bf1
> 6344935: Clarify Object.wait javadoc with respect to spurious wakeups
> Reviewed-by: XXX
>
> diff -r 27b08ab97a60 -r ebd66cd27b29 src/java.base/share/classes/ja
> va/lang/Object.java
> --- a/src/java.base/share/classes/java/lang/Object.java Thu Aug 03
> 09:04:47 2017 -0700
> +++ b/src/java.base/share/classes/java/lang/Object.java Fri Aug 11
> 11:24:31 2017 -0700
> @@ -318,7 +318,7 @@
>       * place itself in the wait set for this object and then to relinquish
>       * any and all synchronization claims on this object. Thread
> <var>T</var>
>       * becomes disabled for thread scheduling purposes and lies dormant
> -     * until one of four things happens:
> +     * until one of five things happens:
>       * <ul>
>       * <li>Some other thread invokes the {@code notify} method for this
>       * object and thread <var>T</var> happens to be arbitrarily chosen as
> @@ -330,7 +330,9 @@
>       * <li>The specified amount of real time has elapsed, more or less.
> If
>       * {@code timeout} is zero, however, then real time is not taken into
>       * consideration and the thread simply waits until notified.
> +     * <li>Thread <var>T</var> is awakened spuriously. (See below.)
>       * </ul>
> +     * <p>
>       * The thread <var>T</var> is then removed from the wait set for this
>       * object and re-enabled for thread scheduling. It then competes in
> the
>       * usual manner with other threads for the right to synchronize on the
>
>
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

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

David Holmes
In reply to this post by Hans Boehm-2
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 <[hidden email]
> <mailto:[hidden email]>> 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
>
>
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

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

Martin Buchholz-3
In reply to this post by Stuart Marks
OK, I'll try my hand as well at making forward progress:

diff --git a/src/java.base/share/classes/java/lang/Object.java
b/src/java.base/share/classes/java/lang/Object.java
--- a/src/java.base/share/classes/java/lang/Object.java
+++ b/src/java.base/share/classes/java/lang/Object.java
@@ -334,7 +334,7 @@
      * The thread <var>T</var> is then removed from the wait set for this
      * object and re-enabled for thread scheduling. It then competes in the
      * usual manner with other threads for the right to synchronize on the
-     * object; once it has gained control of the object, all its
+     * object; once it has regained control of the object, all its
      * synchronization claims on the object are restored to the status quo
      * ante - that is, to the situation as of the time that the {@code
wait}
      * method was invoked. Thread <var>T</var> then returns from the
Loading...