|
|
Boost-Commit : |
From: bdawes_at_[hidden]
Date: 2007-12-03 15:17:32
Author: bemandawes
Date: 2007-12-03 15:17:31 EST (Mon, 03 Dec 2007)
New Revision: 41661
URL: http://svn.boost.org/trac/boost/changeset/41661
Log:
All threads chapter concepts converted to requirements.
Text files modified:
sandbox/committee/LWG/Pete_comments.html | 6
sandbox/committee/LWG/thread_library.html | 190 ++++++++++++++++++---------------------
2 files changed, 93 insertions(+), 103 deletions(-)
Modified: sandbox/committee/LWG/Pete_comments.html
==============================================================================
--- sandbox/committee/LWG/Pete_comments.html (original)
+++ sandbox/committee/LWG/Pete_comments.html 2007-12-03 15:17:31 EST (Mon, 03 Dec 2007)
@@ -216,8 +216,10 @@
quite fuzzy! Perhaps this precondition should simply be removed from
condition_variable_any::wait? (Added by Howard.)<br>
</li>
- <li>The term "block" is used a number of times, but is not defined either in
- this proposal or in the current working paper. (Added by Beman).</li>
+ <li>✔ The term "block" is used a number of times, but is not defined either in
+ this proposal or in the current working paper. (Added by Beman).<br>
+ <br>
+ <i>Definition provided. The definition was taken from the POSIX standard.</i></li>
</ol>
</body>
Modified: sandbox/committee/LWG/thread_library.html
==============================================================================
--- sandbox/committee/LWG/thread_library.html (original)
+++ sandbox/committee/LWG/thread_library.html 2007-12-03 15:17:31 EST (Mon, 03 Dec 2007)
@@ -68,10 +68,12 @@
<br> 30.1.1.7 thread specialized algorithms [thread.threads.algorithm]
<br> 30.1.2 Namespace this_thread [thread.threads.this]
<br> 30.2 Mutexs and locks [thread.mutex]
-<br> 30.2.1 Mutex concepts [thread.mutex.concept]
+<br> <a href="#thread.mutex.concept">30.2.1 Mutex
+requirements [thread.mutex.requirements]</a>
<br> 30.2.1.1 Class mutex [thread.mutex.class]
<br> 30.2.1.2 Class recursive_mutex [thread.mutex.recursive]
-<br> 30.2.2 Timed Mutex concept [thread.timed.concept]
+<br> <a href="#thread.timed.concept">30.2.2 TimedMutex
+requirements [thread.timedmutex.requirements]</a>
<br> 30.2.2.1 Class timed_mutex [thread.timed.class]
<br> 30.2.2.2 Class recursive_timed_mutex [thread.timed.recursive]
<br> 30.2.3 Locks [thread.lock.intro]
@@ -1155,10 +1157,15 @@
</code></pre>
</blockquote>
-<h4><a name="thread.mutex.concept">30.2.1 Mutex concepts [thread.mutex.concept]</a></h4>
+<h4><a name="thread.mutex.concept">30.2.1 Mutex requirements [thread.mutex.requirements]</a></h4>
<p>
-Mutex objects provide synchronization operations to avoid data races.
+<a name="thread.mutex.concept">[thread.mutex.requirements]</a> describes
+requirements on mutex types used to instantiate templates defined in the C++
+Standard Library</p>
+
+<p>
+Objects of mutex types provide synchronization operations to avoid data races.
A
mutex object supports mutual exclusion between threads by
limiting its ownership to a single thread.
@@ -1171,7 +1178,12 @@
non-recursive.
The syntax is the same for both recursive and
non-recursive mutexes, but the semantics differ for the member functions
-as described below.
+as described below.</p>
+
+<p>
+The template definitions in the C++ Standard Library refer to the named Mutex
+requirements whose details are set out below. In this description, <code>m</code>
+is an object of a mutex type.
</p>
<p>
@@ -1179,11 +1191,8 @@
shall be <code>DefaultConstructible</code> and <code>Destructible</code>.
If initialization
of a mutex type fails,
-an exception of type <code>system_error</code> shall be thrown.
-A mutex type is neither copyable
-nor movable.
-A mutex type shall have the following member functions:
-</p>
+an exception of type <code>system_error</code> shall be thrown. A mutex type is
+neither copyable nor movable.</p>
<p>
<b>[Crowl:
@@ -1283,9 +1292,9 @@
]</b>
</p>
-<pre><code>
-void lock();
-</code></pre>
+<p>
+The expression <code>m.lock()</code> shall be well-defined, and have the
+following semantics:</p>
<blockquote>
<dl>
@@ -1300,6 +1309,9 @@
Upon successful completion, the current thread owns the mutex.
</dd>
+<dt>Return type:</dt>
+<dd><code>void</code></dd>
+
<dt>Synchronization:</dt>
<dd>
This is an acquire operation [<cite>intro.multithread</cite>].
@@ -1314,9 +1326,9 @@
</dl>
</blockquote>
-<pre><code>
-bool try_lock();
-</code></pre>
+<p><code><br>
+</code>The expression <code>m.try_lock()</code> shall be well-defined, and have
+the following semantics:</p>
<blockquote>
<dl>
@@ -1333,6 +1345,9 @@
there is no effect and <code>try_lock()</code> immediately returns.
</dd>
+<dt>Return type:</dt>
+<dd><code>bool</code></dd>
+
<dt>Returns:</dt>
<dd>
If ownership of the mutex was obtained for the current thread,
@@ -1342,7 +1357,7 @@
An implementation may fail to obtain the lock
even if it is not held by any other thread.
[<i>Note:</i>
-This spurious failure should be uncommon.
+This spurious failure is normally uncommon.
—<i>end note</i>]
</dd>
@@ -1367,9 +1382,9 @@
</dl>
</blockquote>
-<pre><code>
-void unlock();
-</code></pre>
+<p><code><br>
+</code>The expression <code>m.unlock()</code> shall be well-defined, and have
+the following semantics:</p>
<blockquote>
<dl>
@@ -1388,6 +1403,9 @@
or by any other locking function) before ownership is released.
</dd>
+<dt>Return type:</dt>
+<dd><code>void</code></dd>
+
<dt>Synchronization:</dt>
<dd>
<code>unlock</code> is a release operation [<cite>intro.multithread</cite>]
@@ -1467,18 +1485,17 @@
It shall be a standard-layout class (chapter 9 [class]).
</p>
-<h4><a name="thread.timed.concept">30.2.2 Timed Mutex concept [thread.timed.concept]</a></h4>
+<h4><a name="thread.timed.concept">30.2.2 TimedMutex requirements [thread.timedmutex.requirements]</a></h4>
<p>
-To meet the requirements of the Timed Mutex concept,
-types are required to meet the requirements of the Mutex concept
-and to provide the member functions <code>timed_lock</code>.
-</p>
+To meet the TimedMutex requirements,
+types are required to meet the Mutex requirements. In addition, one or the other
+of the following requirements shall be met, where <code>rel_time</code> denotes
+an rvalue of a type meeting the Duration([]) requirements or <code>abs_time</code>
+denotes an rvalue of type <code>system_time</code>:</p>
-<pre><code>
-template <class Duration>
- bool timed_lock(const Duration& rel_time);
-</code></pre>
+<p>The expression <code>m.timed_lock(rel_time)</code> shall be well-defined, and
+have the following semantics:</p>
<blockquote>
<dl>
@@ -1508,6 +1525,9 @@
—<i>end note</i>]
</dd>
+<dt>Return type:</dt>
+<dd><code>bool</code></dd>
+
<dt>Returns:</dt>
<dd>
<code>true</code> if ownership was obtained, otherwise <code>false</code>.
@@ -1526,44 +1546,40 @@
</dl>
</blockquote>
-<pre><code>
-bool timed_lock(const system_time& abs_time);
-</code></pre>
+<p><code><br>
+</code>The expression <code>m.timed_lock(abs_time)</code> shall be well-defined,
+and have the following semantics:</p>
<blockquote>
<dl>
<dt>Precondition:</dt>
<dd>
-For non-recursive mutexes the current thread shall not own
-the mutex.
+For non-recursive mutexes the current thread shall not own the mutex.
</dd>
<dt>Effects:</dt>
<dd>
-The function attempts to obtain ownership of the mutex
-by the specified time.
-If the indicated time has already passed,
-the function still attempts to obtain ownership without
-blocking (as if by calling <code>try_lock()</code>).
-If the function returns by the specified time,
-it shall have obtained ownership.
-[<i>Note:</i>
-As with <code>try_lock()</code>,
-there is no guarantee that ownership will be obtained
-if the lock is available,
-but implementations are expected to make a strong effort to do so.
-—<i>end note</i>]
+The function attempts to obtain ownership of the mutex by the specified time. If
+the indicated time has already passed, the function still attempts to obtain
+ownership without blocking (as if by calling <code>try_lock()</code>). If the
+function returns by the specified time, it shall have obtained ownership. [<i>Note:</i>
+As with <code>try_lock()</code>, there is no guarantee that ownership will be
+obtained if the lock is available, but implementations are expected to make a
+strong effort to do so. —<i>end note</i>]
</dd>
+<dt>Return type:</dt>
+<dd><code>bool</code></dd>
+
<dt>Returns:</dt>
<dd>
-<code>true</code> if ownership was obtained, otherwise <code>false</code>.
+<code>true</code> if ownership was obtained, otherwise <code>false</code>.
</dd>
<dt>Synchronization:</dt>
<dd>
-If <code>timed_lock</code> returns <code>true</code>,
-it is an acquire operation [<cite>intro.multithread</cite>].
+If <code>timed_lock</code> returns <code>true</code>, it is an acquire operation
+[<cite>intro.multithread</cite>].
</dd>
<dt>Throws:</dt>
@@ -1605,7 +1621,7 @@
<p>
The class <code>timed_mutex</code> provides a non-recursive mutex type
-that satisfies all of the Timed Mutex requirements.
+that satisfies all of the TimedMutex requirements.
It shall be a standard-layout class (chapter 9 [class]).
</p>
@@ -1641,7 +1657,7 @@
<p>
The class <code>recursive_timed_mutex</code> provides a recursive mutex type
-that satisfies all of the Timed Mutex requirements.
+that satisfies all of the TimedMutex requirements.
It shall be a standard-layout class (chapter 9 [class]).
</p>
@@ -2385,31 +2401,18 @@
<h4><a name="thread.lock.algorithm">30.2.4 Generic Locking Algorithms [thread.lock.algorithm]</a></h4>
<pre><code>
-template <class L1, class L2, class ...L3> int try_lock(L1&, L2&, L3&...);
-</code></pre>
+template <class L1, class L2, class ...L3> int try_lock(L1&, L2&, L3&...);</code></pre>
-<blockquote>
-<dl>
-<dt>Requires:</dt>
-<dd>
-<p>
-Each template parameter type supplies the following member functions
-with semantics that meet the requirements of the Mutex concept,
+<p>Each template parameter type shall meet the Mutex requirements,
except that <code>try_lock</code> is allowed to throw an
exception.
[<i>Note:</i>
The <code>unique_lock</code> class template meets these requirements
when suitable instantiated.
-—<i>end note</i>]
-</p>
+—<i>end note</i>] </p>
<blockquote>
-<pre><code>
-bool try_lock();
-void unlock();
-</code></pre>
-</blockquote>
-</dd>
+<dl>
<dt>Effects:</dt>
<dd>
@@ -2435,16 +2438,10 @@
</blockquote>
<pre><code>
-template <class L1, class L2, class ...L3> void lock(L1&, L2&, L3&...);
-</code></pre>
+template <class L1, class L2, class ...L3> void lock(L1&, L2&, L3&...);</code></pre>
-<blockquote>
-<dl>
-<dt>Requires:</dt>
-<dd>
<p>
-Each template parameter type supplies the following member functions
-with semantics that meet the requirements of the Mutex concept,
+Each template parameter type shall meet the Mutex requirements,
except that <code>try_lock</code> is allowed to
throw an exception
[<i>Note:</i>
@@ -2454,22 +2451,17 @@
</p>
<blockquote>
-<pre><code>
-void lock();
-bool try_lock();
-void unlock();
-</code></pre>
-</blockquote>
-</dd>
+<dl>
<dt>Effects:</dt>
<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>, or <code>unlock()</code> on the argument. The sequence of calls shall not
+result in deadlock, but is otherwise unspecified. <i>[Note:</i> A deadlock avoidance algorithm such as try-and-back-off
+must be used, but the
+specific algorithm is not specified to avoid over-constraining implementations.
+<i>--end
+note]</i> 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>
@@ -2968,8 +2960,7 @@
</p>
<blockquote>
-<pre><code>
-while (!<var>pred</var>())
+<pre><code>while (!<var>pred</var>())
{
if (!timed_wait(<var>lock</var>, <var>abs_time</var>))
return <var>pred</var>();
@@ -3012,8 +3003,7 @@
</p>
<blockquote>
-<pre><code>
-return timed_wait(<var>lock</var>, get_system_time() + <var>rel_time</var>, std::move(<var>pred</var>));
+<pre><code>return timed_wait(<var>lock</var>, get_system_time() + <var>rel_time</var>, std::move(<var>pred</var>));
</code></pre>
</blockquote>
</dd>
@@ -3052,11 +3042,9 @@
</p>
<p>
-The <code>Lock</code> type
-must support member functions <code>lock</code> and <code>unlock</code>
-with the semantics of the mutex concept.
-All of the standard mutex types
-meet this requirement.
+To meet the Lock requirement, types shall meet the Mutex requirement except that
+<code>try_lock</code> is not required. <i>[Note: </i>All of the standard mutex
+types meet this requirement. <i>--end note] </i>
</p>
<blockquote>
@@ -3916,7 +3904,7 @@
<p>
-[<b>Comment:</b>
+<i>[<b>Comment:</b>
Typical personal computer platforms currently achieve microsecond level
resolution from calls to the clock.
The
@@ -3925,7 +3913,7 @@
has a class that portably implements the proposed interface,
but it uses different C-level interfaces depending on the operating
system.
-—<b>end comment</b>]
+—<b>end comment</b>] </i>
</p>
<h3><a name="time.duration">31.3 Common Duration Functions [time.duration]</a></h3>
@@ -5510,4 +5498,4 @@
</p>
</body>
-</html>
+</html>
\ No newline at end of file
Boost-Commit list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk