|
|
Boost-Commit : |
From: anthony_at_[hidden]
Date: 2008-07-26 04:39:53
Author: anthonyw
Date: 2008-07-26 04:39:51 EDT (Sat, 26 Jul 2008)
New Revision: 47827
URL: http://svn.boost.org/trac/boost/changeset/47827
Log:
Merged thread doc changes from trunk
Text files modified:
branches/release/libs/thread/doc/condition_variables.qbk | 6 +
branches/release/libs/thread/doc/mutex_concepts.qbk | 195 ++++++++++++++++++++++++++++++++++++++++
branches/release/libs/thread/doc/mutexes.qbk | 20 +++
branches/release/libs/thread/doc/once.qbk | 4
branches/release/libs/thread/doc/overview.qbk | 8 +
branches/release/libs/thread/doc/shared_mutex_ref.qbk | 2
branches/release/libs/thread/doc/thread.qbk | 4
branches/release/libs/thread/doc/thread_ref.qbk | 57 +++++++++++
branches/release/libs/thread/doc/time.qbk | 4
branches/release/libs/thread/doc/tss.qbk | 2
10 files changed, 296 insertions(+), 6 deletions(-)
Modified: branches/release/libs/thread/doc/condition_variables.qbk
==============================================================================
--- branches/release/libs/thread/doc/condition_variables.qbk (original)
+++ branches/release/libs/thread/doc/condition_variables.qbk 2008-07-26 04:39:51 EDT (Sat, 26 Jul 2008)
@@ -74,6 +74,8 @@
[section:condition_variable Class `condition_variable`]
+ #include <boost/thread/condition_variable.hpp>
+
namespace boost
{
class condition_variable
@@ -294,6 +296,8 @@
[section:condition_variable_any Class `condition_variable_any`]
+ #include <boost/thread/condition_variable.hpp>
+
namespace boost
{
class condition_variable_any
@@ -498,6 +502,8 @@
[section:condition Typedef `condition`]
+ #include <boost/thread/condition.hpp>
+
typedef condition_variable_any condition;
The typedef `condition` is provided for backwards compatibility with previous boost releases.
Modified: branches/release/libs/thread/doc/mutex_concepts.qbk
==============================================================================
--- branches/release/libs/thread/doc/mutex_concepts.qbk (original)
+++ branches/release/libs/thread/doc/mutex_concepts.qbk 2008-07-26 04:39:51 EDT (Sat, 26 Jul 2008)
@@ -312,6 +312,8 @@
[section:lock_guard Class template `lock_guard`]
+ #include <boost/thread/locks.hpp>
+
template<typename Lockable>
class lock_guard
{
@@ -376,6 +378,8 @@
[section:unique_lock Class template `unique_lock`]
+ #include <boost/thread/locks.hpp>
+
template<typename Lockable>
class unique_lock
{
@@ -617,6 +621,8 @@
[section:shared_lock Class template `shared_lock`]
+ #include <boost/thread/locks.hpp>
+
template<typename Lockable>
class shared_lock
{
@@ -850,6 +856,8 @@
[section:upgrade_lock Class template `upgrade_lock`]
+ #include <boost/thread/locks.hpp>
+
template<typename Lockable>
class upgrade_lock
{
@@ -897,6 +905,8 @@
[section:upgrade_to_unique_lock Class template `upgrade_to_unique_lock`]
+ #include <boost/thread/locks.hpp>
+
template <class Lockable>
class upgrade_to_unique_lock
{
@@ -921,4 +931,189 @@
[endsect]
+[section:scoped_try_lock Mutex-specific class `scoped_try_lock`]
+
+ class MutexType::scoped_try_lock
+ {
+ private:
+ MutexType::scoped_try_lock(MutexType::scoped_try_lock<MutexType>& other);
+ MutexType::scoped_try_lock& operator=(MutexType::scoped_try_lock<MutexType>& other);
+ public:
+ MutexType::scoped_try_lock();
+ explicit MutexType::scoped_try_lock(MutexType& m);
+ MutexType::scoped_try_lock(MutexType& m_,adopt_lock_t);
+ MutexType::scoped_try_lock(MutexType& m_,defer_lock_t);
+ MutexType::scoped_try_lock(MutexType& m_,try_to_lock_t);
+
+ MutexType::scoped_try_lock(MutexType::scoped_try_lock<MutexType>&& other);
+ MutexType::scoped_try_lock& operator=(MutexType::scoped_try_lock<MutexType>&& other);
+
+ void swap(MutexType::scoped_try_lock&& other);
+
+ void lock();
+ bool try_lock();
+ void unlock();
+ bool owns_lock() const;
+
+ MutexType* mutex() const;
+ MutexType* release();
+ bool operator!() const;
+
+ typedef ``['unspecified-bool-type]`` bool_type;
+ operator bool_type() const;
+ };
+
+The member typedef `scoped_try_lock` is provided for each distinct
+`MutexType` as a typedef to a class with the preceding definition. The
+semantics of each constructor and member function are identical to
+those of [unique_lock_link `boost::unique_lock<MutexType>`] for the same `MutexType`, except
+that the constructor that takes a single reference to a mutex will
+call [try_lock_ref_link `m.try_lock()`] rather than `m.lock()`.
+
+
+[endsect]
+
+[endsect]
+
+[section:lock_functions Lock functions]
+
+[section:lock_multiple Non-member function `lock(Lockable1,Lockable2,...)`]
+
+ template<typename Lockable1,typename Lockable2>
+ void lock(Lockable1& l1,Lockable2& l2);
+
+ template<typename Lockable1,typename Lockable2,typename Lockable3>
+ void lock(Lockable1& l1,Lockable2& l2,Lockable3& l3);
+
+ template<typename Lockable1,typename Lockable2,typename Lockable3,typename Lockable4>
+ void lock(Lockable1& l1,Lockable2& l2,Lockable3& l3,Lockable4& l4);
+
+ template<typename Lockable1,typename Lockable2,typename Lockable3,typename Lockable4,typename Lockable5>
+ void lock(Lockable1& l1,Lockable2& l2,Lockable3& l3,Lockable4& l4,Lockable5& l5);
+
+[variablelist
+
+[[Effects:] [Locks the __lockable_concept_type__ objects supplied as
+arguments in an unspecified and indeterminate order in a way that
+avoids deadlock. It is safe to call this function concurrently from
+multiple threads with the same mutexes (or other lockable objects) in
+different orders without risk of deadlock. If any of the __lock_ref__
+or __try_lock_ref__ operations on the supplied
+__lockable_concept_type__ objects throws an exception any locks
+acquired by the function will be released before the function exits.]]
+
+[[Throws:] [Any exceptions thrown by calling __lock_ref__ or
+__try_lock_ref__ on the supplied __lockable_concept_type__ objects.]]
+
+[[Postcondition:] [All the supplied __lockable_concept_type__ objects
+are locked by the calling thread.]]
+
+]
+
+[endsect]
+
+[section:lock_range Non-member function `lock(begin,end)`]
+
+ template<typename ForwardIterator>
+ void lock(ForwardIterator begin,ForwardIterator end);
+
+[variablelist
+
+[[Preconditions:] [The `value_type` of `ForwardIterator` must implement the __lockable_concept__]]
+
+[[Effects:] [Locks all the __lockable_concept_type__ objects in the
+supplied range in an unspecified and indeterminate order in a way that
+avoids deadlock. It is safe to call this function concurrently from
+multiple threads with the same mutexes (or other lockable objects) in
+different orders without risk of deadlock. If any of the __lock_ref__
+or __try_lock_ref__ operations on the __lockable_concept_type__
+objects in the supplied range throws an exception any locks acquired
+by the function will be released before the function exits.]]
+
+[[Throws:] [Any exceptions thrown by calling __lock_ref__ or
+__try_lock_ref__ on the supplied __lockable_concept_type__ objects.]]
+
+[[Postcondition:] [All the __lockable_concept_type__ objects in the
+supplied range are locked by the calling thread.]]
+
+]
+
+[endsect]
+
+[section:try_lock_multiple Non-member function `try_lock(Lockable1,Lockable2,...)`]
+
+ template<typename Lockable1,typename Lockable2>
+ int try_lock(Lockable1& l1,Lockable2& l2);
+
+ template<typename Lockable1,typename Lockable2,typename Lockable3>
+ int try_lock(Lockable1& l1,Lockable2& l2,Lockable3& l3);
+
+ template<typename Lockable1,typename Lockable2,typename Lockable3,typename Lockable4>
+ int try_lock(Lockable1& l1,Lockable2& l2,Lockable3& l3,Lockable4& l4);
+
+ template<typename Lockable1,typename Lockable2,typename Lockable3,typename Lockable4,typename Lockable5>
+ int try_lock(Lockable1& l1,Lockable2& l2,Lockable3& l3,Lockable4& l4,Lockable5& l5);
+
+[variablelist
+
+[[Effects:] [Calls __try_lock_ref__ on each of the
+__lockable_concept_type__ objects supplied as arguments. If any of the
+calls to __try_lock_ref__ returns `false` then all locks acquired are
+released and the zero-based index of the failed lock is returned.
+
+If any of the __try_lock_ref__ operations on the supplied
+__lockable_concept_type__ objects throws an exception any locks
+acquired by the function will be released before the function exits.]]
+
+[[Returns:] [`-1` if all the supplied __lockable_concept_type__ objects
+are now locked by the calling thread, the zero-based index of the
+object which could not be locked otherwise.]]
+
+[[Throws:] [Any exceptions thrown by calling __try_lock_ref__ on the
+supplied __lockable_concept_type__ objects.]]
+
+[[Postcondition:] [If the function returns `-1`, all the supplied
+__lockable_concept_type__ objects are locked by the calling
+thread. Otherwise any locks acquired by this function will have been
+released.]]
+
+]
+
+[endsect]
+
+[section:try_lock_range Non-member function `try_lock(begin,end)`]
+
+ template<typename ForwardIterator>
+ ForwardIterator try_lock(ForwardIterator begin,ForwardIterator end);
+
+[variablelist
+
+[[Preconditions:] [The `value_type` of `ForwardIterator` must implement the __lockable_concept__]]
+
+[[Effects:] [Calls __try_lock_ref__ on each of the
+__lockable_concept_type__ objects in the supplied range. If any of the
+calls to __try_lock_ref__ returns `false` then all locks acquired are
+released and an iterator referencing the failed lock is returned.
+
+If any of the __try_lock_ref__ operations on the supplied
+__lockable_concept_type__ objects throws an exception any locks
+acquired by the function will be released before the function exits.]]
+
+[[Returns:] [`end` if all the supplied __lockable_concept_type__
+objects are now locked by the calling thread, an iterator referencing
+the object which could not be locked otherwise.]]
+
+[[Throws:] [Any exceptions thrown by calling __try_lock_ref__ on the
+supplied __lockable_concept_type__ objects.]]
+
+[[Postcondition:] [If the function returns `end` then all the
+__lockable_concept_type__ objects in the supplied range are locked by
+the calling thread, otherwise all locks acquired by the function have
+been released.]]
+
+]
+
+[endsect]
+
+
[endsect]
Modified: branches/release/libs/thread/doc/mutexes.qbk
==============================================================================
--- branches/release/libs/thread/doc/mutexes.qbk (original)
+++ branches/release/libs/thread/doc/mutexes.qbk 2008-07-26 04:39:51 EDT (Sat, 26 Jul 2008)
@@ -9,6 +9,8 @@
[section:mutex Class `mutex`]
+ #include <boost/thread/mutex.hpp>
+
class mutex:
boost::noncopyable
{
@@ -24,7 +26,7 @@
native_handle_type native_handle();
typedef unique_lock<mutex> scoped_lock;
- typedef scoped_lock scoped_try_lock;
+ typedef unspecified-type scoped_try_lock;
};
__mutex__ implements the __lockable_concept__ to provide an exclusive-ownership mutex. At most one thread can own the lock on a given
@@ -51,6 +53,8 @@
[section:try_mutex Typedef `try_mutex`]
+ #include <boost/thread/mutex.hpp>
+
typedef mutex try_mutex;
__try_mutex__ is a `typedef` to __mutex__, provided for backwards compatibility with previous releases of boost.
@@ -59,6 +63,8 @@
[section:timed_mutex Class `timed_mutex`]
+ #include <boost/thread/mutex.hpp>
+
class timed_mutex:
boost::noncopyable
{
@@ -78,7 +84,7 @@
native_handle_type native_handle();
typedef unique_lock<timed_mutex> scoped_timed_lock;
- typedef scoped_timed_lock scoped_try_lock;
+ typedef unspecified-type scoped_try_lock;
typedef scoped_timed_lock scoped_lock;
};
@@ -106,6 +112,8 @@
[section:recursive_mutex Class `recursive_mutex`]
+ #include <boost/thread/recursive_mutex.hpp>
+
class recursive_mutex:
boost::noncopyable
{
@@ -121,7 +129,7 @@
native_handle_type native_handle();
typedef unique_lock<recursive_mutex> scoped_lock;
- typedef scoped_lock scoped_try_lock;
+ typedef unspecified-type scoped_try_lock;
};
__recursive_mutex__ implements the __lockable_concept__ to provide an exclusive-ownership recursive mutex. At most one thread can
@@ -150,6 +158,8 @@
[section:recursive_try_mutex Typedef `recursive_try_mutex`]
+ #include <boost/thread/recursive_mutex.hpp>
+
typedef recursive_mutex recursive_try_mutex;
__recursive_try_mutex__ is a `typedef` to __recursive_mutex__, provided for backwards compatibility with previous releases of boost.
@@ -158,6 +168,8 @@
[section:recursive_timed_mutex Class `recursive_timed_mutex`]
+ #include <boost/thread/recursive_mutex.hpp>
+
class recursive_timed_mutex:
boost::noncopyable
{
@@ -178,7 +190,7 @@
native_handle_type native_handle();
typedef unique_lock<recursive_timed_mutex> scoped_lock;
- typedef scoped_lock scoped_try_lock;
+ typedef unspecified-type scoped_try_lock;
typedef scoped_lock scoped_timed_lock;
};
Modified: branches/release/libs/thread/doc/once.qbk
==============================================================================
--- branches/release/libs/thread/doc/once.qbk (original)
+++ branches/release/libs/thread/doc/once.qbk 2008-07-26 04:39:51 EDT (Sat, 26 Jul 2008)
@@ -11,6 +11,8 @@
[section:once_flag Typedef `once_flag`]
+ #include <boost/thread/once.hpp>
+
typedef platform-specific-type once_flag;
#define BOOST_ONCE_INIT platform-specific-initializer
@@ -22,6 +24,8 @@
[section:call_once Non-member function `call_once`]
+ #include <boost/thread/once.hpp>
+
template<typename Callable>
void call_once(once_flag& flag,Callable func);
Modified: branches/release/libs/thread/doc/overview.qbk
==============================================================================
--- branches/release/libs/thread/doc/overview.qbk (original)
+++ branches/release/libs/thread/doc/overview.qbk 2008-07-26 04:39:51 EDT (Sat, 26 Jul 2008)
@@ -19,4 +19,12 @@
[@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2006/n2139.html N2139], and
[@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2006/n2094.html N2094]
+In order to use the classes and functions described here, you can
+either include the specific headers specified by the descriptions of
+each class or function, or include the master thread library header:
+
+ #include <boost/thread.hpp>
+
+which includes all the other headers in turn.
+
[endsect]
Modified: branches/release/libs/thread/doc/shared_mutex_ref.qbk
==============================================================================
--- branches/release/libs/thread/doc/shared_mutex_ref.qbk (original)
+++ branches/release/libs/thread/doc/shared_mutex_ref.qbk 2008-07-26 04:39:51 EDT (Sat, 26 Jul 2008)
@@ -7,6 +7,8 @@
[section:shared_mutex Class `shared_mutex`]
+ #include <boost/thread/shared_mutex.hpp>
+
class shared_mutex
{
public:
Modified: branches/release/libs/thread/doc/thread.qbk
==============================================================================
--- branches/release/libs/thread/doc/thread.qbk (original)
+++ branches/release/libs/thread/doc/thread.qbk 2008-07-26 04:39:51 EDT (Sat, 26 Jul 2008)
@@ -101,8 +101,10 @@
[def __recursive_timed_mutex__ [link thread.synchronization.mutex_types.recursive_timed_mutex `boost::recursive_timed_mutex`]]
[def __shared_mutex__ [link thread.synchronization.mutex_types.shared_mutex `boost::shared_mutex`]]
+[template unique_lock_link[link_text] [link thread.synchronization.locks.unique_lock [link_text]]]
+
[def __lock_guard__ [link thread.synchronization.locks.lock_guard `boost::lock_guard`]]
-[def __unique_lock__ [link thread.synchronization.locks.unique_lock `boost::unique_lock`]]
+[def __unique_lock__ [unique_lock_link `boost::unique_lock`]]
[def __shared_lock__ [link thread.synchronization.locks.shared_lock `boost::shared_lock`]]
[def __upgrade_lock__ [link thread.synchronization.locks.upgrade_lock `boost::upgrade_lock`]]
[def __upgrade_to_unique_lock__ [link thread.synchronization.locks.upgrade_to_unique_lock `boost::upgrade_to_unique_lock`]]
Modified: branches/release/libs/thread/doc/thread_ref.qbk
==============================================================================
--- branches/release/libs/thread/doc/thread_ref.qbk (original)
+++ branches/release/libs/thread/doc/thread_ref.qbk 2008-07-26 04:39:51 EDT (Sat, 26 Jul 2008)
@@ -165,6 +165,8 @@
[section:thread Class `thread`]
+ #include <boost/thread/thread.hpp>
+
class thread
{
public:
@@ -174,6 +176,9 @@
template <class F>
explicit thread(F f);
+ template <class F,class A1,class A2,...>
+ thread(F f,A1 a1,A2 a2,...);
+
template <class F>
thread(detail::thread_move_t<F> f);
@@ -250,6 +255,30 @@
[endsect]
+[section:multiple_argument_constructor Thread Constructor with arguments]
+
+ template <class F,class A1,class A2,...>
+ thread(F f,A1 a1,A2 a2,...);
+
+[variablelist
+
+[[Preconditions:] [`F` and each `A`n must by copyable or movable.]]
+
+[[Effects:] [As if [link
+thread.thread_management.thread.callable_constructor
+`thread(boost::bind(f,a1,a2,...))`. Consequently, `f` and each `a`n
+are copied into internal storage for access by the new thread.]]]
+
+[[Postconditions:] [`*this` refers to the newly created thread of execution.]]
+
+[[Throws:] [__thread_resource_error__ if an error occurs.]]
+
+[[Note:] [Currently up to nine additional arguments `a1` to `a9` can be specified in addition to the function `f`.]]
+
+]
+
+[endsect]
+
[section:destructor Thread Destructor]
~thread();
@@ -480,6 +509,8 @@
[section:non_member_swap Non-member function `swap()`]
+ #include <boost/thread/thread.hpp>
+
void swap(thread& lhs,thread& rhs);
[variablelist
@@ -493,6 +524,8 @@
[section:id Class `boost::thread::id`]
+ #include <boost/thread/thread.hpp>
+
class thread::id
{
public:
@@ -641,6 +674,8 @@
[section:get_id Non-member function `get_id()`]
+ #include <boost/thread/thread.hpp>
+
namespace this_thread
{
thread::id get_id();
@@ -658,6 +693,8 @@
[section:interruption_point Non-member function `interruption_point()`]
+ #include <boost/thread/thread.hpp>
+
namespace this_thread
{
void interruption_point();
@@ -675,6 +712,8 @@
[section:interruption_requested Non-member function `interruption_requested()`]
+ #include <boost/thread/thread.hpp>
+
namespace this_thread
{
bool interruption_requested();
@@ -692,6 +731,8 @@
[section:interruption_enabled Non-member function `interruption_enabled()`]
+ #include <boost/thread/thread.hpp>
+
namespace this_thread
{
bool interruption_enabled();
@@ -709,6 +750,8 @@
[section:sleep Non-member function `sleep()`]
+ #include <boost/thread/thread.hpp>
+
namespace this_thread
{
template<typename TimeDuration>
@@ -729,6 +772,8 @@
[section:yield Non-member function `yield()`]
+ #include <boost/thread/thread.hpp>
+
namespace this_thread
{
void yield();
@@ -746,6 +791,8 @@
[section:disable_interruption Class `disable_interruption`]
+ #include <boost/thread/thread.hpp>
+
namespace this_thread
{
class disable_interruption
@@ -797,6 +844,8 @@
[section:restore_interruption Class `restore_interruption`]
+ #include <boost/thread/thread.hpp>
+
namespace this_thread
{
class restore_interruption
@@ -851,12 +900,16 @@
[section:atthreadexit Non-member function template `at_thread_exit()`]
+ #include <boost/thread/thread.hpp>
+
template<typename Callable>
void at_thread_exit(Callable func);
[variablelist
-[[Effects:] [A copy of `func` is taken and stored to in thread-specific storage. This copy is invoked when the current thread exits.]]
+[[Effects:] [A copy of `func` is placed in
+thread-specific storage. This copy is invoked when the current thread
+exits (even if the thread has been interrupted).]]
[[Postconditions:] [A copy of `func` has been saved for invocation on thread exit.]]
@@ -871,6 +924,8 @@
[section:threadgroup Class `thread_group`]
+ #include <boost/thread/thread.hpp>
+
class thread_group:
private noncopyable
{
Modified: branches/release/libs/thread/doc/time.qbk
==============================================================================
--- branches/release/libs/thread/doc/time.qbk (original)
+++ branches/release/libs/thread/doc/time.qbk 2008-07-26 04:39:51 EDT (Sat, 26 Jul 2008)
@@ -47,6 +47,8 @@
[section:system_time Typedef `system_time`]
+ #include <boost/thread/thread_time.hpp>
+
typedef boost::posix_time::ptime system_time;
See the documentation for [link date_time.posix_time.ptime_class `boost::posix_time::ptime`] in the Boost.Date_Time library.
@@ -55,6 +57,8 @@
[section:get_system_time Non-member function `get_system_time()`]
+ #include <boost/thread/thread_time.hpp>
+
system_time get_system_time();
[variablelist
Modified: branches/release/libs/thread/doc/tss.qbk
==============================================================================
--- branches/release/libs/thread/doc/tss.qbk (original)
+++ branches/release/libs/thread/doc/tss.qbk 2008-07-26 04:39:51 EDT (Sat, 26 Jul 2008)
@@ -44,6 +44,8 @@
[section:thread_specific_ptr Class `thread_specific_ptr`]
+ #include <boost/thread/tss.hpp>
+
template <typename T>
class thread_specific_ptr
{
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