[Boost-commit] svn:boost r41641 - sandbox/committee/LWG

From: bdawes_at_[hidden]
Date: 2007-12-03 08:24:39

Author: bemandawes
Date: 2007-12-03 08:24:38 EST (Mon, 03 Dec 2007)
New Revision: 41641
URL: http://svn.boost.org/trac/boost/changeset/41641

Log:
Add definitions for blocked thread and deadlock. Clarify generic locking algorithm wording to resolve Pete's issues 22 and 23.
Text files modified: 
   sandbox/committee/LWG/Pete_comments.html  |    14 ++++++-                                 
   sandbox/committee/LWG/thread_library.html |    80 ++++++++++++++++++++++++++------------- 
   2 files changed, 65 insertions(+), 29 deletions(-)

Modified: sandbox/committee/LWG/Pete_comments.html
==============================================================================
--- sandbox/committee/LWG/Pete_comments.html	(original)
+++ sandbox/committee/LWG/Pete_comments.html	2007-12-03 08:24:38 EST (Mon, 03 Dec 2007)
@@ -139,11 +139,16 @@
   <i>Fixed. Wording changed. Wording posted to list to make sure others are 
   happy with it.</i><br>
 &nbsp;</li>
-  <li>generic locking algorithms: is there a requirement that the locks be 
+  <li>&#10004;  generic locking algorithms: is there a requirement that the locks be 
   attempted in any particular order?<br>
+  <br>
+  <i>Yes, for try_lock, no, for lock. Text clarified.</i><br>
 &nbsp;</li>
-  <li>generic locking algorithms, lock: what does &quot;an algorithm that avoids 
+  <li>&#10004;  generic locking algorithms, lock: what does &quot;an algorithm that avoids 
   deadlocks&quot; mean? What, exactly, is required?<br>
+  <br>
+  <i>Definitions for &quot;blocked thread&quot; and &quot;deadlock&quot; added to chapter 17. 
+  Generic locking algorithms text clarified accordingly.</i><br>
 &nbsp;</li>
   <li>&#10004; <a name="issue24">condition_variable</a>::wait: &quot;... unless lock refers to the same underlying 
   mutex object.&quot; Same as what?<br>
@@ -176,6 +181,11 @@
   <li>&#10004; Use &quot;thread&quot; to describe a &quot;thread of execution&quot;. Use the term &quot;thread 
   object&quot; to describe objects of class thread. (Added by Beman, based on 
   guidance from Pete.)<br>
+  <br>
+  <i>Changed. Retrained a few usages of &quot;thread of execution&quot; relating to 
+  classes thread and thread::id where both thread objects and threads of 
+  execution are being discussed, and it is otherwise very easy to confuse the 
+  two.</i><br>
 &nbsp;</li>
   <li>&#10004; condition_variable::wait and time_wait specify &quot;<i>Throws:</i> May throw <tt>system_error</tt> if a precondition is not met.&quot; 
   That's redundant since precondition violations can always result in an 

Modified: sandbox/committee/LWG/thread_library.html
==============================================================================
--- sandbox/committee/LWG/thread_library.html	(original)
+++ sandbox/committee/LWG/thread_library.html	2007-12-03 08:24:38 EST (Mon, 03 Dec 2007)
@@ -49,8 +49,11 @@
 <h2>Contents</h2>
 
 <p>
-<br>Introduction
-<br>Chapter 20   General utilities library [utilities]
+<br>Introduction <br>
+Chapter 17   Library introduction [library]<br>
+&nbsp;&nbsp;&nbsp; <a href="#defns.thread.blocked">17.1.? blocked thread 
+[defns.thread.blocked]</a><br>
+&nbsp;&nbsp;&nbsp; 17.1.? deadlock [defns.deadlock]<br>Chapter 20   General utilities library [utilities]
 <br>&nbsp;&nbsp;&nbsp;&nbsp;20.5 Function objects [function.objects]
 <br>&nbsp;&nbsp;&nbsp;&nbsp;20.5.15 Class template hash [unord.hash]
 <br>Chapter 30   Multi-threading library [thread]
@@ -202,6 +205,28 @@
 That is, to have a named 'Sychronization:' attribute.]</b>
 </p>
 
+<h2><a name="library">Chapter 17&nbsp;&nbsp; Library introduction [library]</a></h2>
+
+<p>Add the following definitions:</p>
+
+<blockquote>
+
+<h4>17.1.? blocked thread [<a name="defns.thread.blocked">defns.thread.blocked</a>]</h4>
+
+<p>a thread that is waiting for some condition (other than the availability of a 
+processor) to be satisfied before it can continue execution <sup>(footnote)</sup>. 
+As a verb, <i><b>to block</b></i> is to place a thread in the blocked state, and
+<b><i>to unblock</i></b> is to place a thread in the unblocked state.<br>
+<br>
+<sup>(footnote)</sup> This definition is taken from POSIX.</p>
+
+<h4>17.1.? deadlock [<a name="defns.deadlock">defns.deadlock</a>]</h4>
+
+<p>two or more threads are unable to continue execution because each is blocked 
+waiting for one or more of the others to satisfy some condition.</p>
+
+</blockquote>
+
 <h2><a name="utilities">Chapter 20&nbsp;&nbsp; General utilities library [utilities]</a></h2>
 
 <h3><a name="function.objects">20.5 Function objects [function.objects]</a></h3>
@@ -2368,9 +2393,8 @@
 <dt>Requires:</dt>
 <dd>
 <p>
-Each template parameter type must supply the following member functions
-with semantics
-corresponding to the Mutex concept,
+Each template parameter type supplies the following member functions
+with semantics that meet the requirements of the Mutex concept,
 except that <code>try_lock</code> is allowed to throw an
 exception.
 [<i>Note:</i>
@@ -2389,24 +2413,24 @@
 
 <dt>Effects:</dt>
 <dd>
-The functions attempts to lock all arguments
-without blocking by calling <code>try_lock()</code>
-on each of them.
-If any argument can not be locked,
-then all arguments which have already been locked will
-be unlocked.
-On return, either all arguments will be locked, or none of them will be locked.
-If an
-exception is thrown by a call to <code>try_lock()</code>, there are no effects.
-</dd>
+Calls <code>try_lock()</code> for each argument in order beginning with the 
+first until either all arguments have been processed, a call to <code>try_lock()</code> 
+returns <code>false</code>, or a call to <code>try_lock()</code> throws an 
+exception. If a call to <code>try_lock()</code> returns <code>false</code> or 
+throws an exception, the <code>unlock()</code> function is called for any prior 
+arguments.</dd>
+
+</dl>
+<dl>
 
 <dt>Returns:</dt>
 <dd>
-If all arguments were successfully locked, returns <code>-1</code>.
+If all calls to <code>try_lock()</code> returned <code>true</code>, returns <code>-1</code>.
 Otherwise returns a 0-based index
-value indicating
-which argument failed to lock.
-</dd>
+value indicating for
+which argument <code>try_lock()</code> returned <code>false</code>.&nbsp; <i>
+[Note:</i> On return, either all arguments will be locked or none will be 
+locked. <i>-- end note]</i></dd>
 </dl>
 </blockquote>
 
@@ -2419,9 +2443,8 @@
 <dt>Requires:</dt>
 <dd>
 <p>
-Each template parameter type must supply the following member functions
-with semantics
-corresponding to the Mutex concept,
+Each template parameter type supplies the following member functions
+with semantics that meet the requirements of the Mutex concept,
 except that <code>try_lock</code> is allowed to
 throw an exception
 [<i>Note:</i>
@@ -2441,11 +2464,14 @@
 
 <dt>Effects:</dt>
 <dd>
-All arguments are locked with an algorithm that avoids deadlock.
-If an exception is thrown
-by a call to <code>lock()</code> or <code>try_lock()</code>,
-there are no effects.
-</dd>
+All arguments are locked via a sequence of calls to <code>lock()</code>, <code>
+try_lock()</code>, or <code>unlock()</code>. The sequence of calls shall not 
+result in deadlock, but is otherwise unspecified. [Note: Implementations are 
+required to use a deadlock avoidance algorithm such as try-and-back-off, but the 
+specific algorithm is unspecified to avoid over-constraining implementors. --end 
+note] If an exception is thrown by a call to <code>lock()</code> or <code>
+try_lock()</code>, then <code>unlock()</code> will be called for any argument 
+which had been locked by a call to <code>lock()</code> or <code>try_lock()</code>.</dd>
 </dl>
 </blockquote>