|
|
Boost-Commit : |
Subject: [Boost-commit] svn:boost r80823 - trunk/libs/thread/doc
From: vicente.botet_at_[hidden]
Date: 2012-10-03 01:43:39
Author: viboes
Date: 2012-10-03 01:43:38 EDT (Wed, 03 Oct 2012)
New Revision: 80823
URL: http://svn.boost.org/trac/boost/changeset/80823
Log:
Thread: Update doc
Text files modified:
trunk/libs/thread/doc/changes.qbk | 15 +-
trunk/libs/thread/doc/configuration.qbk | 66 +++++++++++-
trunk/libs/thread/doc/future_ref.qbk | 199 ++++++++++++++++++++++++++++++---------
trunk/libs/thread/doc/futures.qbk | 36 +++++++
4 files changed, 254 insertions(+), 62 deletions(-)
Modified: trunk/libs/thread/doc/changes.qbk
==============================================================================
--- trunk/libs/thread/doc/changes.qbk (original)
+++ trunk/libs/thread/doc/changes.qbk 2012-10-03 01:43:38 EDT (Wed, 03 Oct 2012)
@@ -22,7 +22,6 @@
New Features:
-
* [@http://svn.boost.org/trac/boost/ticket/7281 #7281] C++11 compliance: Add ArgTypes to packaged_task template.
Provided when BOOST_THREAD_PROVIDES_SIGNATURE_PACKAGED_TASK is defined (Default value from Boost 1.55).
See BOOST_THREAD_PROVIDES_SIGNATURE_PACKAGED_TASK and BOOST_THREAD_DONT_PROVIDE_SIGNATURE_PACKAGED_TASK.
@@ -37,6 +36,7 @@
See BOOST_THREAD_PROVIDES_SIGNATURE_PACKAGED_TASK and BOOST_THREAD_DONT_PROVIDE_SIGNATURE_PACKAGED_TASK, BOOST_THREAD_PROVIDES_VARIADIC_THREAD and BOOST_THREAD_DONT_PROVIDE_VARIADIC_THREAD.
* [@http://svn.boost.org/trac/boost/ticket/7414 #7414] c++11 compliance: future::get post-condition should be valid()==false
+* [@http://svn.boost.org/trac/boost/ticket/7414 #7444] Async: Add make_future/make_shared_future
[/* [@http://svn.boost.org/trac/boost/ticket/7413 #7413] c++11 compliance: Add async when the launch policy is deferred.]
@@ -306,16 +306,17 @@
* [@http://svn.boost.org/trac/boost/ticket/7413 #7413] c++11 compliance: Add async when the launch policy is deferred.
* [@http://svn.boost.org/trac/boost/ticket/7280 #7280] C++11 compliance: Add promise::...at_thread_exit functions.
* [@http://svn.boost.org/trac/boost/ticket/7282 #7282] C++11 compliance: Add packaged_task::make_ready_at_thread_exit function.
- * [@http://svn.boost.org/trac/boost/ticket/7285 #7285] Allow to pass movable arguments for call_once.
- * [@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/7285 #7285] C++11 compliance: Allow to pass movable arguments for call_once.
+ * [@http://svn.boost.org/trac/boost/ticket/6227 #6227] C++11 compliance: Use of variadic templates on Generic Locking Algorithms on compilers providing them.
# Add some of the extension proposed in [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2012/n3428.pdf A Standardized Representation of Asynchronous Operations], in particular
- * make_future/make_shared_future,
- * future<T>.then,
- * when_any/when_all,
- * scheduler (in the form of an asynchronous executor as defined in Boost.Async).
+ * [@http://svn.boost.org/trac/boost/ticket/7445 #7445] Async: Add future<>.then
+ * [@http://svn.boost.org/trac/boost/ticket/7446 #7446] Async: Add when_any
+ * [@http://svn.boost.org/trac/boost/ticket/7447 #7447] Async: Add when_all
+ * [@http://svn.boost.org/trac/boost/ticket/7448 #7448] Async: Add async taking a scheduler parameter
+
# Add a synchronized value class following the design in [@http://www.drdobbs.com/cpp/enforcing-correct-mutex-usage-with-synch/225200269 Enforcing Correct Mutex Usage with Synchronized Values]
Modified: trunk/libs/thread/doc/configuration.qbk
==============================================================================
--- trunk/libs/thread/doc/configuration.qbk (original)
+++ trunk/libs/thread/doc/configuration.qbk 2012-10-03 01:43:38 EDT (Wed, 03 Oct 2012)
@@ -18,6 +18,8 @@
[endsect]
+
+
[section:move Boost.Move]
Boost.Thread uses by default an internal move semantic implementation. Since version 3.0.0 you can use the move emulation emulation provided by Boost.Move.
@@ -27,6 +29,11 @@
[endsect]
+[section:id thread::id]
+
+Boost.Thread uses by default a thread::id on Posix based on the pthread type (BOOST_THREAD_PROVIDES_BASIC_THREAD_ID). For backward compatibility and also for compilers that don't work well with this modification the user can define `BOOST_THREAD_DONT_PROVIDE_BASIC_THREAD_ID`.
+
+[endsect]
[section:shared_gen Shared Locking Generic]
The shared mutex implementation on Windows platform provides currently less functionality than the generic one that is used for PTheads based platforms. In order to have access to these functions, the user needs to define `BOOST_THREAD_PROVIDES_GENERIC_SHARED_MUTEX_ON_WIN` to use the generic implementation, that while could be less efficient, provides all the functions.
@@ -148,12 +155,40 @@
[endsect]
-[section:deprecated Deprecated]
-Version 3.0.0 deprecates some Boost.Thread features.
+[section:deprecated Signature parameter for packaged_task]
+
+C++11 packaged task class has a Signature template parameter. When `BOOST_THREAD_PROVIDES_SIGNATURE_PACKAGED_TASK ` is defined Boost.Thread provides this C++ feature.
+
+[waring This is a breaking change respect to version 3.x.]
+
+When `BOOST_THREAD_VERSION<=3` define `BOOST_THREAD_PROVIDES_SIGNATURE_PACKAGED_TASK` if you want this feature.
+When `BOOST_THREAD_VERSION>4` define `BOOST_THREAD_DONT_PROVIDE_SIGNATURE_PACKAGED_TASK` if you don't want this feature.
+
+[endsect]
+
+
+[section:thread_const-var thread constructor with variadic rvalue parameters]
+
+C++11 thread constructor accep a variable number of rvalue argumentshas. When `BOOST_THREAD_PROVIDES_VARIADIC_THREAD ` is defined Boost.Thread provides this C++ feature if the following are not defined
+
+* BOOST_NO_CXX11_VARIADIC_TEMPLATES
+* BOOST_NO_CXX11_DECLTYPE
+* BOOST_NO_CXX11_RVALUE_REFERENCES
+* BOOST_NO_CXX11_HDR_TUPLE
+
+When `BOOST_THREAD_VERSION>4` define `BOOST_THREAD_DONT_PROVIDE_SIGNATURE_PACKAGED_TASK` if you don't want this feature.
+
+[endsect]
+
+[section:get_invalid future<>::get() invalidates the future]
+
+C++11 future<>::get() invalidates the future once its value has been obtained. When `BOOST_THREAD_PROVIDES_FUTURE_INVALID_AFTER_GET ` is defined Boost.Thread provides this C++ feature.
-These deprecated features will be provided by default up to boost 1.52. If you don't want to include the deprecated features you could define `BOOST_THREAD_DONT_PROVIDE_DEPRECATED_FEATURES_SINCE_V3_0_0`. Since 1.53 these features will not be included any more by default. Since this version, if you want to include the deprecated features yet you could define `BOOST_THREAD_PROVIDE_DEPRECATED_FEATURES_SINCE_V3_0_0`. These deprecated features will be only available until boost 1.55, that is you have 1 year and a half to move to the new features.
+[waring This is a breaking change respect to version 3.x.]
+When `BOOST_THREAD_VERSION<=3` define `BOOST_THREAD_PROVIDES_FUTURE_INVALID_AFTER_GET` if you want this feature.
+When `BOOST_THREAD_VERSION>4` define `BOOST_THREAD_DONT_PROVIDE_FUTURE_INVALID_AFTER_GET` if you don't want this feature.
[endsect]
@@ -169,19 +204,26 @@
The user can request the version 3 by defining `BOOST_THREAD_VERSION` to 3. In this case the following breaking or extending macros are defined if the opposite is not requested:
* Breaking change `BOOST_THREAD_PROVIDES_EXPLICIT_LOCK_CONVERSION `
-* Breaking change `BOOST_THREAD_PROVIDES_FUTURE`
+* Conformity & Breaking change `BOOST_THREAD_PROVIDES_FUTURE`
* Uniformity `BOOST_THREAD_PROVIDES_GENERIC_SHARED_MUTEX_ON_WIN`
* Extension `BOOST_THREAD_PROVIDES_SHARED_MUTEX_UPWARDS_CONVERSION`
* Conformity `BOOST_THREAD_PROVIDES_FUTURE_CTOR_ALLOCATORS`
-* Breaking change BOOST_THREAD_PROVIDES_THREAD_DESTRUCTOR_CALLS_TERMINATE_IF_JOINABLE
-* Breaking change BOOST_THREAD_PROVIDES_THREAD_MOVE_ASSIGN_CALLS_TERMINATE_IF_JOINABLE
-* Breaking change `BOOST_THREAD_PROVIDES_ONCE_CXX11`
+* Conformity & Breaking change BOOST_THREAD_PROVIDES_THREAD_DESTRUCTOR_CALLS_TERMINATE_IF_JOINABLE
+* Conformity & Breaking change BOOST_THREAD_PROVIDES_THREAD_MOVE_ASSIGN_CALLS_TERMINATE_IF_JOINABLE
+* Conformity & Breaking change `BOOST_THREAD_PROVIDES_ONCE_CXX11`
* Breaking change `BOOST_THREAD_DONT_PROVIDE_PROMISE_LAZY`
* Breaking change `BOOST_THREAD_DONT_PROVIDE_DEPRECATED_FEATURES_SINCE_V3_0_0`
The default value for `BOOST_THREAD_VERSION` will be changed to 3 since Boost 1.53.
+The user can request the version 4 by defining `BOOST_THREAD_VERSION` to 4. In this case the following breaking or extending macros are defined if the opposite is not requested:
+
+* Conformity & Breaking change `BOOST_THREAD_PROVIDES_SIGNATURE_PACKAGED_TASK `
+* Conformity & Breaking change `BOOST_THREAD_PROVIDES_FUTURE_INVALID_AFTER_GET `
+* Conformity `BOOST_THREAD_PROVIDES_VARIADIC_THREAD`
+
+
[endsect]
[endsect]
@@ -210,5 +252,15 @@
And Boost.Thread doesn't links with Boost.Chrono.
+
[endsect]
+[section:ce WCE]
+
+If _WIN32_WCE && _WIN32_WCE==0x501 the library defines
+
+* `BOOST_THREAD_DONT_PROVIDE_FUTURE_CTOR_ALLOCATORS`
+
+
+[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-10-03 01:43:38 EDT (Wed, 03 Oct 2012)
@@ -12,12 +12,10 @@
namespace boost
{
- #if defined BOOST_THREAD_PROVIDES_DEPRECATED_FEATURES_SINCE_V3_0_0
- namespace future_state
+ namespace future_state // EXTENSION
{
enum state {uninitialized, waiting, ready, moved};
}
- #endif
enum class future_errc
{
@@ -83,27 +81,31 @@
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>
- // async(launch policy, 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>
+ async(F&& f, Args&&... args);
+ 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);
+
template<typename Iterator>
void wait_for_all(Iterator begin,Iterator end); // EXTENSION
-
template<typename F1,typename... FS>
void wait_for_all(F1& f1,Fs&... fs); // EXTENSION
template<typename Iterator>
Iterator wait_for_any(Iterator begin,Iterator end);
-
template<typename F1,typename... Fs>
unsigned wait_for_any(F1& f1,Fs&... fs);
-
-
+
+ template <typename T>
+ future<typename decay<T>::type> make_future(T&& value); // EXTENSION
+ future<void> make_future(); // EXTENSION
+
+ template <typename T>
+ shared_future<typename decay<T>::type> make_shared_future(T&& value); // EXTENSION
+ shared_future<void> make_shared_future(); // EXTENSION
+
[section:future_state Enumeration `state`]
namespace future_state
@@ -280,13 +282,11 @@
#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;
- #endif
- #if defined BOOST_THREAD_PROVIDES_DEPRECATED_FEATURES_SINCE_V3_0_0
- typedef future_state::state state;
- state get_state() const;
+ bool timed_wait(Duration const& rel_time) const; // DEPRECATED SINCE V3.0.0
+ bool timed_wait_until(boost::system_time const& abs_time) const; // DEPRECATED SINCE V3.0.0
#endif
+ typedef future_state::state state; // EXTENSION
+ state get_state() const; // EXTENSION
};
[section:default_constructor Default Constructor]
@@ -430,7 +430,7 @@
[endsect]
-[section:timed_wait_duration Member function `timed_wait()`]
+[section:timed_wait_duration Member function `timed_wait()` DEPRECATED SINCE V3.0.0]
template<typename Duration>
bool timed_wait(Duration const& wait_duration);
@@ -457,7 +457,7 @@
[endsect]
-[section:timed_wait_absolute Member function `timed_wait()`]
+[section:timed_wait_absolute Member function `timed_wait()` DEPRECATED SINCE V3.0.0]
bool timed_wait(boost::system_time const& wait_timeout);
@@ -672,12 +672,10 @@
#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;
- #endif
- #if defined BOOST_THREAD_PROVIDES_DEPRECATED_FEATURES_SINCE_V3_0_0
- state get_state() const noexcept;
+ bool timed_wait(Duration const& rel_time) const; // DEPRECATED SINCE V3.0.0
+ 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]
@@ -1378,17 +1376,28 @@
template <class F>
__unique_future__<typename result_of<typename decay<F>::type()>::type>
- async(F f);
+ async(F&& f);
template <class F>
__unique_future__<typename result_of<typename decay<F>::type()>::type>
- async(launch policy, F f);
+ async(launch policy, F&& f);
+ template <class F, class... Args>
+ __unique_future__<typename result_of<typename decay<F>::type(typename decay<Args>::type...)>::type>
+ async(F&& f, Args&&... args);
+ template <class F, class... Args>
+ __unique_future__<typename result_of<typename decay<F>::type(typename decay<Args>::type...)>::type>
+ async(launch policy, F&& f, Args&&... args);
+
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!]
+[warning the variadic prototype is provided only on C++11 compilers supporting rvalue references, variadic templates, decltype and a standard library providing <tuple>, and BOOST_THREAD_PROVIDES_SIGNATURE_PACKAGED_TASK is defined.]
+
+[heading Non-Variadic variant]
+
[variablelist
[[Requires:] [
@@ -1440,38 +1449,69 @@
]
-[/
+[heading Variadic variant]
[variablelist
-[[Requires:] [F and each Ti in Args shall satisfy the MoveConstructible requirements. invoke (decay_copy (boost::forward<F>(f)), decay_copy (boost::forward<Args>(args))...) shall be a valid expression.
+[[Requires:] [
+`F` and each `Ti` in `Args` shall satisfy the `MoveConstructible` requirements.
+
+ invoke (decay_copy (boost::forward<F>(f)), decay_copy (boost::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 (boost::forward<F>(f)), decay_copy (boost::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(boost::forward<F>(f)), decay_copy (boost::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 (boost::forward<F>(f)) and decay_copy (boost::forward<Args>(args))... in the shared state. These copies of f and args constitute a deferred function. Invocation of the deferred function evaluates invoke (boost::move(g), boost::move(xyz)) where g is the stored value of decay_copy (boost::forward<F>(f)) and xyz is the stored copy of decay_copy (boost::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 (boost::move(g), boost::move(xyz)) begins, the function is no longer considered deferred.
+[[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(forward<F>(f)), decay_copy (forward<Args>(args))...)`
+ 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 `invoke(decay_copy(boost::forward<F>(f)), decay_copy (boost::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(forward<F>(f))` and `decay_copy(forward<Args>(args))...` in the shared state.
+ These copies of `f` and `args` constitute a deferred function. Invocation of the deferred function evaluates
+ `invoke(move(g), move(xyz))` where `g` is the stored value of `decay_copy(forward<F>(f))` and `xyz` is the stored copy of `decay_copy(forward<Args>(args))...`.
+ 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 `invoke(move(g), 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.]]
+[[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 decay<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.
+- 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.
+[[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.
+- `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 boost::launch.
@@ -1479,10 +1519,6 @@
]
-]
-
-
-
[endsect]
@@ -1562,5 +1598,72 @@
[endsect]
+[section:make_future Non-member function `make_future()`]
+
+ template <typename T>
+ future<typename decay<T>::type> make_future(T&& value); // EXTENSION
+ future<void> make_future(); // EXTENSION
+
+
+[variablelist
+
+[[Effects:] [
+The value that is passed in to the function is moved to the shared state of the returned function if it is an rvalue.
+Otherwise the value is copied to the shared state of the returned function.
+.]]
+
+[[Returns:] [
+
+- future<T>, if function is given a value of type T
+
+- future<void>, if the function is not given any inputs.
+
+]]
+
+[[Postcondition:] [
+
+- Returned future<T>, valid() == true
+
+- Returned future<T>, is_ready() = true
+
+]]
+
+]
+
+
+[endsect]
+[section:make_shared_future Non-member function `make_shared_future()`]
+
+ template <typename T>
+ shared_future<typename decay<T>::type> make_shared_future(T&& value); // EXTENSION
+ shared_future<void> make_shared_future(); // EXTENSION
+
+[variablelist
+
+[[Effects:] [
+The value that is passed in to the function is moved to the shared state of the returned function if it is an rvalue.
+Otherwise the value is copied to the shared state of the returned function.
+.]]
+
+[[Returns:] [
+
+- shared_future<T>, if function is given a value of type T
+
+- shared_future<void>, if the function is not given any inputs.
+
+]]
+
+[[Postcondition:] [
+
+- Returned shared_future<T>, valid() == true
+
+- Returned shared_future<T>, is_ready() = true
+
+]]
+
+]
+
+[endsect]
+
[endsect]
Modified: trunk/libs/thread/doc/futures.qbk
==============================================================================
--- trunk/libs/thread/doc/futures.qbk (original)
+++ trunk/libs/thread/doc/futures.qbk 2012-10-03 01:43:38 EDT (Wed, 03 Oct 2012)
@@ -184,6 +184,42 @@
[endsect]
+[section:async Executing asynchronously]
+[endsect]
+
+[section:make_future Making immediate futures easier]
+
+Some functions may know the value at the point of construction. In these cases the value is immediately available,
+but needs to be returned as a future or shared_future. By using make_future (make_shared_future) a future (shared_future)
+can be created which holds a pre-computed result in its shared state.
+
+Without these features it is non-trivial to create a future directly from a value.
+First a promise must be created, then the promise is set, and lastly the future is retrieved from the promise.
+This can now be done with one operation.
+
+[heading make_future / make_shared_future]
+
+This function creates a future for a given value. If no value is given then a future<void> is returned.
+This function is primarily useful in cases where sometimes, the return value is immediately available, but sometimes
+it is not. The example below illustrates, that in an error path the value is known immediately, however in other paths
+the function must return an eventual value represented as a future.
+
+
+ boost::future<int> compute(int x)
+ {
+ if (x == 0) return boost::make_future(0);
+ if (x < 0) return boost::make_future(-1);
+ boost::future<int> f1 = boost::async([]() { return x+1; });
+ return f1;
+ }
+
+There are two variations of this function. The first takes a value of any type, and returns a future of that type.
+The input value is passed to the shared state of the returned future. The second version takes no input and returns a future<void>.
+make_shared_future has the same functionality as make_future, except has a return type of shared_future.
+
+
+[endsect]
+
[include future_ref.qbk]
[endsect]
\ No newline at end of file
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