Template packaged_task<>

| Home | Libraries | People | FAQ | More

#### 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)`.