mirror of
https://github.com/boostorg/fiber.git
synced 2026-02-13 00:12:17 +00:00
a0490413cd
Explain "shared state", and provide links to the explanation wherever it's referenced. We don't need the doc to enumerate 'R& future<R&>::get()' or 'void future<void>::get()' separately from 'R future<R>::get()': all three specializations are exactly as the reader expects, given the generic template (unlike shared_future, where it's useful to spell them out). Encapsulate some of the necessary redundancies between future and shared_future documentation. Explain the effect of promise::set_value() vs. promise::set_exception() on each of [shared_]future::get(), get_exception_ptr(), wait(), wait_for() and wait_until(). Add get_exception_ptr() method to shared_future exposition class. Clarify distinction between shared_future move assignment vs. copy assignment. Document that async() is now variadic. Document its StackAllocator overload, and the effect of passing StackAllocator. Remove warning about launch policy 'deferred' since async() has no launch policy parameter.
171 lines
4.8 KiB
Plaintext
171 lines
4.8 KiB
Plaintext
[/
|
|
Copyright Oliver Kowalke 2013.
|
|
Distributed under the Boost Software License, Version 1.0.
|
|
(See accompanying file LICENSE_1_0.txt or copy at
|
|
http://www.boost.org/LICENSE_1_0.txt
|
|
]
|
|
|
|
[#class_packaged_task]
|
|
[section:packaged_task Template `packaged_task<>`]
|
|
|
|
A __packaged_task__ wraps a callable target that returns a value so that the
|
|
return value can be computed asynchronously.
|
|
|
|
template< class R, typename ... Args >
|
|
class packaged_task< R( Args ... ) > {
|
|
public:
|
|
packaged_task() noexcept;
|
|
|
|
template< typename Fn >
|
|
explicit packaged_task( Fn && fn);
|
|
|
|
template< typename Fn, typename Allocator >
|
|
explicit packaged_task( std::allocator_arg_t, Allocator const& alloc, Fn && fn);
|
|
|
|
packaged_task( packaged_task && other) noexcept;
|
|
|
|
packaged_task( packaged_task const& other) = delete;
|
|
|
|
~packaged_task();
|
|
|
|
packaged_task & operator=( packaged_task && other) noexcept;
|
|
|
|
packaged_task & operator=( packaged_task const& other) = delete;
|
|
|
|
void swap( packaged_task & other) noexcept;
|
|
|
|
operator safe_bool() const noexcept;
|
|
|
|
bool operator!() const noexcept;
|
|
|
|
bool valid() const noexcept;
|
|
|
|
future< R > get_future();
|
|
|
|
void operator()( Args && ... args);
|
|
|
|
void reset();
|
|
};
|
|
|
|
[heading Default constructor `packaged_task()`]
|
|
|
|
packaged_task();
|
|
|
|
[variablelist
|
|
[[Effects:] [Constructs an object of class `packaged_task` with no [link shared_state shared state].]]
|
|
[[Throws:] [Nothing.]]
|
|
]
|
|
|
|
[heading Templated constructor `template<> packaged_task()`]
|
|
|
|
template< typename Fn >
|
|
explicit packaged_task( Fn && fn);
|
|
|
|
template< typename Fn, typename Allocator >
|
|
explicit packaged_task( std::allocator_arg_t, Allocator const& alloc, Fn && fn);
|
|
|
|
[variablelist
|
|
[[Effects:] [Constructs an object of class `packaged_task` with a [link shared_state shared state]
|
|
and stores the callable target `fn` internally.]]
|
|
[[Throws:] [Nothing.]]
|
|
[[Note:] [The signature of `Fn` should have a return type convertible to `R`.]]
|
|
]
|
|
|
|
[heading Move constructor]
|
|
|
|
packaged_task( packaged_task && other) noexcept;
|
|
|
|
[variablelist
|
|
[[Effects:] [Creates a packaged_task by moving the [link shared_state shared state] from `other`.]]
|
|
[[Postcondition:] [`other` contains no valid shared state.]]
|
|
[[Throws:] [Nothing.]]
|
|
]
|
|
|
|
[heading Destructor]
|
|
|
|
~packaged_task();
|
|
|
|
[variablelist
|
|
[[Effects:] [Destroys `*this` and abandons the [link shared_state shared state] if shared state is
|
|
ready; otherwise stores __future_error__ with error condition __broken_promise__.]]
|
|
[[Throws:] [Nothing.]]
|
|
]
|
|
|
|
[operator_heading packaged_task..operator_assign..operator=]
|
|
|
|
packaged_task & operator=( packaged_task && other) noexcept;
|
|
|
|
[variablelist
|
|
[[Effects:] [Transfers the ownership of [link shared_state shared state] to `*this`.]]
|
|
[[Postcondition:] [`other` contains no valid shared state.]]
|
|
[[Throws:] [Nothing.]]
|
|
]
|
|
|
|
[member_heading packaged_task..swap]
|
|
|
|
void swap( packaged_task & other) noexcept;
|
|
|
|
[variablelist
|
|
[[Effects:] [Swaps the [link shared_state shared state] between other and `*this`.]]
|
|
[[Throws:] [Nothing.]]
|
|
]
|
|
|
|
[member_heading packaged_task..operator safe_bool]
|
|
|
|
operator safe_bool() const noexcept;
|
|
|
|
[variablelist
|
|
[[Effects:] [Returns `true` if `*this` contains a non-empty [link shared_state shared state].]]
|
|
[[Throws:] [Nothing.]]
|
|
]
|
|
|
|
[operator_heading packaged_task..operator_not..operator!]
|
|
|
|
bool operator!() const noexcept;
|
|
|
|
[variablelist
|
|
[[Effects:] [Returns `true` if `*this` contains an empty [link shared_state shared state].]]
|
|
[[Throws:] [Nothing.]]
|
|
]
|
|
|
|
[member_heading packaged_task..valid]
|
|
|
|
bool valid() const noexcept;
|
|
|
|
[variablelist
|
|
[[Effects:] [Returns `true` if `*this` contains a [link shared_state shared state].]]
|
|
[[Throws:] [Nothing.]]
|
|
]
|
|
|
|
[member_heading packaged_task..get_future]
|
|
|
|
future< R > get_future();
|
|
|
|
[variablelist
|
|
[[Returns:] [A __future__ with the same [link shared_state shared state].]]
|
|
[[Throws:] [__future_error__ with __already_retrieved__ or __no_state__.]]
|
|
]
|
|
|
|
[operator_heading packaged_task..operator_apply..operator()]
|
|
|
|
void operator()( Args && ... args);
|
|
|
|
[variablelist
|
|
[[Effects:] [Invokes the stored callable target. Any exception thrown by the
|
|
callable target `fn` is stored in the [link shared_state shared state]. Otherwise, the value returned
|
|
by `fn` is stored in the shared state.]]
|
|
[[Throws:] [__future_error__ with __no_state__.]]
|
|
]
|
|
|
|
[member_heading packaged_task..reset]
|
|
|
|
void reset();
|
|
|
|
[variablelist
|
|
[[Effects:] [Resets the [link shared_state shared state] and abondons the result of previous
|
|
executions. A new shared state is constructed.]]
|
|
[[Throws:] [__future_error__ with __no_state__.]]
|
|
]
|
|
|
|
[endsect]
|