|
Boost-Commit : |
From: Lawrence_at_[hidden]
Date: 2007-12-03 21:20:54
Author: crowl
Date: 2007-12-03 21:20:54 EST (Mon, 03 Dec 2007)
New Revision: 41673
URL: http://svn.boost.org/trac/boost/changeset/41673
Log:
Provide introductory text for each major section.
Provide subsections for common isses. (Eases citations.)
Text files modified:
sandbox/committee/LWG/thread_library.html | 209 ++++++++++++++++++++++++---------------
1 files changed, 126 insertions(+), 83 deletions(-)
Modified: sandbox/committee/LWG/thread_library.html
==============================================================================
--- sandbox/committee/LWG/thread_library.html (original)
+++ sandbox/committee/LWG/thread_library.html 2007-12-03 21:20:54 EST (Mon, 03 Dec 2007)
@@ -50,43 +50,47 @@
<h2>Contents</h2>
<p>
-<br>Introduction <br>
-Chapter 17 Library introduction [library]<br>
- <a href="#defns.thread.blocked">17.1.? blocked thread
-[defns.thread.blocked]</a><br>
- 17.1.? deadlock [defns.deadlock]<br>Chapter 20 General utilities library [utilities]
+<br>Introduction
+<br>Chapter 17 Library introduction [library]
+<br> 17.1.? blocked thread [defns.thread.blocked]
+<br> 17.1.? deadlock [defns.deadlock]
+<br>Chapter 20 General utilities library [utilities]
<br> 20.5 Function objects [function.objects]
<br> 20.5.15 Class template hash
[unord.hash]
<br>Chapter 30 Multi-threading library [thread]
-<br> 30.1 Threads [thread.threads]
-<br> 30.1.1 Class thread [thread.threads.class]
-<br> 30.1.1.1 Class thread::id
[thread.threads.id]
-<br> 30.1.1.2 thread
constructors [thread.threads.constr]
-<br> 30.1.1.3 thread
destructor [thread.threads.destr]
-<br> 30.1.1.4 thread
assignment [thread.threads.assign]
-<br> 30.1.1.5 thread
members [thread.threads.member]
-<br> 30.1.1.6 thread
static members [thread.threads.static]
-<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> <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> <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]
-<br> 30.2.3.1 Class lock_guard [thread.lock.guard]
-<br> 30.2.3.2 Class unique_lock [thread.lock.unique]
-<br> 30.2.4 Generic Locking Algorithms [thread.lock.algorithm]
-<br> 30.2.5 Call Once [thread.mutex.once]
-<br> 30.2.5.1 struct once_flag
[thread.mutex.onceflag]
-<br> 30.2.5.2 Non-member function call_once
[thread.threads.callonce]
-<br> 30.3 Condition variables [thread.condition]
-<br> 30.3.1 Class condition_variable [thread.condvar]
-<br> 30.3.2 Class condition_variable_any [thread.condvarany]
+<br> 30.1 Common Issues [thread.common]
+<br> 30.1.1 Template Parameter Names [thread.tmplparmname]
+<br> 30.1.2 Exceptions [thread.exception]
+<br> 30.1.3 Native Handles [thread.native]
+<br> 30.1.4 Duration Timeout [thread.duration]
+<br> 30.1.5 Thread Safety [thread.safety]
+<br> 30.2 Threads [thread.threads]
+<br> 30.2.1 Class thread [thread.threads.class]
+<br> 30.2.1.1 Class thread::id
[thread.threads.id]
+<br> 30.2.1.2 thread
constructors [thread.threads.constr]
+<br> 30.2.1.3 thread
destructor [thread.threads.destr]
+<br> 30.2.1.4 thread
assignment [thread.threads.assign]
+<br> 30.2.1.5 thread
members [thread.threads.member]
+<br> 30.2.1.6 thread
static members [thread.threads.static]
+<br> 30.2.1.7 thread
specialized algorithms [thread.threads.algorithm]
+<br> 30.2.2 Namespace this_thread
[thread.threads.this]
+<br> 30.3 Mutual Exclusion [thread.mutex]
+<br> 30.3.1 Mutex requirements [thread.mutex.requirements]
+<br> 30.3.1.1 Class mutex [thread.mutex.class]
+<br> 30.3.1.2 Class recursive_mutex [thread.mutex.recursive]
+<br> 30.3.2 TimedMutex requirements [thread.timedmutex.requirements]
+<br> 30.3.2.1 Class timed_mutex [thread.timed.class]
+<br> 30.3.2.2 Class recursive_timed_mutex [thread.timed.recursive]
+<br> 30.3.3 Locks [thread.lock.intro]
+<br> 30.3.3.1 Class lock_guard [thread.lock.guard]
+<br> 30.3.3.2 Class unique_lock [thread.lock.unique]
+<br> 30.3.4 Generic Locking Algorithms [thread.lock.algorithm]
+<br> 30.3.5 Call Once [thread.mutex.once]
+<br> 30.3.5.1 struct once_flag
[thread.mutex.onceflag]
+<br> 30.3.5.2 non-member function call_once
[thread.threads.callonce]
+<br> 30.4 Condition variables [thread.condition]
+<br> 30.4.1 Class condition_variable [thread.condvar]
+<br> 30.4.2 Class condition_variable_any [thread.condvarany]
<br>Chapter 31 Date Time Library [time]
<br> 31.1 Class system_time [time.system]
<br> 31.2 Function get_system_time [time.getsystem]
@@ -214,7 +218,7 @@
<blockquote>
-<h4>17.1.? blocked thread [<a name="defns.thread.blocked">defns.thread.blocked</a>]</h4>
+<h4><a name="dfns.thread.blocked">17.1.? blocked thread [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>.
@@ -223,7 +227,7 @@
<br>
<sup>(footnote)</sup> This definition is taken from POSIX.</p>
-<h4>17.1.? deadlock [<a name="defns.deadlock">defns.deadlock</a>]</h4>
+<h4><a name="defns.deadlock">17.1.? 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>
@@ -282,8 +286,8 @@
<p>
The following subclauses describe components to create and manage threads
([<cite>1.10 [intro.multithread]</cite>]),
-perform mutual exclusion and locking, and communicate
-between threads.
+perform mutual exclusion,
+and communicate conditions between threads.
</p>
<table>
@@ -296,7 +300,7 @@
<td><code><thread></code></td>
</tr>
<tr>
- <td>Mutexs and locks</td>
+ <td>Mutual Exclusion</td>
<td><code><mutex></code></td>
</tr>
<tr>
@@ -305,17 +309,32 @@
</tr>
</tbody></table>
+
+<h3><a name="thread.common">30.1 Common Issues [thread.common]</a></h3>
+
+
+<h4><a name="thread.tmplparmname">30.1.1 Template Parameter Names [thread.tmplparmname]</a></h4>
+
+<p>
+Throughout this clause,
+the names of template parameters are used to express type requirements.
+</p>
+
<p>
-Throughout this clause, the names of template parameters are used to express
-type requirements.
The requirements for Duration parameters are specified in
[<cite>reference to date-time library clause</cite>].
+</p>
+
+<p>
If a parameter is Predicate, <code>operator()</code>
applied to the actual template argument
shall return a value that is convertible
to <code>bool</code>.
</p>
+
+<h4><a name="thread.exception">30.1.2 Exceptions [thread.exception]</a></h4>
+
<p>
Implementations of functions described in this clause are permitted to call
operating system or other low-level applications program interfaces (API's).
@@ -342,6 +361,9 @@
—<i>end note</i>]
</p>
+
+<h4><a name="thread.native">30.1.3 Native Handles [thread.native]</a></h4>
+
<p>
Several classes described in this clause have members <code>
native_handle_type</code> and <code>native_handle</code>.
@@ -357,6 +379,9 @@
—<i>end note</i>]
</p>
+
+<h4><a name="thread.native">30.1.4 Duration Timeout [thread.duration]</a></h4>
+
<p>
Several functions described in this clause take an argument specifying
a timeout. [<i>Note:</i> Reasonable use cases exist for both duration and
@@ -364,6 +389,8 @@
contraindicated. <i>--end note.</i>]
</p>
+<h4><a name="thread.native">30.1.5 Thread Safety [thread.safety]</a></h4>
+
<p>
<b>[Crowl: I think we need a general statement that
operations on std::thread are not thread-safe unless specifically mentioned.
@@ -371,7 +398,17 @@
</p>
-<h3><a name="thread.threads">30.1 Threads [thread.threads]</a></h3>
+<h3><a name="thread.threads">30.2 Threads [thread.threads]</a></h3>
+
+<p>
+This section describes components to create and manage threads.
+<p>
+
+<p>
+[<i>Note:</i>
+These threads are intended to map one-to-one with operating system threads.
+—<i>end note</i>]
+
<p>
<strong><thread> synopsis</strong>
@@ -402,7 +439,7 @@
</code></pre>
</blockquote>
-<h4><a name="thread.threads.class">30.1.1 Class thread [thread.threads.class]</a></h4>
+<h4><a name="thread.threads.class">30.2.1 Class thread [thread.threads.class]</a></h4>
<p>
An object of class <code>thread</code> represents and manages a thread of
@@ -426,7 +463,7 @@
public:
// <em>types:</em>
class id;
- typedef <var><strong>implementation-defined</strong></var> native_handle_type; // <em>See [frontmatter]</em>
+ typedef <var><strong>implementation-defined</strong></var> native_handle_type; // <em>See [thread.native]</em>
// <em>construct/copy/destroy:</em>
thread();
@@ -444,7 +481,7 @@
void join();
void detach();
id get_id() const;
- native_handle_type native_handle(); // <em>See [frontmatter]</em>
+ native_handle_type native_handle(); // <em>See [thread.native]</em>
// <em>static members:</em>
static unsigned hardware_concurrency();
@@ -458,7 +495,7 @@
classes (chapter 9 [class]).
</p>
-<h5><a name="thread.threads.id">30.1.1.1 Class <code>thread::id</code> [thread.threads.id]</a></h5>
+<h5><a name="thread.threads.id">30.2.1.1 Class <code>thread::id</code> [thread.threads.id]</a></h5>
<blockquote>
<pre><code>
@@ -654,7 +691,7 @@
</dl>
</blockquote>
-<h5><a name="thread.threads.constr">30.1.1.2 <code>thread</code> constructors [thread.threads.constr]</a></h5>
+<h5><a name="thread.threads.constr">30.2.1.2 <code>thread</code> constructors [thread.threads.constr]</a></h5>
<pre><code>
thread();
@@ -770,7 +807,7 @@
</dl>
</blockquote>
-<h5><a name="thread.threads.destr">30.1.1.3 <code>thread</code> destructor [thread.threads.destr]</a></h5>
+<h5><a name="thread.threads.destr">30.2.1.3 <code>thread</code> destructor [thread.threads.destr]</a></h5>
<pre><code>
~thread();
@@ -791,7 +828,7 @@
</dl>
</blockquote>
-<h5><a name="thread.threads.assign">30.1.1.4 <code>thread</code> assignment [thread.threads.assign]</a></h5>
+<h5><a name="thread.threads.assign">30.2.1.4 <code>thread</code> assignment [thread.threads.assign]</a></h5>
<pre><code>
thread& operator=(thread&& <var>x</var>);
@@ -832,7 +869,7 @@
</dl>
</blockquote>
-<h5><a name="thread.threads.member">30.1.1.5 <code>thread</code> members [thread.threads.member]</a></h5>
+<h5><a name="thread.threads.member">30.2.1.5 <code>thread</code> members [thread.threads.member]</a></h5>
<pre><code>
void swap(thread&& <var>x</var>);
@@ -957,7 +994,7 @@
</dl>
</blockquote>
-<h5><a name="thread.threads.static">30.1.1.6 <code>thread</code> static members [thread.threads.static]</a></h5>
+<h5><a name="thread.threads.static">30.2.1.6 <code>thread</code> static members [thread.threads.static]</a></h5>
<pre><code>
unsigned hardware_concurrency();
@@ -982,7 +1019,7 @@
</dl>
</blockquote>
-<h5><a name="thread.threads.algorithm">30.1.1.7 <code>thread</code> specialized algorithms [thread.threads.algorithm]</a></h5>
+<h5><a name="thread.threads.algorithm">30.2.1.7 <code>thread</code> specialized algorithms [thread.threads.algorithm]</a></h5>
<pre><code>
void swap(thread& <var>x</var>, thread& <var>y</var>);
@@ -1001,7 +1038,7 @@
-<h4><a name="thread.threads.this">30.1.2 Namespace <code>this_thread</code> [thread.threads.this]</a></h4>
+<h4><a name="thread.threads.this">30.2.2 Namespace <code>this_thread</code> [thread.threads.this]</a></h4>
<blockquote>
<pre><code>
@@ -1108,7 +1145,14 @@
</dl>
</blockquote>
-<h3><a name="thread.mutex">30.2 Mutexs and locks [thread.mutex]</a></h3>
+<h3><a name="thread.mutex">30.3 Mutual Exclusion [thread.mutex]</a></h3>
+
+<p>
+This section provides mechanisms for mutual exclusion:
+mutexes, locks, and call once.
+These mechanisms ease the production of race-free programs
+[intro.multithread].
+</p>
<p>
<strong><mutex> synopsis</strong>
@@ -1158,7 +1202,7 @@
</code></pre>
</blockquote>
-<h4><a name="thread.mutex.concept">30.2.1 Mutex requirements [thread.mutex.requirements]</a></h4>
+<h4><a name="thread.mutex.concept">30.3.1 Mutex requirements [thread.mutex.requirements]</a></h4>
<p>
<a name="thread.mutex.concept">[thread.mutex.requirements]</a> describes
@@ -1166,7 +1210,6 @@
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.
@@ -1420,7 +1463,7 @@
</dl>
</blockquote>
-<h5><a name="thread.mutex.class">30.2.1.1 Class mutex [thread.mutex.class]</a></h5>
+<h5><a name="thread.mutex.class">30.3.1.1 Class mutex [thread.mutex.class]</a></h5>
<blockquote>
<pre><code>
@@ -1439,8 +1482,8 @@
bool try_lock();
void unlock();
- typedef <var><strong>implemenation-defined</strong></var> native_handle_type; // <em>See [frontmatter]</em>
- native_handle_type native_handle(); // <em>See [frontmatter]</em>
+ typedef <var><strong>implemenation-defined</strong></var> native_handle_type; // <em>See [thread.native]</em>
+ native_handle_type native_handle(); // <em>See [thread.native]</em>
};
} // std
@@ -1453,7 +1496,7 @@
It shall be a standard-layout class (chapter 9 [class]).
</p>
-<h5><a name="thread.mutex.recursive">30.2.1.2 Class recursive_mutex [thread.mutex.recursive]</a></h5>
+<h5><a name="thread.mutex.recursive">30.3.1.2 Class recursive_mutex [thread.mutex.recursive]</a></h5>
<blockquote>
<pre><code>
@@ -1472,8 +1515,8 @@
bool try_lock();
void unlock();
- typedef <var><strong>implemenation-defined</strong></var> native_handle_type; // <em>See [frontmatter]</em>
- native_handle_type native_handle(); // <em>See [frontmatter]</em>
+ typedef <var><strong>implemenation-defined</strong></var> native_handle_type; // <em>See [thread.native]</em>
+ native_handle_type native_handle(); // <em>See [thread.native]</em>
};
} // std
@@ -1486,7 +1529,7 @@
It shall be a standard-layout class (chapter 9 [class]).
</p>
-<h4><a name="thread.timed.concept">30.2.2 TimedMutex requirements [thread.timedmutex.requirements]</a></h4>
+<h4><a name="thread.timed.concept">30.3.2 TimedMutex requirements [thread.timedmutex.requirements]</a></h4>
<p>
To meet the TimedMutex requirements,
@@ -1590,7 +1633,7 @@
</dl>
</blockquote>
-<h5><a name="thread.timed.class">30.2.2.1 Class timed_mutex [thread.timed.class]</a></h5>
+<h5><a name="thread.timed.class">30.3.2.1 Class timed_mutex [thread.timed.class]</a></h5>
<blockquote>
<pre><code>
@@ -1612,8 +1655,8 @@
bool timed_lock(const system_time& abs_time);
void unlock();
- typedef <var><strong>implemenation-defined</strong></var> native_handle_type; // <em>See [frontmatter]</em>
- native_handle_type native_handle(); // <em>See [frontmatter]</em>
+ typedef <var><strong>implemenation-defined</strong></var> native_handle_type; // <em>See [thread.native]</em>
+ native_handle_type native_handle(); // <em>See [thread.native]</em>
};
} // std
@@ -1626,7 +1669,7 @@
It shall be a standard-layout class (chapter 9 [class]).
</p>
-<h5><a name="thread.timed.recursive">30.2.2.2 Class recursive_timed_mutex [thread.timed.recursive]</a></h5>
+<h5><a name="thread.timed.recursive">30.3.2.2 Class recursive_timed_mutex [thread.timed.recursive]</a></h5>
<blockquote>
<pre><code>
@@ -1648,8 +1691,8 @@
bool timed_lock(const system_time& abs_time);
void unlock();
- typedef <var><strong>implemenation-defined</strong></var> native_handle_type; // <em>See [frontmatter]</em>
- native_handle_type native_handle(); // <em>See [frontmatter]</em>
+ typedef <var><strong>implemenation-defined</strong></var> native_handle_type; // <em>See [thread.native]</em>
+ native_handle_type native_handle(); // <em>See [thread.native]</em>
};
} // std
@@ -1662,7 +1705,7 @@
It shall be a standard-layout class (chapter 9 [class]).
</p>
-<h4><a name="thread.lock.intro">30.2.3 Locks [thread.lock.intro]</a></h4>
+<h4><a name="thread.lock.intro">30.3.3 Locks [thread.lock.intro]</a></h4>
<p>
Locks are objects that hold a reference to a mutex
@@ -1717,7 +1760,7 @@
</code></pre>
</blockquote>
-<h5><a name="thread.lock.guard">30.2.3.1 Class lock_guard [thread.lock.guard]</a></h5>
+<h5><a name="thread.lock.guard">30.3.3.1 Class lock_guard [thread.lock.guard]</a></h5>
<blockquote>
<pre><code>
@@ -1805,7 +1848,7 @@
</dl>
</blockquote>
-<h5><a name="thread.lock.unique">30.2.3.2 Class unique_lock [thread.lock.unique]</a></h5>
+<h5><a name="thread.lock.unique">30.3.3.2 Class unique_lock [thread.lock.unique]</a></h5>
<blockquote>
<pre><code>
@@ -2399,7 +2442,7 @@
</dl>
</blockquote>
-<h4><a name="thread.lock.algorithm">30.2.4 Generic Locking Algorithms [thread.lock.algorithm]</a></h4>
+<h4><a name="thread.lock.algorithm">30.3.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>
@@ -2469,7 +2512,7 @@
</blockquote>
-<h4><a name="thread.mutex.once">30.2.5 Call Once [thread.mutex.once]</a></h4>
+<h4><a name="thread.mutex.once">30.3.5 Call Once [thread.mutex.once]</a></h4>
<p>
Objects of class <code>once_flag</code> are opaque data structures
@@ -2477,7 +2520,7 @@
without causing a data race or deadlock.
</p>
-<h5><a name="thread.mutex.onceflag">30.2.5.1 <code>struct once_flag</code> [thread.mutex.onceflag]</a></h5>
+<h5><a name="thread.mutex.onceflag">30.3.5.1 <code>struct once_flag</code> [thread.mutex.onceflag]</a></h5>
<pre><code>
constexpr once_flag();
@@ -2507,7 +2550,7 @@
</blockquote>
-<h5><a name="thread.threads.callonce">30.2.5.2 <code>non-member function call_once</code> [thread.threads.callonce]</a></h5>
+<h5><a name="thread.threads.callonce">30.3.5.2 <code>non-member function call_once</code> [thread.threads.callonce]</a></h5>
<pre><code>
template<class Callable, class Args...>
@@ -2615,7 +2658,7 @@
</blockquote>
-<h3><a name="thread.condition">30.3 Condition variables [thread.condition]</a></h3>
+<h3><a name="thread.condition">30.4 Condition variables [thread.condition]</a></h3>
<p>
Condition variables provide a mechanism to implement the monitor pattern.
@@ -2644,7 +2687,7 @@
</code></pre>
</blockquote>
-<h4><a name="thread.condvar">30.3.1 Class condition_variable [thread.condvar]</a></h4>
+<h4><a name="thread.condvar">30.4.1 Class condition_variable [thread.condvar]</a></h4>
<p>
An object of class <code>condition_variable</code>
@@ -2686,8 +2729,8 @@
template <class Duration, class Predicate>
bool timed_wait(unique_lock<mutex>& <var>lock</var>, const Duration& <var>rel_time</var>, Predicate <var>pred</var>);
- typedef <var><strong>implemenation-defined</strong></var> native_handle_type; // <em>See [frontmatter]</em>
- native_handle_type native_handle(); // <em>See [frontmatter]</em>
+ typedef <var><strong>implemenation-defined</strong></var> native_handle_type; // <em>See [thread.native]</em>
+ native_handle_type native_handle(); // <em>See [thread.native]</em>
};
} // std
@@ -3033,7 +3076,7 @@
shall be a standard-layout class (chapter 9 [class]).
</p>
-<h4><a name="thread.condvarany">30.3.2 Class condition_variable_any [thread.condvarany]</a></h4>
+<h4><a name="thread.condvarany">30.4.2 Class condition_variable_any [thread.condvarany]</a></h4>
<p>
An object of class <code>condition_variable_any</code>
@@ -3076,8 +3119,8 @@
template <class Lock, class Duration, class Predicate>
bool timed_wait(Lock& <var>lock</var>, const Duration& <var>rel_time</var>, Predicate <var>pred</var>);
- typedef <var><strong>implemenation-defined</strong></var> native_handle_type; // <em>See [frontmatter]</em>
- native_handle_type native_handle(); // <em>See [frontmatter]</em>
+ typedef <var><strong>implemenation-defined</strong></var> native_handle_type; // <em>See [thread.native]</em>
+ native_handle_type native_handle(); // <em>See [thread.native]</em>
};
} // std
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