Boost C++ Libraries

...one of the most highly regarded and expertly designed C++ library projects in the world. Herb Sutter and Andrei Alexandrescu, C++ Coding Standards

This is the documentation for a snapshot of the develop branch, built from commit 4e6c143b17.
PrevUpHomeNext

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:

  1. Instantiate packaged_task<> with template arguments matching the signature of the callable. Pass the callable to the constructor.
  2. Call packaged_task::get_future() and capture the returned future<> instance.
  3. Launch a fiber to run the new packaged_task<>, passing any arguments required by the original callable.
  4. Call fiber::detach() on the newly-launched fiber.
  5. 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).


PrevUpHomeNext