[Boost-commit] svn:boost r80570 - trunk/libs/thread/doc

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

Author: viboes
Date: 2012-09-18 02:08:11 EDT (Tue, 18 Sep 2012)
New Revision: 80570
URL: http://svn.boost.org/trac/boost/changeset/80570

Log:
Thread: Complete future reference documentation
Text files modified: 
   trunk/libs/thread/doc/future_ref.qbk |   264 +++++++++++++++++++++++++++++++++++++-- 
   trunk/libs/thread/doc/futures.qbk    |    12                                         
   trunk/libs/thread/doc/overview.qbk   |     8                                         
   trunk/libs/thread/doc/thread.qbk     |     2                                         
   trunk/libs/thread/doc/time.qbk       |    18 +-                                      
   5 files changed, 267 insertions(+), 37 deletions(-)

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-18 02:08:11 EDT (Tue, 18 Sep 2012)
@@ -27,6 +27,17 @@
       no_state
     };
 
+    enum class launch
+    {
+      async = unspecified,
+      deferred = unspecified,
+      any = async | deferred
+    };
+    
+    enum class future_status {
+      ready,  timeout, deferred
+    };
+    
     namespace system
     {
       template <>
@@ -115,6 +126,18 @@
   }
 
 [endsect]
+[section:launch Enumeration `launch `]
+
+    enum class launch
+    {
+      async = unspecified,
+      deferred = unspecified,
+      any = async | deferred
+    };
+
+The enum type launch is a bitmask type with launch::async and launch::deferred denoting individual bits. 
+
+[endsect]
 [section:is_error_code_enum Specialization `is_error_code_enum<future_errc>`]
 
   namespace system
@@ -132,6 +155,12 @@
     error_code make_error_code(future_errc e);
   }
 
+[variablelist
+
+[[Returns:] [`error_code(static_cast<int>(e), future_category())`.]]
+
+]  
+
 [endsect]
 [section:make_error_condition Non-member function `make_error_condition()`]
 
@@ -140,11 +169,26 @@
     error_condition make_error_condition(future_errc e);
   }
 
+[variablelist
+
+[[Returns:] [`error_condition(static_cast<int>(e), future_category())`.]]
+
+]  
+
 [endsect]
 [section:future_category Non-member function `future_category()`]
 
   const system::error_category& future_category();
 
+[variablelist
+
+[[Returns:] [A reference to an object of a type derived from class error_category.]]
+
+[[Notes:] [The object's `default_error_condition` and equivalent virtual functions behave as specified for the class `system::error_category`. 
+The object's `name` virtual function returns a pointer to the string "future".]]
+
+]  
+
 [endsect]
 [section:future_error Class `future_error`]
 
@@ -157,6 +201,34 @@
       const system::error_code& code() const no_except;
   };
 
+[section:constructor Constructor]
+
+      future_error(system::error_code ec);
+
+[variablelist
+
+[[Effects:] [Constructs a future_error.]]
+
+[[Postconditions:] [`code()==ec` ]]
+
+[[Throws:] [Nothing.]]
+
+]
+
+[endsect]
+[section:code Member function `code()`]
+
+      const system::error_code& code() const no_except;
+
+[variablelist
+
+[[Returns:] [The value of `ec` that was passed to the object's constructor.]]
+
+]
+
+[endsect]
+
+
 [endsect]
 
 [section:future_status Enumeration `future_status`]
@@ -408,16 +480,96 @@
 
 [endsect]
 
+[section:wait_for Member function `wait_for()`]
 
-[section:is_ready Member function `is_ready()` EXTENSION]
+      template <class Rep, class Period>
+      future_status wait_for(const chrono::duration<Rep, Period>& rel_time) const;
 
-    bool is_ready();
+[variablelist
+
+[[Effects:] [If `*this` is associated with an asynchronous result, waits until the result is ready, or the time specified by
+`wait_duration` has elapsed. If the result is not ready on entry, and the result has a ['wait callback] set, that callback is
+invoked prior to waiting.]]
+
+[[Returns:] [
+
+- `future_status::deferred` if the shared state contains a deferred function. (Not implemented yet)
+
+- `future_status::ready` if the shared state is ready.
+
+- `future_status::timeout` if the function is returning because the relative timeout specified by `rel_time` has expired.
+
+]]
+
+[[Throws:] [__future_uninitialized__ if `*this` is not associated with an asynchronous result. __thread_interrupted__ if the result
+associated with `*this` is not ready at the point of the call, and the current thread is interrupted. Any exception thrown by the
+['wait callback] if such a callback is called.]]
+
+[[Postconditions:] [If this call returned `true`, then [unique_future_is_ready_link `this->is_ready()`] returns `true` and
+[unique_future_get_state_link `this->get_state()`] returns __ready__.]]
+
+[[Notes:] [`wait_for()` is an ['interruption point]. `Duration` must be a type that meets the Boost.DateTime time duration requirements.]]
+
+]
+
+[endsect]
+
+[section:wait_until Member function `wait_until()`]
+
+      template <class Clock, class Duration>
+      future_status wait_until(const chrono::time_point<Clock, Duration>& abs_time) const;
 
 [variablelist
 
-[[Effects:] [Checks to see if the asynchronous result associated with `*this` is set.]]
+[[Effects:] [If `*this` is associated with an asynchronous result, waits until the result is ready, or the time point specified by
+`wait_timeout` has passed. If the result is not ready on entry, and the result has a ['wait callback] set, that callback is invoked
+prior to waiting.]]
+
+[[Returns:] [
 
-[[Returns:] [`true` if `*this` is associated with an asynchronous result, and that result is ready for retrieval, `false`
+- `future_status::deferred` if the shared state contains a deferred function. (Not implemented yet)
+
+- `future_status::ready` if the shared state is ready.
+
+- `future_status::timeout` if the function is returning because the absolute timeout specified by `absl_time` has reached.
+
+]]
+
+[[Throws:] [__future_uninitialized__ if `*this` is not associated with an asynchronous result. __thread_interrupted__ if the result
+associated with `*this` is not ready at the point of the call, and the current thread is interrupted. Any exception thrown by the
+['wait callback] if such a callback is called.]]
+
+[[Postconditions:] [If this call returned `true`, then [unique_future_is_ready_link `this->is_ready()`] returns `true` and
+[unique_future_get_state_link `this->get_state()`] returns __ready__.]]
+
+[[Notes:] [`wait_until()` is an ['interruption point].]]
+
+]
+
+[endsect]
+
+
+[section:valid Member function `valid()`]
+
+    bool valid() const;
+
+[variablelist
+
+[[Returns:] [`true` if `*this` is associated with an asynchronous result, `false`
+otherwise.]]
+
+[[Throws:] [Nothing.]]
+
+]
+
+[endsect]
+[section:is_ready Member function `is_ready()` EXTENSION]
+
+    bool is_ready() const;
+
+[variablelist
+
+[[Returns:] [`true` if `*this` is associated with an asynchronous result and that result is ready for retrieval, `false`
 otherwise.]]
 
 [[Throws:] [Nothing.]]
@@ -428,12 +580,10 @@
 
 [section:has_value Member function `has_value()` EXTENSION]
 
-    bool has_value();
+    bool has_value() const;
 
 [variablelist
 
-[[Effects:] [Checks to see if the asynchronous result associated with `*this` is set with a value rather than an exception.]]
-
 [[Returns:] [`true` if `*this` is associated with an asynchronous result, that result is ready for retrieval, and the result is a
 stored value, `false` otherwise.]]
 
@@ -445,12 +595,10 @@
 
 [section:has_exception Member function `has_exception()` EXTENSION]
 
-    bool has_exception();
+    bool has_exception() const;
 
 [variablelist
 
-[[Effects:] [Checks to see if the asynchronous result associated with `*this` is set with an exception rather than a value.]]
-
 [[Returns:] [`true` if `*this` is associated with an asynchronous result, that result is ready for retrieval, and the result is a
 stored exception, `false` otherwise.]]
 
@@ -642,13 +790,95 @@
 
 [endsect]
 
-[section:is_ready Member function `is_ready()` EXTENSION]
+[section:wait_for Member function `wait_for()`]
+
+      template <class Rep, class Period>
+      future_status wait_for(const chrono::duration<Rep, Period>& rel_time) const;
 
-    bool is_ready();
 
 [variablelist
 
-[[Effects:] [Checks to see if the asynchronous result associated with `*this` is set.]]
+[[Effects:] [If `*this` is associated with an asynchronous result, waits until the result is ready, or the time specified by
+`wait_duration` has elapsed. If the result is not ready on entry, and the result has a ['wait callback] set, that callback is
+invoked prior to waiting.]]
+
+[[Returns:] [
+
+- `future_status::deferred` if the shared state contains a deferred function. (Not implemented yet)
+
+- `future_status::ready` if the shared state is ready.
+
+- `future_status::timeout` if the function is returning because the relative timeout specified by `rel_time` has expired.
+
+]]
+
+[[Throws:] [__future_uninitialized__ if `*this` is not associated with an asynchronous result. __thread_interrupted__ if the result
+associated with `*this` is not ready at the point of the call, and the current thread is interrupted. Any exception thrown by the
+['wait callback] if such a callback is called.]]
+
+[[Postconditions:] [If this call returned `true`, then [shared_future_is_ready_link `this->is_ready()`] returns `true` and
+[shared_future_get_state_link `this->get_state()`] returns __ready__.]]
+
+[[Notes:] [`timed_wait()` is an ['interruption point]. `Duration` must be a type that meets the Boost.DateTime time duration requirements.]]
+
+]
+
+[endsect]
+
+[section:wait_until Member function `wait_until()`]
+
+      template <class Clock, class Duration>
+      future_status wait_until(const chrono::time_point<Clock, Duration>& abs_time) const;
+
+[variablelist
+
+[[Effects:] [If `*this` is associated with an asynchronous result, waits until the result is ready, or the time point specified by
+`wait_timeout` has passed. If the result is not ready on entry, and the result has a ['wait callback] set, that callback is invoked
+prior to waiting.]]
+
+[[Returns:] [
+
+- `future_status::deferred` if the shared state contains a deferred function. (Not implemented yet)
+
+- `future_status::ready` if the shared state is ready.
+
+- `future_status::timeout` if the function is returning because the absolute timeout specified by `absl_time` has reached.
+
+]]
+
+[[Throws:] [__future_uninitialized__ if `*this` is not associated with an asynchronous result. __thread_interrupted__ if the result
+associated with `*this` is not ready at the point of the call, and the current thread is interrupted. Any exception thrown by the
+['wait callback] if such a callback is called.]]
+
+[[Postconditions:] [If this call returned `true`, then [shared_future_is_ready_link `this->is_ready()`] returns `true` and
+[shared_future_get_state_link `this->get_state()`] returns __ready__.]]
+
+[[Notes:] [`timed_wait()` is an ['interruption point].]]
+
+]
+
+[endsect]
+
+[section:valid Member function `valid()`]
+
+    bool valid() const;
+
+[variablelist
+
+[[Returns:] [`true` if `*this` is associated with an asynchronous result, `false`
+otherwise.]]
+
+[[Throws:] [Nothing.]]
+
+]
+
+[endsect]
+
+[section:is_ready Member function `is_ready()` EXTENSION]
+
+    bool is_ready() const;
+
+[variablelist
 
 [[Returns:] [`true` if `*this` is associated with an asynchronous result, and that result is ready for retrieval, `false`
 otherwise.]]
@@ -661,12 +891,10 @@
 
 [section:has_value Member function `has_value()` EXTENSION]
 
-    bool has_value();
+    bool has_value() const;
 
 [variablelist
 
-[[Effects:] [Checks to see if the asynchronous result associated with `*this` is set with a value rather than an exception.]]
-
 [[Returns:] [`true` if `*this` is associated with an asynchronous result, that result is ready for retrieval, and the result is a
 stored value, `false` otherwise.]]
 
@@ -678,12 +906,10 @@
 
 [section:has_exception Member function `has_exception()` EXTENSION]
 
-    bool has_exception();
+    bool has_exception() const;
 
 [variablelist
 
-[[Effects:] [Checks to see if the asynchronous result associated with `*this` is set with an exception rather than a value.]]
-
 [[Returns:] [`true` if `*this` is associated with an asynchronous result, that result is ready for retrieval, and the result is a
 stored exception, `false` otherwise.]]
 

Modified: trunk/libs/thread/doc/futures.qbk
==============================================================================
--- trunk/libs/thread/doc/futures.qbk	(original)
+++ trunk/libs/thread/doc/futures.qbk	2012-09-18 02:08:11 EDT (Tue, 18 Sep 2012)
@@ -27,22 +27,22 @@
 [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()`]]
+[def __unique_future_get__ [unique_future_get_link `boost::future<R>::get()`]]
 
 [template unique_future_wait_link[link_text] [link thread.synchronization.futures.reference.unique_future.wait [link_text]]]
-[def __unique_future_wait__ [unique_future_wait_link `boost::unique_future<R>::wait()`]]
+[def __unique_future_wait__ [unique_future_wait_link `boost::future<R>::wait()`]]
 
 [template unique_future_is_ready_link[link_text] [link thread.synchronization.futures.reference.unique_future.is_ready [link_text]]]
-[def __unique_future_is_ready__ [unique_future_is_ready_link `boost::unique_future<R>::is_ready()`]]
+[def __unique_future_is_ready__ [unique_future_is_ready_link `boost::future<R>::is_ready()`]]
 
 [template unique_future_has_value_link[link_text] [link thread.synchronization.futures.reference.unique_future.has_value [link_text]]]
-[def __unique_future_has_value__ [unique_future_has_value_link `boost::unique_future<R>::has_value()`]]
+[def __unique_future_has_value__ [unique_future_has_value_link `boost::future<R>::has_value()`]]
 
 [template unique_future_has_exception_link[link_text] [link thread.synchronization.futures.reference.unique_future.has_exception [link_text]]]
-[def __unique_future_has_exception__ [unique_future_has_exception_link `boost::unique_future<R>::has_exception()`]]
+[def __unique_future_has_exception__ [unique_future_has_exception_link `boost::future<R>::has_exception()`]]
 
 [template unique_future_get_state_link[link_text] [link thread.synchronization.futures.reference.unique_future.get_state [link_text]]]
-[def __unique_future_get_state__ [unique_future_get_state_link `boost::unique_future<R>::get_state()`]]
+[def __unique_future_get_state__ [unique_future_get_state_link `boost::future<R>::get_state()`]]
 
 [template shared_future_link[link_text] [link thread.synchronization.futures.reference.shared_future [link_text]]]
 [def __shared_future__ [shared_future_link `boost::shared_future`]]

Modified: trunk/libs/thread/doc/overview.qbk
==============================================================================
--- trunk/libs/thread/doc/overview.qbk	(original)
+++ trunk/libs/thread/doc/overview.qbk	2012-09-18 02:08:11 EDT (Tue, 18 Sep 2012)
@@ -12,7 +12,9 @@
 functions for managing the threads themselves, along with others for synchronizing data between the threads or providing separate
 copies of data specific to individual threads.
 
-The __boost_thread__ library was originally written and designed by William E. Kempf (version 0). Anthony Williams version (version 1) was a major rewrite designed to
+The __boost_thread__ library was originally written and designed by William E. Kempf (version 1). 
+
+Anthony Williams version (version 2) was a major rewrite designed to
 closely follow the proposals presented to the C++ Standards Committee, in particular
 [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2497.html N2497],
 [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2320.html N2320],
@@ -20,8 +22,8 @@
 [@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]
 
-Vicente J. Botet Escriba started in version 3 the adaptation to comply with the accepted Thread C++11 library (Make use of Boost.Chrono and Boost.Move) and the [@http://home.roadrunner.com/~hinnant/bloomington/shared_mutex.html Shared Locking] Howard Hinnant proposal except for the upward conversions.  
-Some minor features have been added also as thread attributes, reverse_lock, shared_lock_guard.
+Vicente J. Botet Escriba started (version 3) the adaptation to comply with the accepted Thread C++11 library (Make use of Boost.Chrono and Boost.Move) and the [@http://home.roadrunner.com/~hinnant/bloomington/shared_mutex.html Shared Locking] Howard Hinnant proposal except for the upward conversions.  
+Some minor non-standard features have been added also as thread attributes, reverse_lock, shared_lock_guard.
 
 In order to use the classes and functions described here, you can
 either include the specific headers specified by the descriptions of

Modified: trunk/libs/thread/doc/thread.qbk
==============================================================================
--- trunk/libs/thread/doc/thread.qbk	(original)
+++ trunk/libs/thread/doc/thread.qbk	2012-09-18 02:08:11 EDT (Tue, 18 Sep 2012)
@@ -169,7 +169,7 @@
 
 
 [def __thread__ [link thread.thread_management.thread `boost::thread`]]
-[def __thread [link thread.thread_management.thread `boost::thread`]]
+[def __thread [link thread.thread_management.thread `thread`]]
 [def __thread_id__ [link thread.thread_management.thread.id `boost::thread::id`]]
 [template join_link[link_text] [link thread.thread_management.thread.join [link_text]]]
 [def __join__ [join_link `join()`]]

Modified: trunk/libs/thread/doc/time.qbk
==============================================================================
--- trunk/libs/thread/doc/time.qbk	(original)
+++ trunk/libs/thread/doc/time.qbk	2012-09-18 02:08:11 EDT (Tue, 18 Sep 2012)
@@ -10,14 +10,16 @@
 As of Boost 1.50.0, the __boost_thread__ library uses Boost.Chrono library for all operations that require a
 time out as defined in the standard c++11. These include (but are not limited to):
 
-* __sleep_for
-* __sleep_until
-* __try_join_for
-* __try_join_until
-* __wait_for
-* __wait_until
-* __try_lock_for
-* __try_lock_until
+* `boost::this_thread::__sleep_for`
+* `boost::this_thread::__sleep_until`
+* `boost::__thread::__try_join_for`
+* `boost::__thread::__try_join_until`
+* `boost::__condition_variable::__wait_for`
+* `boost::__condition_variable::__wait_until`
+* `boost::__condition_variable_any::__cvany_wait_for`
+* `boost::__condition_variable_any::__cvany_wait_until`
+* `__TimedLockable::__try_lock_for`
+* `__TimedLockable::__try_lock_until`
 
 [section:deprecated Deprecated]
 The time related functions introduced in Boost 1.35.0, using the [link date_time Boost.Date_Time] library are deprecated. These include (but are not limited to):