Boost logo

Boost-Commit :

Subject: [Boost-commit] svn:boost r80446 - trunk/libs/thread/doc
From: vicente.botet_at_[hidden]
Date: 2012-09-08 10:12:06


Author: viboes
Date: 2012-09-08 10:12:05 EDT (Sat, 08 Sep 2012)
New Revision: 80446
URL: http://svn.boost.org/trac/boost/changeset/80446

Log:
Thread: update doc with async and notify_all_at_thread_exit referece doc
Text files modified:
   trunk/libs/thread/doc/changes.qbk | 6
   trunk/libs/thread/doc/condition_variables.qbk | 48 ++++
   trunk/libs/thread/doc/future_ref.qbk | 429 ++++++++++++++++++++++++++-------------
   trunk/libs/thread/doc/futures.qbk | 9
   trunk/libs/thread/doc/mutex_concepts.qbk | 38 ++
   trunk/libs/thread/doc/mutexes.qbk | 4
   trunk/libs/thread/doc/tss.qbk | 5
   7 files changed, 369 insertions(+), 170 deletions(-)

Modified: trunk/libs/thread/doc/changes.qbk
==============================================================================
--- trunk/libs/thread/doc/changes.qbk (original)
+++ trunk/libs/thread/doc/changes.qbk 2012-09-08 10:12:05 EDT (Sat, 08 Sep 2012)
@@ -14,6 +14,8 @@
 
 * [@http://svn.boost.org/trac/boost/ticket/2361 #2361] thread_specific_ptr: document nature of the key, complexity and rationale
 * [@http://svn.boost.org/trac/boost/ticket/4710 #4710] C++11 compliance: : Missing async()
+* [@http://svn.boost.org/trac/boost/ticket/7283 #7283] C++11 compliance: Add notify_all_at_thread_exit
+* [@http://svn.boost.org/trac/boost/ticket/7345 #7345] C++11 compliance: Add noexcept to recursive mutex try_lock
 
 Fixed Bugs:
 
@@ -29,6 +31,8 @@
 * [@http://svn.boost.org/trac/boost/ticket/7238 #5274] this_thread::sleep_for() does not respond to interrupt()
 * [@http://svn.boost.org/trac/boost/ticket/7245 #7245] Minor typos on documentation related to version 3
 * [@http://svn.boost.org/trac/boost/ticket/7272 #7272] win32/thread_primitives.hpp: (Unneccessary) Warning
+* [@http://svn.boost.org/trac/boost/ticket/7284 #7284] Clarify that there is no access priority between lock and shared_lock on shared mutex
+* [@http://svn.boost.org/trac/boost/ticket/7329 #7329] boost/thread/future.hpp does not compile on HPUX
 
 [heading Version 3.0.1 - boost 1.51]
 
@@ -248,7 +252,7 @@
 
 # Complete the C++11 missing features, in particular
 
- * [@http://svn.boost.org/trac/boost/ticket/4710 #4710] Missing async().
+ * async with deferred and variadic rvalue reference args.
   * [@http://svn.boost.org/trac/boost/ticket/6227 #6227] Use of variadic templates on Generic Locking Algorithms on compilers providing them.
   * [@http://svn.boost.org/trac/boost/ticket/6270 #6270] Add thread constructor from movable callable and movable arguments following C++11.
          

Modified: trunk/libs/thread/doc/condition_variables.qbk
==============================================================================
--- trunk/libs/thread/doc/condition_variables.qbk (original)
+++ trunk/libs/thread/doc/condition_variables.qbk 2012-09-08 10:12:05 EDT (Sat, 08 Sep 2012)
@@ -19,6 +19,7 @@
     };
     class condition_variable;
     class condition_variable_any;
+ void notify_all_at_thread_exit(condition_variable& cond, unique_lock<mutex> lk);
   }
 
 The classes `condition_variable` and `condition_variable_any` provide a
@@ -86,7 +87,7 @@
 
 [section:condition_variable Class `condition_variable`]
 
- #include <boost/thread/condition_variable.hpp>
+ //#include <boost/thread/condition_variable.hpp>
 
     namespace boost
     {
@@ -439,7 +440,7 @@
 
 [section:condition_variable_any Class `condition_variable_any`]
 
- #include <boost/thread/condition_variable.hpp>
+ //#include <boost/thread/condition_variable.hpp>
 
     namespace boost
     {
@@ -751,14 +752,53 @@
 
 [endsect]
 
-[section:condition Typedef `condition`]
+[section:condition Typedef `condition` DEPRECATED V3]
 
- #include <boost/thread/condition.hpp>
+ // #include <boost/thread/condition.hpp>
+ namespace boost
+ {
 
     typedef condition_variable_any condition;
 
+ }
+
 The typedef `condition` is provided for backwards compatibility with previous boost releases.
 
 [endsect]
 
+
+[section:notify_all_at_thread_exit Non-member Function `notify_all_at_thread_exit`()]
+
+ // #include <boost/thread/condition_variable.hpp>
+
+ namespace boost
+ {
+ void notify_all_at_thread_exit(condition_variable& cond, unique_lock<mutex> lk);
+ }
+
+[variablelist
+
+[[Requires:] [`lk` is locked by the calling thread and either no other thread is waiting on `cond`, or `lk.mutex()` returns the same value for each of the lock arguments supplied by all concurrently waiting (via `wait`, `wait_for`, or `wait_until`) threads.]]
+[[Effects:] [transfers ownership of the lock associated with `lk` into internal storage and schedules `cond` to be notified when the current thread exits, after all objects of thread storage duration associated with the current thread have been destroyed. This notification shall be as if
+
+``
+ lk.unlock();
+ cond.notify_all();
+``
+
+]]
+
+]
+
+[/
+[[Synchronization:] [The call to notify_all_at_thread_exit and the completion of the destructors for all the current threadÕs variables of thread storage duration synchronize with (1.10) calls to functions waiting on cond.
+]]
+[[Note:] [The supplied lock will be held until the thread exits, and care must be taken to ensure that this does not cause deadlock due to lock ordering issues. After calling notify_all_at_thread_exit it is recommended that the thread should be exited as soon as possible, and that no blocking or time-consuming tasks are run on that thread.
+]]
+[[Note:] [It is the userÕs responsibility to ensure that waiting threads do not erroneously assume that the thread has finished if they experience spurious wakeups. This typically requires that the condition being waited for is satisfied while holding the lock on lk, and that this lock is not released and reacquired prior to calling notify_all_at_thread_exit.
+]]
+]
+
+[endsect]
+
 [endsect]

Modified: trunk/libs/thread/doc/future_ref.qbk
==============================================================================
--- trunk/libs/thread/doc/future_ref.qbk (original)
+++ trunk/libs/thread/doc/future_ref.qbk 2012-09-08 10:12:05 EDT (Sat, 08 Sep 2012)
@@ -5,16 +5,17 @@
   http://www.boost.org/LICENSE_1_0.txt).
 ]
 
+
 [section:reference Futures Reference]
 
   //#include <boost/thread/futures.hpp>
 
- namespace boost
+ namespace boost
   {
   #if defined BOOST_THREAD_PROVIDES_DEPRECATED_FEATURES_SINCE_V3_0_0
     namespace future_state
     {
- enum state {uninitialized, waiting, ready, moved};
+ enum state {uninitialized, waiting, ready, moved};
     }
   #endif
 
@@ -47,7 +48,7 @@
     void swap(promise<R>& x, promise<R>& y) noexcept;
 
     namespace container {
- template <class R, class Alloc>
+ template <class R, class Alloc>
       struct uses_allocator<promise<R>, Alloc>:: true_type;
     }
 
@@ -61,14 +62,21 @@
     class packaged_task;
     template <class R> void swap(packaged_task<R>&, packaged_task<R>&) noexcept;
 
- template <class R, class Alloc>
+ template <class R, class Alloc>
     struct uses_allocator<packaged_task <R>, Alloc>;
 
- // template <class F, class... Args>
- // future<typename result_of<typename decay<F>::type(typename decay<Args>::type...)>::type>
+ template <class F>
+ future<typename result_of<typename decay<F>::type()>::type>
+ async(F f);
+ template <class F>
+ future<typename result_of<typename decay<F>::type()>::type>
+ async(launch policy, F f);
+
+ // template <class F, class... Args>
+ // future<typename result_of<typename decay<F>::type(typename decay<Args>::type...)>::type>
     // async(F&& f, Args&&... args); // NOT YET IMPLEMENTED
- // template <class F, class... Args>
- // future<typename result_of<typename decay<F>::type(typename decay<Args>::type...)>::type>
+ // template <class F, class... Args>
+ // future<typename result_of<typename decay<F>::type(typename decay<Args>::type...)>::type>
     // async(launch policy, F&& f, Args&&... args); // NOT YET IMPLEMENTED
 
 
@@ -89,7 +97,7 @@
 
     namespace future_state
     {
- enum state {uninitialized, waiting, ready, moved};
+ enum state {uninitialized, waiting, ready, moved};
     }
 
 
@@ -153,66 +161,66 @@
 
 [section:future_status Enumeration `future_status`]
 
- enum class future_status {
+ enum class future_status {
     ready, timeout, deferred
   };
 
 [endsect]
 
-[section:unique_future `unique_future` class template]
+[section:unique_future __unique_future class template]
 
     template <typename R>
- class unique_future
+ class __unique_future__
     {
 
     public:
- unique_future(unique_future & rhs);// = delete;
- unique_future& operator=(unique_future& rhs);// = delete;
+ __unique_future__(__unique_future__ & rhs);// = delete;
+ __unique_future__& operator=(__unique_future__& rhs);// = delete;
 
- unique_future() noexcept;
- ~unique_future();
+ __unique_future__() noexcept;
+ ~__unique_future__();
 
- // move support
- unique_future(unique_future && other) noexcept;
- unique_future& operator=(unique_future && other) noexcept;
- shared_future<R> share();
-
- void swap(unique_future& other) noexcept; // EXTENSION
-
- // retrieving the value
- R&& get();
-
- // functions to check state
- bool valid() const;
- bool is_ready() const; // EXTENSION
- bool has_exception() const; // EXTENSION
- bool has_value() const; // EXTENSION
-
- // waiting for the result to be ready
- void wait() const;
- template <class Rep, class Period>
- future_status wait_for(const chrono::duration<Rep, Period>& rel_time) const;
- template <class Clock, class Duration>
- future_status wait_until(const chrono::time_point<Clock, Duration>& abs_time) const;
+ // move support
+ __unique_future__(__unique_future__ && other) noexcept;
+ __unique_future__& operator=(__unique_future__ && other) noexcept;
+ shared_future<R> share();
+
+ void swap(__unique_future__& other) noexcept; // EXTENSION
+
+ // retrieving the value
+ R&& get();
+
+ // functions to check state
+ bool valid() const;
+ bool is_ready() const; // EXTENSION
+ bool has_exception() const; // EXTENSION
+ bool has_value() const; // EXTENSION
+
+ // waiting for the result to be ready
+ void wait() const;
+ template <class Rep, class Period>
+ future_status wait_for(const chrono::duration<Rep, Period>& rel_time) const;
+ template <class Clock, class Duration>
+ future_status wait_until(const chrono::time_point<Clock, Duration>& abs_time) const;
 
     #if defined BOOST_THREAD_PROVIDES_DEPRECATED_FEATURES_SINCE_V3_0_0 || defined BOOST_THREAD_DONT_USE_CHRONO
- template<typename Duration>
- bool timed_wait(Duration const& rel_time) const;
- bool timed_wait_until(boost::system_time const& abs_time) const;
+ template<typename Duration>
+ bool timed_wait(Duration const& rel_time) const;
+ bool timed_wait_until(boost::system_time const& abs_time) const;
     #endif
     #if defined BOOST_THREAD_PROVIDES_DEPRECATED_FEATURES_SINCE_V3_0_0
- typedef future_state::state state;
- state get_state() const;
+ typedef future_state::state state;
+ state get_state() const;
     #endif
     };
 
 [section:default_constructor Default Constructor]
 
- unique_future();
+ __unique_future__();
 
 [variablelist
 
-[[Effects:] [Constructs an uninitialized future.]]
+[[Effects:] [Constructs an uninitialized __unique_future__.]]
 
 [[Postconditions:] [[unique_future_is_ready_link `this->is_ready`] returns `false`. [unique_future_get_state_link
 `this->get_state()`] returns __uninitialized__.]]
@@ -225,7 +233,7 @@
 
 [section:destructor Destructor]
 
- ~unique_future();
+ ~__unique_future__();
 
 [variablelist
 
@@ -239,11 +247,11 @@
 
 [section:move_constructor Move Constructor]
 
- unique_future(unique_future && other);
+ __unique_future__(__unique_future__ && other);
 
 [variablelist
 
-[[Effects:] [Constructs a new future, and transfers ownership of the asynchronous result associated with `other` to `*this`.]]
+[[Effects:] [Constructs a new __unique_future__, and transfers ownership of the asynchronous result associated with `other` to `*this`.]]
 
 [[Postconditions:] [[unique_future_get_state_link `this->get_state()`] returns the value of `other->get_state()` prior to the
 call. `other->get_state()` returns __uninitialized__. If `other` was associated with an asynchronous result, that result is now
@@ -259,7 +267,7 @@
 
 [section:move_assignment Move Assignment Operator]
 
- unique_future& operator=(unique_future && other);
+ __unique_future__& operator=(__unique_future__ && other);
 
 [variablelist
 
@@ -280,7 +288,7 @@
 
 [section:swap Member function `swap()`]
 
- void swap(unique_future & other) no_except;
+ void swap(__unique_future__ & other) no_except;
 
 [variablelist
 
@@ -301,8 +309,8 @@
 [section:get Member function `get()`]
 
     R&& get();
- R& unique_future<R&>::get();
- void unique_future<void>::get();
+ R& __unique_future__<R&>::get();
+ void __unique_future__<void>::get();
 
 [variablelist
 
@@ -478,46 +486,46 @@
     class shared_future
     {
     public:
- typedef future_state::state state; // EXTENSION
+ typedef future_state::state state; // EXTENSION
 
- shared_future() noexcept;
- ~shared_future();
+ shared_future() noexcept;
+ ~shared_future();
 
- // copy support
- shared_future(shared_future const& other);
- shared_future& operator=(shared_future const& other);
-
- // move support
- shared_future(shared_future && other) noexcept;
- shared_future(unique_future<R> && other) noexcept;
- shared_future& operator=(shared_future && other) noexcept;
- shared_future& operator=(unique_future<R> && other) noexcept;
-
- void swap(shared_future& other);
-
- // retrieving the value
- R get();
-
- // functions to check state, and wait for ready
- bool valid() const noexcept;
- bool is_ready() const noexcept; // EXTENSION
- bool has_exception() const noexcept; // EXTENSION
- bool has_value() const noexcept; // EXTENSION
-
- // waiting for the result to be ready
- void wait() const;
- template <class Rep, class Period>
- future_status wait_for(const chrono::duration<Rep, Period>& rel_time) const;
- template <class Clock, class Duration>
- future_status wait_until(const chrono::time_point<Clock, Duration>& abs_time) const;
+ // copy support
+ shared_future(shared_future const& other);
+ shared_future& operator=(shared_future const& other);
+
+ // move support
+ shared_future(shared_future && other) noexcept;
+ shared_future(__unique_future__<R> && other) noexcept;
+ shared_future& operator=(shared_future && other) noexcept;
+ shared_future& operator=(__unique_future__<R> && other) noexcept;
+
+ void swap(shared_future& other);
+
+ // retrieving the value
+ R get();
+
+ // functions to check state, and wait for ready
+ bool valid() const noexcept;
+ bool is_ready() const noexcept; // EXTENSION
+ bool has_exception() const noexcept; // EXTENSION
+ bool has_value() const noexcept; // EXTENSION
+
+ // waiting for the result to be ready
+ void wait() const;
+ template <class Rep, class Period>
+ future_status wait_for(const chrono::duration<Rep, Period>& rel_time) const;
+ template <class Clock, class Duration>
+ future_status wait_until(const chrono::time_point<Clock, Duration>& abs_time) const;
 
     #if defined BOOST_THREAD_PROVIDES_DEPRECATED_FEATURES_SINCE_V3_0_0 || defined BOOST_THREAD_DONT_USE_CHRONO
- template<typename Duration>
- bool timed_wait(Duration const& rel_time) const;
- bool timed_wait_until(boost::system_time const& abs_time) const;
+ template<typename Duration>
+ bool timed_wait(Duration const& rel_time) const;
+ bool timed_wait_until(boost::system_time const& abs_time) const;
     #endif
     #if defined BOOST_THREAD_PROVIDES_DEPRECATED_FEATURES_SINCE_V3_0_0
- state get_state() const noexcept;
+ state get_state() const noexcept;
     #endif
     };
 
@@ -527,7 +535,7 @@
 
 [variablelist
 
-[[Effects:] [Constructs an uninitialized future.]]
+[[Effects:] [Constructs an uninitialized shared_future.]]
 
 [[Postconditions:] [[shared_future_is_ready_link `this->is_ready`] returns `false`. [shared_future_get_state_link
 `this->get_state()`] returns __uninitialized__.]]
@@ -712,33 +720,33 @@
     {
     public:
 
- promise();
- template <class Allocator>
- promise(allocator_arg_t, Allocator a);
- promise & operator=(const promise & rhs);// = delete;
- promise(const promise & rhs);// = delete;
- ~promise();
-
- // Move support
- promise(promise && rhs) noexcept;;
- promise & operator=(promise&& rhs) noexcept;;
-
- void swap(promise& other) noexcept;
- // Result retrieval
- unique_future<R> get_future();
-
- // Set the value
- void set_value(R& r);
- void set_value(R&& r);
- void set_exception(boost::exception_ptr e);
-
- // setting the result with deferred notification
- // void set_value_at_thread_exit(const R& r); // NOT YET IMPLEMENTED
- // void set_value_at_thread_exit(see below); // NOT YET IMPLEMENTED
- // void set_exception_at_thread_exit(exception_ptr p); // NOT YET IMPLEMENTED
+ promise();
+ template <class Allocator>
+ promise(allocator_arg_t, Allocator a);
+ promise & operator=(const promise & rhs);// = delete;
+ promise(const promise & rhs);// = delete;
+ ~promise();
+
+ // Move support
+ promise(promise && rhs) noexcept;;
+ promise & operator=(promise&& rhs) noexcept;;
+
+ void swap(promise& other) noexcept;
+ // Result retrieval
+ __unique_future__<R> get_future();
+
+ // Set the value
+ void set_value(R& r);
+ void set_value(R&& r);
+ void set_exception(boost::exception_ptr e);
+
+ // setting the result with deferred notification
+ // void set_value_at_thread_exit(const R& r); // NOT YET IMPLEMENTED
+ // void set_value_at_thread_exit(see below); // NOT YET IMPLEMENTED
+ // void set_exception_at_thread_exit(exception_ptr p); // NOT YET IMPLEMENTED
 
- template<typename F>
- void set_wait_callback(F f); // EXTENSION
+ template<typename F>
+ void set_wait_callback(F f); // EXTENSION
     };
 
 [section:default_constructor Default Constructor]
@@ -757,8 +765,8 @@
 
 [section:alloc_constructor Allocator Constructor]
 
- template <class Allocator>
- promise(allocator_arg_t, Allocator a);
+ template <class Allocator>
+ promise(allocator_arg_t, Allocator a);
 
 [variablelist
 
@@ -826,7 +834,7 @@
 
 [section:get_future Member Function `get_future()`]
 
- unique_future<R> get_future();
+ __unique_future__<R> get_future();
 
 [variablelist
 
@@ -913,43 +921,43 @@
     class packaged_task
     {
     public:
- typedef R result_type;
+ typedef R result_type;
 
- packaged_task(packaged_task&);// = delete;
- packaged_task& operator=(packaged_task&);// = delete;
+ packaged_task(packaged_task&);// = delete;
+ packaged_task& operator=(packaged_task&);// = delete;
 
- // construction and destruction
- packaged_task() noexcept;
+ // construction and destruction
+ packaged_task() noexcept;
 
- explicit packaged_task(R(*f)());
-
- template <class F>
- explicit packaged_task(F&& f);
+ explicit packaged_task(R(*f)());
 
- template <class F, class Allocator>
- packaged_task(allocator_arg_t, Allocator a, F&& f);
+ template <class F>
+ explicit packaged_task(F&& f);
 
- ~packaged_task()
- {}
+ template <class F, class Allocator>
+ packaged_task(allocator_arg_t, Allocator a, F&& f);
 
- // move support
- packaged_task(packaged_task&& other) noexcept;
- packaged_task& operator=(packaged_task&& other) noexcept;
+ ~packaged_task()
+ {}
 
- void swap(packaged_task& other) noexcept;
+ // move support
+ packaged_task(packaged_task&& other) noexcept;
+ packaged_task& operator=(packaged_task&& other) noexcept;
 
- bool valid() const noexcept;
- // result retrieval
- unique_future<R> get_future();
+ void swap(packaged_task& other) noexcept;
 
- // execution
- void operator()();
- // void operator()(ArgTypes... ); // NOT YET IMPLEMENTED
- // void make_ready_at_thread_exit(ArgTypes...); // NOT YET IMPLEMENTED
+ bool valid() const noexcept;
+ // result retrieval
+ __unique_future__<R> get_future();
 
- void reset();
- template<typename F>
- void set_wait_callback(F f); // EXTENSION
+ // execution
+ void operator()();
+ // void operator()(ArgTypes... ); // NOT YET IMPLEMENTED
+ // void make_ready_at_thread_exit(ArgTypes...); // NOT YET IMPLEMENTED
+
+ void reset();
+ template<typename F>
+ void set_wait_callback(F f); // EXTENSION
     };
 
 [section:task_constructor Task Constructor]
@@ -977,10 +985,10 @@
 
 [section:alloc_constructor Allocator Constructor]
 
- template <class Allocator>
- packaged_task(allocator_arg_t, Allocator a, R(*f)());
- template <class F, class Allocator>
- packaged_task(allocator_arg_t, Allocator a, F&& f);
+ template <class Allocator>
+ packaged_task(allocator_arg_t, Allocator a, R(*f)());
+ template <class F, class Allocator>
+ packaged_task(allocator_arg_t, Allocator a, F&& f);
 
 [variablelist
 
@@ -1052,7 +1060,7 @@
 
 [section:get_future Member Function `get_future()`]
 
- unique_future<R> get_future();
+ __unique_future__<R> get_future();
 
 [variablelist
 
@@ -1086,7 +1094,7 @@
 
 [section:reset Member Function `reset()`]
 
- void reset();
+ void reset();
 
 [variablelist
 
@@ -1123,6 +1131,129 @@
 
 [endsect]
 
+
+[section:decay_copy Non-member function `decay_copy()`]
+ template <class T>
+ typename decay<T>::type decay_copy(T&& v)
+ {
+ return std::forward<T>(v);
+ }
+
+[endsect]
+
+[section:async Non-member function `async()`]
+
+ template <class F>
+ __unique_future__<typename result_of<typename decay<F>::type()>::type>
+ async(F f);
+ template <class F>
+ __unique_future__<typename result_of<typename decay<F>::type()>::type>
+ async(launch policy, F f);
+
+
+The function template async provides a mechanism to launch a function potentially in a new thread and
+provides the result of the function in a future object with which it shares a shared state.
+
+[warning `async(launch::deferred, F)` is NOT YET IMPLEMENTED!]
+
+[variablelist
+
+[[Requires:] [
+
+``
+decay_copy(std::forward<F>(f))()
+``
+
+shall be a valid expression.
+]]
+
+[[Effects] [The first function behaves the same as a call to the second function with a policy argument of
+ `launch::async | launch::deferred` and the same arguments for `F`. The second function creates a shared state that is associated with the returned future object.
+
+The further behavior of the second function depends on the policy argument as follows (if more than one of these conditions applies, the implementation may choose any of the corresponding policies):
+
+- if `policy & launch::async` is non-zero - calls `decay_copy(std::forward<F>(f))()` as if in a new thread of execution represented by a thread object with the calls to `decay_copy()` being evaluated in the thread that called `async`. Any return value is stored as the result in the shared state. Any exception propagated from the execution of `decay_copy(std::forward<F>(f))()` is stored as the exceptional result in the shared state. The thread object is stored in the shared state and affects the behavior of any asynchronous return objects that reference that state.
+
+- if `policy & launch::deferred` is non-zero - Stores `decay_copy(std::forward<F>(f))` in the shared state. This copy of `f` constitute a deferred function. Invocation of the deferred function evaluates `boost::move(g)()` where `g` is the stored value of `decay_copy(std::forward<F>(f))`. The shared state is not made ready until the function has completed. The first call to a non-timed waiting function on an asynchronous return object referring to this shared state shall invoke the deferred function in the thread that called the waiting function. Once evaluation of `boost::move(g)()` begins, the function is no longer considered deferred. (Note: If this policy is specified together with other policies, such as when using a policy value of `launch::async | launch::deferred`, implementations should defer invocation or the selection of the policy when no more concurrency can be effectively exploited.)
+
+]]
+
+[[Returns:] [An object of type `__unique_future__<typename result_of<typename decay<F>::type()>::type>` that refers to the shared state created by this call to `async`.]]
+
+[[Synchronization:] [Regardless of the provided policy argument,
+
+- the invocation of `async` synchronizes with the invocation of `f`. (Note: This statement applies even when the corresponding future object is moved to another thread.); and
+
+- the completion of the function `f` is sequenced before the shared state is made ready. (Note: `f` might not be called at all, so its completion might never happen.)
+
+If the implementation chooses the `launch::async` policy,
+
+- a call to a waiting function on an asynchronous return object that shares the shared state created by this async call shall block until the associated thread has completed, as if joined;
+
+- the associated thread completion synchronizes with the return from the first function that successfully detects the ready status of the shared state or with the return from the last function that releases the shared state, whichever happens first.
+]]
+
+[[Throws:][`system_error` if policy is `launch::async` and the implementation is unable to start a new thread.
+]]
+
+[[Error conditions:] [
+
+- `resource_unavailable_try_again` - if policy is `launch::async` and the system is unable to start a new thread.
+
+]]
+
+[[Remarks:] [The first signature shall not participate in overload resolution if decay<F>::type is std::launch.
+]]
+
+]
+
+[/
+
+[variablelist
+
+[[Requires:] [F and each Ti in Args shall satisfy the MoveConstructible requirements. INVOKE (DECAY_- COPY (std::forward<F>(f)), decay_copy (std::forward<Args>(args))...) shall be a valid expression.
+
+]]
+[[Effects:] [The first function behaves the same as a call to the second function with a policy argument of launch::async | launch::deferred and the same arguments for F and Args. The second function creates a shared state that is associated with the returned future object. The further behavior of the second function depends on the policy argument as follows (if more than one of these conditions applies, the implementation may choose any of the corresponding policies):
+- if policy & launch::async is non-zero - calls INVOKE (decay_copy (std::forward<F>(f)), decay_copy (std::forward<Args>(args))...) (20.8.2, 30.3.1.2) as if in a new thread of exe- cution represented by a thread object with the calls to decay_copy() being evaluated in the thread that called async. Any return value is stored as the result in the shared state. Any excep- tion propagated from the execution of INVOKE(decay_copy(std::forward<F>(f)), DECAY_- COPY (std::forward<Args>(args))...) is stored as the exceptional result in the shared state. The thread object is stored in the shared state and affects the behavior of any asynchronous return objects that reference that state.
+- if policy & launch::deferred is non-zero - Stores decay_copy (std::forward<F>(f)) and decay_copy (std::forward<Args>(args))... in the shared state. These copies of f and args constitute a deferred function. Invocation of the deferred function evaluates INVOKE (std::move(g), std::move(xyz)) where g is the stored value of decay_copy (std::forward<F>(f)) and xyz is the stored copy of decay_copy (std::forward<Args>(args)).... The shared state is not made ready until the function has completed. The first call to a non-timed waiting function (30.6.4) on an asynchronous return object referring to this shared state shall invoke the deferred func- tion in the thread that called the waiting function. Once evaluation of INVOKE (std::move(g), std::move(xyz)) begins, the function is no longer considered deferred.
+
+]]
+
+[[Note:] [If this policy is specified together with other policies, such as when using a policy value of launch::async | launch::deferred, implementations should defer invocation or the selection of the policy when no more concurrency can be effectively exploited.]]
+[[Returns:] [An object of type __unique_future__<typename result_of<typename decay<F>::type(typename de- cay<Args>::type...)>::type> that refers to the shared state created by this call to async.]]
+
+[[Synchronization:] [Regardless of the provided policy argument,
+
+- the invocation of async synchronizes with (1.10) the invocation of f. (Note: This statement applies even when the corresponding future object is moved to another thread.); and
+- the completion of the function f is sequenced before (1.10) the shared state is made ready. (Note: f might not be called at all, so its completion might never happen.)
+If the implementation chooses the launch::async policy,
+- a call to a waiting function on an asynchronous return object that shares the shared state created by this async call shall block until the associated thread has completed, as if joined;
+- the associated thread completion synchronizes with (1.10) the return from the first function that successfully detects the ready status of the shared state or with the return from the last function that releases the shared state, whichever happens first.
+
+]]
+
+[[Throws:] [system_error if policy is launch::async and the implementation is unable to start a new thread.
+]]
+
+[[Error conditions:][
+
+- resource_unavailable_try_again - if policy is launch::async and the system is unable to start a new thread.
+]]
+
+[[Remarks:] [The first signature shall not participate in overload resolution if decay<F>::type is std:: launch.
+]]
+
+]
+
+]
+
+
+
+
+[endsect]
+
+
 [section:wait_for_any Non-member function `wait_for_any()`]
 
     template<typename Iterator>

Modified: trunk/libs/thread/doc/futures.qbk
==============================================================================
--- trunk/libs/thread/doc/futures.qbk (original)
+++ trunk/libs/thread/doc/futures.qbk 2012-09-08 10:12:05 EDT (Sat, 08 Sep 2012)
@@ -23,7 +23,8 @@
 
 
 [template unique_future_link[link_text] [link thread.synchronization.futures.reference.unique_future [link_text]]]
-[def __unique_future__ [unique_future_link `boost::unique_future`]]
+[def __unique_future__ [unique_future_link `future`]]
+[def __unique_future `future`]
 
 [template unique_future_get_link[link_text] [link thread.synchronization.futures.reference.unique_future.get [link_text]]]
 [def __unique_future_get__ [unique_future_get_link `boost::unique_future<R>::get()`]]
@@ -114,7 +115,7 @@
     }
 
     boost::packaged_task<int> pt(calculate_the_answer_to_life_the_universe_and_everything);
- boost::unique_future<int> fi=pt.get_future();
+ boost::__unique_future__<int> fi=pt.get_future();
 
     boost::thread task(boost::move(pt)); // launch task on a thread
 
@@ -132,7 +133,7 @@
 produce multiple values.
 
     boost::promise<int> pi;
- boost::unique_future<int> fi;
+ boost::__unique_future__<int> fi;
     fi=pi.get_future();
 
     pi.set_value(42);
@@ -174,7 +175,7 @@
     {
         boost::packaged_task<int> task(calculate_the_answer_to_life_the_universe_and_everything);
         task.set_wait_callback(invoke_lazy_task);
- boost::unique_future<int> f(task.get_future());
+ boost::__unique_future__<int> f(task.get_future());
 
         assert(f.get()==42);
     }

Modified: trunk/libs/thread/doc/mutex_concepts.qbk
==============================================================================
--- trunk/libs/thread/doc/mutex_concepts.qbk (original)
+++ trunk/libs/thread/doc/mutex_concepts.qbk 2012-09-08 10:12:05 EDT (Sat, 08 Sep 2012)
@@ -790,8 +790,10 @@
 
 [section:locks Lock Types]
 
- #include <boost/thread/locks.hpp>
+ //#include <boost/thread/locks.hpp>
 
+ namespace boost
+ {
     struct defer_lock_t {};
     struct try_to_lock_t {};
     struct adopt_lock_t {};
@@ -815,6 +817,7 @@
     void swap(upgrade_lock <Mutex>& lhs, upgrade_lock <Mutex>& rhs);
     template <class Mutex>
     class upgrade_to_unique_lock;
+ }
 
 [section:lock_tags Lock option tags]
 
@@ -837,7 +840,7 @@
 
 [section:lock_guard Class template `lock_guard`]
 
- #include <boost/thread/locks.hpp>
+ //#include <boost/thread/locks.hpp>
 
     template<typename Lockable>
     class lock_guard
@@ -903,7 +906,7 @@
 
 [section:unique_lock Class template `unique_lock`]
 
- #include <boost/thread/locks.hpp>
+ //#include <boost/thread/locks.hpp>
 
     template<typename Lockable>
     class unique_lock
@@ -1267,7 +1270,7 @@
 
 [section:shared_lock Class template `shared_lock`]
 
- #include <boost/thread/locks.hpp>
+ //#include <boost/thread/locks.hpp>
 
     template<typename Lockable>
     class shared_lock
@@ -1508,7 +1511,7 @@
 
 [section:upgrade_lock Class template `upgrade_lock`]
 
- #include <boost/thread/locks.hpp>
+ //#include <boost/thread/locks.hpp>
 
     template<typename Lockable>
     class upgrade_lock
@@ -1663,8 +1666,10 @@
 
 [section: reverse_mutex Class template `reverse_mutex`]
 
- #include <boost/thread/reverse_mutex.hpp>
+ //#include <boost/thread/reverse_mutex.hpp>
 
+ namespace boost
+ {
     template<typename BasicLockable>
     class reverse_mutex
     {
@@ -1679,6 +1684,7 @@
         void lock();
         void unlock();
     };
+ }
 
 __reverse_mutex reverse the operations of a __BasicLockable, that unlocks the lockable when `lock()` is called and locks it when `unlock()` is called.
 
@@ -1692,17 +1698,22 @@
 
 [section:shared_lock_guard Class template `shared_lock_guard`]
 
- #include <boost/thread/shared_lock_guard.hpp>
-
+ // #include <boost/thread/shared_lock_guard.hpp>
+ namespace boost
+ {
     template<typename SharedLockable>
     class shared_lock_guard
     {
     public:
+ shared_lock_guard(shared_lock_guard const&) = delete;
+ shared_lock_guard& operator=(shared_lock_guard const&) = delete;
+
         explicit shared_lock_guard(SharedLockable& m_);
         shared_lock_guard(SharedLockable& m_,boost::adopt_lock_t);
 
         ~shared_lock_guard();
     };
+ }
 
 __shared_lock_guard is very simple: on construction it
 acquires shared ownership of the implementation of the __shared_lockable_concept__ supplied as
@@ -1756,7 +1767,9 @@
 
 [section:reverse_lock Class template `reverse_lock`]
 
- #include <boost/thread/reverse_lock.hpp>
+ // #include <boost/thread/reverse_lock.hpp>
+ namespace boost
+ {
 
     template<typename Lock>
     class reverse_lock
@@ -1768,6 +1781,7 @@
         explicit reverse_lock(Lock& m_);
         ~reverse_lock();
     };
+ }
 
 __reverse_lock reverse the operations of a lock: it provide for RAII-style, that unlocks the lock at construction time and lock it at destruction time. In addition, it transfer ownership temporarily, so that the mutex can not be locked using the Lock.
 
@@ -1810,6 +1824,10 @@
 
 [section:lock_multiple Non-member function `lock(Lockable1,Lockable2,...)`]
 
+ // #include <boost/thread/locks.hpp>
+ namespace boost
+ {
+
     template<typename Lockable1,typename Lockable2>
     void lock(Lockable1& l1,Lockable2& l2);
 
@@ -1822,6 +1840,8 @@
     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

Modified: trunk/libs/thread/doc/mutexes.qbk
==============================================================================
--- trunk/libs/thread/doc/mutexes.qbk (original)
+++ trunk/libs/thread/doc/mutexes.qbk 2012-09-08 10:12:05 EDT (Sat, 08 Sep 2012)
@@ -131,7 +131,7 @@
         ~recursive_mutex();
         
         void lock();
- bool try_lock();
+ bool try_lock() noexcept;
         void unlock();
 
         typedef platform-specific-type native_handle_type;
@@ -187,7 +187,7 @@
         ~recursive_timed_mutex();
         
         void lock();
- bool try_lock();
+ bool try_lock() noexcept;
         void unlock();
 
 

Modified: trunk/libs/thread/doc/tss.qbk
==============================================================================
--- trunk/libs/thread/doc/tss.qbk (original)
+++ trunk/libs/thread/doc/tss.qbk 2012-09-08 10:12:05 EDT (Sat, 08 Sep 2012)
@@ -53,8 +53,10 @@
 
 [section:thread_specific_ptr Class `thread_specific_ptr`]
 
- #include <boost/thread/tss.hpp>
+ // #include <boost/thread/tss.hpp>
 
+ namespace boost
+ {
     template <typename T>
     class thread_specific_ptr
     {
@@ -70,6 +72,7 @@
         T* release();
         void reset(T* new_value=0);
     };
+ }
 
 [section:default_constructor `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