Boost logo

Boost :

From: Larry Lansing (llansing_at_[hidden])
Date: 2005-03-15 14:24:27


Attached please find a patch for boost/libs/thread/doc/condition-ref.xml
which re-adds a warning about spurious wakeups that appeared in older
versions of the boost threads documentation.

Compare and contrast:

http://www-eleves-isia.cma.fr/documentation/BoostDoc/boost_1_29_0/libs/thread/doc/condition.html
vs.
http://www.boost.org/doc/html/condition.html

The newer boost.org version omits this paragraph:

***
Danger: This version should always be used within a loop checking that
the state logically associated with the condition has become true.
Without the loop, race conditions can ensue due to possible "spurious
wake ups". The second version encapsulates this loop idiom internally
and is generally the preferred method.
***

Unless there was an important reason that this warning was removed, it
seems like the spurious wakeup issue should definitely be mentioned in
the wait() and timed_wait() interfaces. Unless I've screwed it up, the
attached patch should put this paragraph in the right places.

Thank you for your time.

--
Larry Lansing

Index: condition-ref.xml
===================================================================
RCS file: /cvsroot/boost/boost/libs/thread/doc/condition-ref.xml,v
retrieving revision 1.3
diff -d -u -r1.3 condition-ref.xml
--- condition-ref.xml 17 Jul 2004 04:33:59 -0000 1.3
+++ condition-ref.xml 15 Mar 2005 19:18:42 -0000
@@ -97,6 +97,13 @@
               lock.</simpara></effects>
           <throws><simpara><classname>lock_error</classname> if
               <code>!lock.locked()</code></simpara></throws>
+ <notes><simpara>This version should always be used within a
+ loop checking that the state logically associated with the
+ <classname>condition</classname> has become true. Without
+ the loop, race conditions can ensue due to possible
+ "spurious wake ups". The second version encapsulates this
+ loop idiom internally and is generally the preferred
+ method.</simpara></notes>
         </method>
 
         <method name="wait">
@@ -153,6 +160,13 @@
               otherwise <code>true</code>.</simpara></returns>
           <throws><simpara><classname>lock_error</classname> if
               <code>!lock.locked()</code></simpara></throws>
+ <notes><simpara>This version should always be used within a
+ loop checking that the state logically associated with the
+ <classname>condition</classname> has become true. Without
+ the loop, race conditions can ensue due to possible
+ "spurious wake ups". The second version encapsulates this
+ loop idiom internally and is generally the preferred
+ method.</simpara></notes>
         </method>
 
         <method name="timed_wait">


Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk