[boost] boost/threads/condition.hpp documentation patch

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">