|
|
Boost-Commit : |
From: bdawes_at_[hidden]
Date: 2007-10-08 13:52:03
Author: bemandawes
Date: 2007-10-08 13:52:03 EDT (Mon, 08 Oct 2007)
New Revision: 39802
URL: http://svn.boost.org/trac/boost/changeset/39802
Log:
thread7cv - condition variable cleanup
Text files modified:
sandbox/committee/LWG/thread_library.html | 219 +++++++++++++++++++--------------------
1 files changed, 109 insertions(+), 110 deletions(-)
Modified: sandbox/committee/LWG/thread_library.html
==============================================================================
--- sandbox/committee/LWG/thread_library.html (original)
+++ sandbox/committee/LWG/thread_library.html 2007-10-08 13:52:03 EDT (Mon, 08 Oct 2007)
@@ -1666,45 +1666,51 @@
<h3><a name="ConditionVariablesWording">Condition variables</a></h3>
-<b><<span class="remove">cond_var</span><span class="insert">condition_variable</span>> synopsis</b>
+<b><condition_variable> synopsis</b>
<blockquote><pre>namespace std {
-class <span class="remove">cond_var</span><span
- class="insert">condition_variable</span>;
-class <span class="remove">gen_cond_var</span><span
-class="insert">general_condition_variable</span>;
+class condition_variable;
+class condition_variable_any;
} // std
</pre></blockquote>
-<h4>Class <span class="remove">cond_var</span><span
- class="insert">condition_variable</span></h4>
+<h4>Class condition_variable</h4>
<p>
-An object of class <tt><span class="remove">cond_var</span><span
- class="insert">condition_variable</span></tt> is a synchronization primitive
+An object of class <tt>condition_variable</tt> is a synchronization primitive
used to cause a thread of execution to wait until notified by some other
thread of execution that some condition is met, or a UTC[(?)] time is reached.
</p>
+<p>
+If and only if the condition variable type is internally represented by an object
+which can be passed to operating system specific interfaces, then there shall be a
+implementation-defined member typedef <tt>native_handle_type</tt> that is an alias
+to this native type, if it is copyable, or if the native type is not copyable,
+a pointer to this native type. The implementation shall document whether the
+<tt>native_handle_type</tt> member typedef is present.
+</p>
+
+<p>
+If the nested typedef <tt>native_handle_type</tt> exists, then there
+also shall be a member function <tt>native_handle()</tt> which returns the
+underlying representation.
+</p>
+
<blockquote><pre>namespace std {
-class <span class="remove">cond_var</span><span
- class="insert">condition_variable</span>
+class condition_variable
{
public:
- <span class="remove">cond_var</span><span
- class="insert">condition_variable</span>();
- ~<span class="remove">cond_var</span><span
- class="insert">condition_variable</span>();
-
- <span class="remove">cond_var</span><span
- class="insert">condition_variable</span>(const <span class="remove">cond_var</span><span
- class="insert">condition_variable</span>&) = delete;
- <span class="remove">cond_var</span><span
- class="insert">condition_variable</span>& operator=(const <span class="remove">cond_var</span><span
- class="insert">condition_variable</span>&) = delete;
+ typedef <i>implementation-defined</i> native_handle_type;
+
+ condition_variable();
+ ~condition_variable();
+
+ condition_variable(const condition_variable&) = delete;
+ condition_variable& operator=(const condition_variable&) = delete;
void notify_one();
void notify_all();
@@ -1714,26 +1720,24 @@
bool timed_wait(unique_lock<mutex>& lock, const utc_time& abs_time);
template <class Predicate>
bool timed_wait(unique_lock<mutex>& lock, const utc_time& abs_time, Predicate pred);
+ native_handle_type native_handle();
};
} // std
</pre></blockquote>
<blockquote>
-<pre><span class="remove">cond_var</span><span
- class="insert">condition_variable</span>();
+<pre>condition_variable();
</pre>
<blockquote>
<p>
-<i>Effects:</i> Constructs an object of class <tt><span class="remove">cond_var</span><span
- class="insert">condition_variable</span></tt>.
+<i>Effects:</i> Constructs an object of class <tt>condition_variable</tt>.
</p>
</blockquote>
</blockquote>
<blockquote>
-<pre>~<span class="remove">cond_var</span><span
- class="insert">condition_variable</span>();
+<pre>~condition_variable();
</pre>
<blockquote>
<p>
@@ -1751,12 +1755,11 @@
<blockquote>
<p>
<i>Effects:</i> If any threads of execution are blocked waiting for <code>*this</code>,
-unblocks at least one those threads<span class="insert"> of execution</span>.</p>
+unblocks at least one those threads of execution.</p>
<p>
<i>Thread safety:</i> Calls to the <code>wait</code>,
<code>timed_wait</code>, <code>notify_one</code> or
-<code>notify_all</code> member functions of the same <tt>condition<span
-class="insert">_variable</span></tt>
+<code>notify_all</code> member functions of the same <tt>condition_variable</tt>
object from different threads of execution shall not result in data
races or deadlocks.
</p>
@@ -1768,13 +1771,12 @@
</pre>
<blockquote>
<p>
-<i>Effects:</i> Unblock all threads<span class="insert"> of execution</span> that are blocked waiting for <code>*this</code>.
+<i>Effects:</i> Unblock all threads of execution that are blocked waiting for <code>*this</code>.
</p>
<p>
<i>Thread safety:</i> Calls to the <code>wait</code>,
<code>timed_wait</code>, <code>notify_one</code> or
-<code>notify_all</code> member functions of the same <tt>condition<span
-class="insert">_variable</span></tt>
+<code>notify_all</code> member functions of the same <tt>condition_variable</tt>
object from different threads of execution shall not result in data
races or deadlocks.
</p>
@@ -1787,19 +1789,15 @@
<blockquote>
<p>
<i>Precondition:</i> <tt>lock</tt> is locked by the current thread of execution. No
-other thread of execution is waiting on this <tt><span class="remove">cond_var</span><span
- class="insert">condition_variable</span></tt> object unless <tt>lock</tt>
+other thread of execution is waiting on this <tt>condition_variable</tt> object unless <tt>lock</tt>
refers to the same underlying <tt>mutex</tt> object.
</p>
<p>
<i>Effects:</i> Atomically blocks and releases the lock on
<tt>lock</tt>. If the <tt>wait</tt> should throw an exception for any
-reason, <tt>lock</tt> will be locked as the exception propagates<span
-class="remove"> out</span>.
-This thread of execution shall unblock when another thread<span class="insert">
-of execution</span> issues a
-notification to this blocked thread<span class="insert">
-of execution</span> . The current thread of execution may
+reason, <tt>lock</tt> will be locked as the exception propagates.
+This thread of execution shall unblock when another threadof execution issues a
+notification to this blocked thread of execution. The current thread of execution may
unblock and return even in the absence of a notification.
</p>
<p>
@@ -1811,8 +1809,7 @@
<p>
<i>Thread safety:</i> Calls to the <code>wait</code>,
<code>timed_wait</code>, <code>notify_one</code> or
-<code>notify_all</code> member functions of the same <tt>condition<span
-class="insert">_variable</span></tt>
+<code>notify_all</code> member functions of the same <tt>condition_variable</tt>
object from different threads of execution shall not result in data
races or deadlocks.
</p>
@@ -1840,8 +1837,7 @@
<blockquote>
<p>
<i>Precondition:</i> The <tt>lock</tt> is locked by the current thread of execution. No
-other thread of execution is waiting on this <tt><span class="remove">cond_var</span><span
- class="insert">condition_variable</span></tt> object unless <tt>lock</tt>
+other thread of execution is waiting on this <tt>condition_variable</tt> object unless <tt>lock</tt>
refers to, the same underlying <tt>mutex</tt> object.
</p>
<p>
@@ -1850,13 +1846,10 @@
any reason, <tt>lock</tt> will be locked as the exception propagates
out. If the absolute time specified by <tt>abs_time</tt> passes (that
is, system time equals or exceeds <tt>abs_time</tt>) before the
-<tt>condition<span
-class="insert">_variable</span></tt> is notified, or if the absolute time specified by
+<tt>condition_variable</tt> is notified, or if the absolute time specified by
<tt>abs_time</tt> has already been passed at the time of the call, then
<tt>false</tt> is returned. This thread of execution shall unblock when
-another thread<span class="insert">
-of execution</span> issues a notification to this blocked thread<span class="insert">
-of execution</span> . The current
+another thread of execution issues a notification to this blocked thread of execution . The current
thread of execution may unblock and return even in the absence of a
notification.
</p>
@@ -1874,15 +1867,14 @@
<p>
<i>Thread safety:</i> Calls to the <code>wait</code>,
<code>timed_wait</code>, <code>notify_one</code> or
-<code>notify_all</code> member functions of the same <tt>condition<span
-class="insert">_variable</span></tt>
+<code>notify_all</code> member functions of the same <tt>condition_variable</tt>
object from different threads of execution shall not result in data
races or deadlocks.
</blockquote>
</blockquote>
<blockquote>
-<pre>template <class <span class="remove">_</span>Predicate>
+<pre>template <class Predicate>
bool timed_wait(unique_lock<mutex>& lock, const utc_time& abs_time, Predicate pred);
</pre>
<blockquote>
@@ -1907,17 +1899,25 @@
</blockquote>
</blockquote>
+<blockquote>
+<pre>native_handle_type native_handle();
+</pre>
+<blockquote>
<p>
-<tt><span class="remove">cond_var</span><span
- class="insert">condition_variable</span></tt> shall be a standard-layout type ([?]).
+<i>Returns:</i> the representation of the underlying object used to implement <tt>*this</tt>.
</p>
+</blockquote>
+</blockquote>
-<h4>Class <span class="remove">gen_cond_var</span><span
-class="insert">general_condition_variable</span></h4>
<p>
-An object of class <tt><span class="remove">gen_cond_var</span><span
-class="insert">general_condition_variable</span></tt> is a synchronization primitive
+<tt>condition_variable</tt> shall be a standard-layout type ([?]).
+</p>
+
+<h4>Class condition_variable_any</h4>
+
+<p>
+An object of class <tt>condition_variable_any</tt> is a synchronization primitive
used to cause a thread of execution to wait until notified by some other
thread of execution that some condition is met, or a UTC[(?)] time is reached.
</p>
@@ -1928,23 +1928,33 @@
meet this requirement.
</p>
+<p>
+If and only if the <tt>condition_variable_any</tt> type is internally represented by an
+an object or objects which can be passed to operating system specific interfaces, then
+there shall be a nested implementation-defined typedef <tt>native_handle_type</tt> that
+is an alias to a type providing access to the object or objects. The type
+<tt>native_handle_type</tt> must be copyable; if the object or objects are not copyable,
+<tt>native_handle_type</tt> must be a pointer type. The implementation shall document
+whether the <tt>native_handle_type</tt> typedef is present.
+</p>
+
+<p>
+If the nested typedef <tt>native_handle_type</tt> exists, then there
+also shall be a member function <tt>native_handle()</tt> which returns the
+underlying representation.
+</p>
+
<blockquote><pre>namespace std {
-class <span class="remove">gen_cond_var</span><span
-class="insert">general_condition_variable</span>
+class condition_variable_any
{
public:
- <span class="remove">gen_cond_var</span><span
-class="insert">general_condition_variable</span>();
- ~<span class="remove">gen_cond_var</span><span
-class="insert">general_condition_variable</span>();
-
- <span class="remove">gen_cond_var</span><span
-class="insert">general_condition_variable</span>(const <span class="remove">gen_cond_var</span><span
-class="insert">general_condition_variable</span>&) = delete;
- <span class="remove">gen_cond_var</span><span
-class="insert">general_condition_variable</span>& operator=(const <span class="remove">gen_cond_var</span><span
-class="insert">general_condition_variable</span>&) = delete;
+ typedef <i>implementation-defined</i> native_handle_type;
+ condition_variable_any();
+ ~condition_variable_any();
+
+ condition_variable_any(const condition_variable_any&) = delete;
+ condition_variable_any& operator=(const condition_variable_any&) = delete;
void notify_one();
void notify_all();
@@ -1956,26 +1966,24 @@
bool timed_wait(Lock& lock, const utc_time& abs_time);
template <class Lock, class Predicate>
bool timed_wait(Lock& lock, const utc_time& abs_time, Predicate pred);
+ native_handle_type native_handle();
};
} // std
</pre></blockquote>
<blockquote>
-<pre><span class="remove">gen_cond_var</span><span
-class="insert">general_condition_variable</span>();
+<pre>condition_variable_any();
</pre>
<blockquote>
<p>
-<i>Effects:</i> Constructs an object of class <tt><span class="remove">gen_cond_var</span><span
-class="insert">general_condition_variable</span></tt>.
+<i>Effects:</i> Constructs an object of class <tt>condition_variable_any</tt>.
</p>
</blockquote>
</blockquote>
<blockquote>
-<pre>~<span class="remove">gen_cond_var</span><span
-class="insert">general_condition_variable</span>();
+<pre>~condition_variable_any();
</pre>
<blockquote>
<p>
@@ -1993,13 +2001,11 @@
<blockquote>
<p>
<i>Effects:</i> If any threads of execution are blocked waiting for <code>*this</code>,
-unblocks at least one those threads<span class="insert"> of execution</span>.</p>
+unblocks at least one those threads of execution.</p>
<p>
<i>Thread safety:</i> Calls to the <code>wait</code>,
<code>timed_wait</code>, <code>notify_one</code> or
-<code>notify_all</code> member functions of the same <tt><span
-class="insert">general_</span>condition<span
-class="insert">_variable</span></tt>
+<code>notify_all</code> member functions of the same <tt>condition_variable_any</tt>
object from different threads of execution shall not result in data
races or deadlocks.
</p>
@@ -2011,15 +2017,12 @@
</pre>
<blockquote>
<p>
-<i>Effects:</i> Unblock all threads <span class="insert">
-of execution</span>that are blocked waiting for <code>*this</code>.
+<i>Effects:</i> Unblock all threads of execution that are blocked waiting for <code>*this</code>.
</p>
<p>
<i>Thread safety:</i> Calls to the <code>wait</code>,
<code>timed_wait</code>, <code>notify_one</code> or
-<code>notify_all</code> member functions of the same <tt><span
-class="insert">general_</span>condition<span
-class="insert">_variable</span></tt>
+<code>notify_all</code> member functions of the same <tt>condition_variable_any</tt>
object from different threads of execution shall not result in data
races or deadlocks.
</p>
@@ -2033,19 +2036,15 @@
<p>
<i>Precondition:</i> <tt>lock</tt> is locked by the current thread of execution. If
<tt>Lock</tt> supports recursive locking, the lock count is one. No
-other thread of execution is waiting on this <tt><span class="remove">gen_cond_var</span><span
-class="insert">general_condition_variable</span></tt> object unless <tt>lock</tt>
+other thread of execution is waiting on this <tt>condition_variable_any</tt> object unless <tt>lock</tt>
is, or refers to, the same underlying mutex object.
</p>
<p>
<i>Effects:</i> Atomically blocks and releases the lock on
<tt>lock</tt>. If the <tt>wait</tt> should throw an exception for any
-reason, <tt>lock</tt> will be locked as the exception propagates<span
-name="remove"> out</span>.
-This thread of execution shall unblock when another thread<span class="insert">
-of execution</span> issues a
-notification to this blocked thread<span class="insert">
-of execution</span>. The current thread of execution may
+reason, <tt>lock</tt> will be locked as the exception propagates.
+This thread of execution shall unblock when another thread of execution issues a
+notification to this blocked thread of execution. The current thread of execution may
unblock and return even in the absence of a notification.
</p>
<p>
@@ -2057,9 +2056,7 @@
<p>
<i>Thread safety:</i> Calls to the <code>wait</code>,
<code>timed_wait</code>, <code>notify_one</code> or
-<code>notify_all</code> member functions of the same <tt><span
-class="insert">general_</span>condition<span
-class="insert">_variable</span></tt>
+<code>notify_all</code> member functions of the same <tt>condition_variable_any</tt>
object from different threads of execution shall not result in data
races or deadlocks.
</p>
@@ -2088,8 +2085,7 @@
<p>
<i>Precondition:</i> The <tt>lock</tt> is locked by the current thread of execution. If
<tt>Lock</tt> supports recursive locking, the lock count is one. No
-other thread of execution is waiting on this <tt><span class="remove">gen_cond_var</span><span
-class="insert">general_condition_variable</span></tt> object unless <tt>lock</tt>
+other thread of execution is waiting on this <tt>condition_variable_any</tt> object unless <tt>lock</tt>
is, or refers to, the same underlying mutex object.
</p>
<p>
@@ -2098,14 +2094,10 @@
any reason, <tt>lock</tt> will be locked as the exception propagates
out. If the absolute time specified by <tt>abs_time</tt> passes (that
is, system time equals or exceeds <tt>abs_time</tt>) before the
-<tt><span
-class="insert">general_</span>condition<span
-class="insert">_variable</span></tt> is notified, or if the absolute time specified by
+<tt>condition_variable_any</tt> is notified, or if the absolute time specified by
<tt>abs_time</tt> has already been passed at the time of the call, then
<tt>false</tt> is returned. This thread of execution shall unblock when
-another thread<span class="insert">
-of execution</span> issues a notification to this blocked thread<span class="insert">
-of execution</span>. The current
+another thread of execution issues a notification to this blocked thread of execution. The current
thread of execution may unblock and return even in the absence of a
notification.
</p>
@@ -2123,9 +2115,7 @@
<p>
<i>Thread safety:</i> Calls to the <code>wait</code>,
<code>timed_wait</code>, <code>notify_one</code> or
-<code>notify_all</code> member functions of the same <tt><span
-class="insert">general_</span>condition<span
-class="insert">_variable</span></tt>
+<code>notify_all</code> member functions of the same <tt>condition_variable_any</tt>
object from different threads of execution shall not result in data
races or deadlocks.
</blockquote>
@@ -2157,6 +2147,15 @@
</blockquote>
</blockquote>
+<blockquote>
+<pre>native_handle_type native_handle();
+</pre>
+<blockquote>
+<p>
+<i>Returns:</i> the representation of the underlying object or objects used to implement <tt>*this</tt>.
+</p>
+</blockquote>
+</blockquote>
<hr/>
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