Template 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.

Conventional usage of packaged_task<> is like this:

Instantiate packaged_task<> with template arguments matching the signature of the callable. Pass the callable to the constructor.
Call packaged_task::get_future() and capture the returned future<> instance.
Launch a fiber to run the new packaged_task<>, passing any arguments required by the original callable.
Call fiber::detach() on the newly-launched fiber.
At some later point, retrieve the result from the future<>.

This is, in fact, pretty much what fibers::async() encapsulates.

#include <boost/fiber/future/packaged_task.hpp>

namespace boost {
namespace fibers {

template< class R, typename ... Args >
class packaged_task< R( Args ... ) > {
public:
    packaged_task() noexcept;

    template< typename Fn >
    explicit packaged_task( Fn &&);

    template< typename Fn, typename Allocator >
    packaged_task( std::allocator_arg_t, Allocator const&, Fn &&);

    packaged_task( packaged_task &&) noexcept;

    packaged_task & operator=( packaged_task &&) noexcept;

    packaged_task( packaged_task const&) = delete;

    packaged_task & operator=( packaged_task const&) = delete;

    ~packaged_task();

    void swap( packaged_task &) noexcept;

    bool valid() const noexcept;

    future< R > get_future();

    void operator()( Args ...);

    void reset();
};

template< typename Signature >
void swap( packaged_task< Signature > &, packaged_task< Signature > &) noexcept;

}}

Default constructor `packaged_task()`

packaged_task() noexcept;

Effects:: Constructs an object of class packaged_task with no shared state.
Throws:: Nothing.

Templated constructor `packaged_task()`

template< typename Fn >
explicit packaged_task( Fn && fn);

template< typename Fn, typename Allocator >
packaged_task( std::allocator_arg_t, Allocator const& alloc, Fn && fn);

Effects:: Constructs an object of class packaged_task with a shared state and copies or moves the callable target fn to internal storage.
Throws:: Exceptions caused by memory allocation.
Note:: The signature of Fn should have a return type convertible to R.
See also:: std::allocator_arg_t

Move constructor

packaged_task( packaged_task && other) noexcept;

Effects:: Creates a packaged_task by moving the shared state from other.
Postcondition:: other contains no valid shared state.
Throws:: Nothing.

Destructor

~packaged_task();

Effects:: Destroys *this and abandons the shared state if shared state is ready; otherwise stores future_error with error condition future_errc::broken_promise as if by promise::set_exception(): the shared state is set ready.

Member function `operator=`()

packaged_task & operator=( packaged_task && other) noexcept;

Effects:: Transfers the ownership of shared state to *this.
Postcondition:: other contains no valid shared state.
Throws:: Nothing.

Member function `swap`()

void swap( packaged_task & other) noexcept;

Effects:: Swaps the shared state between other and *this.
Throws:: Nothing.

Member function `valid`()

bool valid() const noexcept;

Effects:: Returns true if *this contains a shared state.
Throws:: Nothing.

Member function `get_future`()

future< R > get_future();

Returns:: A future<> with the same shared state.
Throws:: future_error with future_errc::future_already_retrieved or future_errc::no_state.

Member function `operator()`()

void operator()( Args && ... args);

Effects:: Invokes the stored callable target. Any exception thrown by the callable target fn is stored in the shared state as if by promise::set_exception(). Otherwise, the value returned by fn is stored in the shared state as if by promise::set_value().
Throws:: future_error with future_errc::no_state.

Member function `reset`()

void reset();

Effects:: Resets the shared state and abandons the result of previous executions. A new shared state is constructed.
Throws:: future_error with future_errc::no_state.

Non-member function `swap()`

template< typename Signature >
void swap( packaged_task< Signature > & l, packaged_task< Signature > & r) noexcept;

Effects:: Same as l.swap( r).