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

Subject: [Boost-commit] svn:boost r84544 - trunk/libs/thread/doc
From: vicente.botet_at_[hidden]
Date: 2013-05-29 02:22:45

Author: viboes
Date: 2013-05-29 02:22:44 EDT (Wed, 29 May 2013)
New Revision: 84544
URL: http://svn.boost.org/trac/boost/changeset/84544

Log:
Thread: Added shared_future::then doc.
Text files modified: 
   trunk/libs/thread/doc/changes.qbk    |     6 +                                       
   trunk/libs/thread/doc/future_ref.qbk |    97 +++++++++++++++++++++++++++++++++++---- 
   2 files changed, 89 insertions(+), 14 deletions(-)

Modified: trunk/libs/thread/doc/changes.qbk
==============================================================================
--- trunk/libs/thread/doc/changes.qbk	(original)
+++ trunk/libs/thread/doc/changes.qbk	2013-05-29 02:22:44 EDT (Wed, 29 May 2013)
@@ -15,6 +15,7 @@
 
 * [@http://svn.boost.org/trac/boost/ticket/8273 #8273] Add externally locked streams
 * [@http://svn.boost.org/trac/boost/ticket/8274 #8274] Add concurrent queue
+* [@http://svn.boost.org/trac/boost/ticket/8515 #8515] Async: Add shared_future::then
 * [@http://svn.boost.org/trac/boost/ticket/8518 #8518] Sync: Add a latch class
 * [@http://svn.boost.org/trac/boost/ticket/8615 #8615] Async: Replace make_future/make_shared_future by make_ready_future
 
@@ -406,7 +407,7 @@
   * [@http://svn.boost.org/trac/boost/ticket/8273 #8273] Add externally locked streams
   * [@http://svn.boost.org/trac/boost/ticket/8274 #8274] Add concurrent queue
   * [@http://svn.boost.org/trac/boost/ticket/8518 #8518] Sync: Add a latch class
-  * [@http://svn.boost.org/trac/boost/ticket/XXXX #XXXX] Sync: Add a completion_latch class
+  * [@http://svn.boost.org/trac/boost/ticket/8519 #8519] Sync: Add a completion_latch class
   * [@http://svn.boost.org/trac/boost/ticket/8513 #8513] Async: Add a basic thread_pool executor.
   * [@http://svn.boost.org/trac/boost/ticket/8514 #8514] Async: Add a thread_pool executor with work stealing.
 
@@ -417,7 +418,8 @@
   * [@http://svn.boost.org/trac/boost/ticket/7448 #7448] Async: Add async taking a scheduler parameter.
   * [@http://svn.boost.org/trac/boost/ticket/8515 #8515] Async: Add shared_future::then
   * [@http://svn.boost.org/trac/boost/ticket/8516 #8516] Async: Add future/shared_future::then taking a scheduler as parameter.
-  * [@http://svn.boost.org/trac/boost/ticket/8517 #8517] Async: Add a variadic future/shared_future::then  
+  * [@http://svn.boost.org/trac/boost/ticket/8517 #8517] Async: Add a variadic shared_future::then  
+  * [@http://svn.boost.org/trac/boost/ticket/8627 #8627] Async: Add future<>::unwrap.
 
 
 

Modified: trunk/libs/thread/doc/future_ref.qbk
==============================================================================
--- trunk/libs/thread/doc/future_ref.qbk	(original)
+++ trunk/libs/thread/doc/future_ref.qbk	2013-05-29 02:22:44 EDT (Wed, 29 May 2013)
@@ -269,6 +269,8 @@
       // move support
       __unique_future__(__unique_future__ && other) noexcept;
       __unique_future__& operator=(__unique_future__ && other) noexcept;
+      
+      // factories
       shared_future<R> share();
       template<typename F>
       __unique_future__<typename boost::result_of<F(__unique_future__&)>::type> 
@@ -280,7 +282,7 @@
       __unique_future__<typename boost::result_of<F(__unique_future__&)>::type> 
       then(launch policy, F&& func); // EXTENSION
             
-      void swap(__unique_future__& other) noexcept; // EXTENSION
+      void swap(__unique_future__& other) noexcept;
 
       // retrieving the value
       see below get();
@@ -678,7 +680,7 @@
 
 [endsect]
 
-[section:get_state Member function `get_state()`]
+[section:get_state Member function `get_state()` EXTENSION]
 
     future_state::state get_state();
 
@@ -695,7 +697,7 @@
 
 [endsect]
 
-[section:then Member function `then()`]
+[section:then Member function `then()` EXTENSION]
 
       template<typename F>
       __unique_future__<typename boost::result_of<F(__unique_future__&)>::type> 
@@ -731,23 +733,23 @@
 - When the scheduler or launch policy is not provided the continuation inherits the
 parent's launch policy or scheduler.
 
-- If the parent was created with std::promise or with a packaged_task (has no associated launch policy), the 
-continuation behaves the same as the third overload with a policy argument of launch::async | launch::deferred and 
+- If the parent was created with `promise<<` or with a `packaged_task<>` (has no associated launch policy), the 
+continuation behaves the same as the third overload with a policy argument of `launch::async | launch::deferred` and 
 the same argument for func.
 
-- If the parent has a policy of launch::deferred and the continuation does not have a specified launch policy or 
-scheduler, then the parent is filled by immediately calling .wait(), and the policy of the antecedent is 
-launch::deferred
+- If the parent has a policy of `launch::deferred` and the continuation does not have a specified launch policy or 
+scheduler, then the parent is filled by immediately calling `.wait()`, and the policy of the antecedent is 
+`launch::deferred`.
 
 ]]
 
-[[Returns:] [An object of type future<typename boost::result_of<F(__unique_future__&)> that refers to the shared state created by the continuation.]]
+[[Returns:] [An object of type `__unique_future__<typename boost::result_of<F(__unique_future__&)>` that refers to the shared state created by the continuation.]]
 
 [[Postconditions:] [
 
-- The future object is moved to the parameter of the continuation function .
+- The `shared_future` object passed to the parameter of the continuation function is a copy of the original `shared_future`.
 
-- valid() == false on original future object immediately after it returns.
+- `valid() == false` on original future object immediately after it returns.
 
 ]]
 
@@ -782,6 +784,17 @@
       shared_future& operator=(shared_future && other) noexcept;
       shared_future& operator=(__unique_future__<R> && other) noexcept;
 
+      // factories
+      template<typename F>
+      __unique_future__<typename boost::result_of<F(shared_future&)>::type> 
+      then(F&& func); // EXTENSION
+      template<typename S, typename F>
+      __unique_future__<typename boost::result_of<F(shared_future&)>::type> 
+      then(S& scheduler, F&& func); // EXTENSION NOT_YET_IMPLEMENTED
+      template<typename F>
+      __unique_future__<typename boost::result_of<F(shared_future&)>::type> 
+      then(launch policy, F&& func); // EXTENSION
+
       void swap(shared_future& other);
 
       // retrieving the value
@@ -806,6 +819,7 @@
       bool timed_wait_until(boost::system_time const& abs_time) const;  // DEPRECATED SINCE V3.0.0
     #endif
       state get_state() const noexcept;  // EXTENSION
+            
     };
 
 [section:default_constructor Default Constructor]
@@ -1081,7 +1095,7 @@
 
 [endsect]
 
-[section:get_state Member function `get_state()`]
+[section:get_state Member function `get_state()` EXTENSION]
 
     future_state::state get_state();
 
@@ -1098,6 +1112,65 @@
 
 [endsect]
 
+[section:then Member function `then()` EXTENSION]
+
+      template<typename F>
+      __unique_future__<typename boost::result_of<F(shared_future&)>::type> 
+      then(F&& func); // EXTENSION
+      template<typename S, typename F>
+      __unique_future__<typename boost::result_of<F(shared_future&)>::type> 
+      then(S& scheduler, F&& func); // EXTENSION NOT_YET_IMPLEMENTED
+      template<typename F>
+      __unique_future__<typename boost::result_of<F(shared_future&)>::type> 
+      then(launch policy, F&& func); // EXTENSION
+
+
+[warning These functions are experimental and subject to change in future versions. 
+There are not too much tests yet, so it is possible that you can find out some trivial bugs :(] 
+
+[note These functions are based on the [@http://www.open-std.org/JTC1/SC22/WG21/docs/papers/2013/n3558.pdf [*N3558 - A Standardized Representation of Asynchronous Operations]] C++1y proposal by N. Gustafsson, A. Laksberg, H. Sutter, S. Mithani.]
+
+  
+
+[variablelist
+
+[[Notes:] [The three functions differ only by input parameters. The first only takes a callable object which accepts a 
+shared_future object as a parameter. The second function takes a scheduler as the first parameter and a callable object as 
+the second parameter. The third function takes a launch policy as the first parameter and a callable object as the 
+second parameter.]]
+
+[[Effects:] [
+
+- The continuation is called when the object's shared state is ready (has a value or exception stored).
+
+- The continuation launches according to the specified policy or scheduler.
+
+- When the scheduler or launch policy is not provided the continuation inherits the
+parent's launch policy or scheduler.
+
+- If the parent was created with `promise` or with a `packaged_task` (has no associated launch policy), the 
+continuation behaves the same as the third overload with a policy argument of `launch::async | launch::deferred` and 
+the same argument for func.
+
+- If the parent has a policy of `launch::deferred` and the continuation does not have a specified launch policy or 
+scheduler, then the parent is filled by immediately calling `.wait()`, and the policy of the antecedent is 
+`launch::deferred`
+
+]]
+
+[[Returns:] [An object of type `__unique_future__<typename boost::result_of<F(shared_future&)>` that refers to the shared state created by the continuation.]]
+
+[[Postconditions:] [
+
+- The future object is moved to the parameter of the continuation function .
+
+- `valid() == false` on original future object immediately after it returns.
+
+]]
+
+]
+
+[endsect]
 
 [endsect]