packaged_task Class

The latest version of this topic can be found at packaged_task Class.

Describes an asynchronous provider that is a call wrapper whose call signature is Ty(ArgTypes...). Its associated asynchronous state holds a copy of its callable object in addition to the potential result.

Syntax

template <class>
class packaged_task;

Members

Public Constructors

Public Methods

Public Operators

Requirements

Header: future

Namespace: std

packaged_task::get_future Method

Returns an object of type future<Ty> that has the same associated asynchronous state.

future<Ty> get_future();

Remarks

If the packaged_task object does not have an associated asynchronous state, this method throws a future_error that has an error code of no_state.

If this method has already been called for a packaged_task object that has the same associated asynchronous state, the method throws a future_error that has an error code of future_already_retrieved.

packaged_task::make_ready_at_thread_exit Method

Calls the callable object that's stored in the associated asynchronous state and atomically stores the returned value.

void make_ready_at_thread_exit(ArgTypes... args);

Remarks

If the packaged_task object doesn't have an associated asynchronous state, this method throws a future_error that has an error code of no_state.

If this method or make_ready_at_thread_exit has already been called for a packaged_task object that has the same associated asynchronous state, the method throws a future_error that has an error code of promise_already_satisfied.

Otherwise, this operator calls INVOKE(fn, args..., Ty), where fn is the callable object that's stored in the associated asynchronous state. Any returned value is stored atomically as the returned result of the associated asynchronous state.

In contrast to packaged_task::operator(), the associated asynchronous state is not set to ready until after all thread-local objects in the calling thread have been destroyed. Typically, threads that are blocked on the associated asynchronous state are not unblocked until the calling thread exits.

packaged_task::operator=

Transfers the associated asynchronous state from a specified object.

packaged_task& operator=(packaged_task&& Right);

Parameters

Right
A packaged_task object.

Return Value

*this

Remarks

After the operation, Right no longer has an associated asynchronous state.

packaged_task::operator()

Calls the callable object that's stored in the associated asynchronous state, atomically stores the returned value, and sets the state to ready.

void operator()(ArgTypes... args);

Remarks

If the packaged_task object doesn't have an associated asynchronous state, this method throws a future_error that has an error code of no_state.

If this method or make_ready_at_thread_exit has already been called for a packaged_task object that has the same associated asynchronous state, the method throws a future_error that has an error code of promise_already_satisfied.

Otherwise, this operator calls INVOKE(fn, args..., Ty), where fn is the callable object that's stored in the associated asynchronous state. Any returned value is stored atomically as the returned result of the associated asynchronous state, and the state is set to ready. As a result, any threads that are blocked on the associated asynchronous state become unblocked.

packaged_task::operator bool

Specifies whether the object has an associated asynchronous state.

operator bool() const noexcept;

Return Value

true if the object has an associated asynchronous state; otherwise, false.

packaged_task::packaged_task Constructor

Constructs a packaged_task object.

packaged_task() noexcept;
packaged_task(packaged_task&& Right) noexcept;
template <class Fn>
explicit packaged_task(Fn&& fn);

template <class Fn, class Alloc>
explicit packaged_task(allocator_arg_t,
    const Alloc& alloc, Fn&& fn);

Parameters

Right
A packaged_task object.

alloc
A memory allocator. For more information, see <allocators>.

fn
A function object.

Remarks

The first constructor constructs a packaged_task object that has no associated asynchronous state.

The second constructor constructs a packaged_task object and transfers the associated asynchronous state from Right. After the operation, Right no longer has an associated asynchronous state.

The third constructor constructs a packaged_task object that has a copy of fn stored in its associated asynchronous state.

The fourth constructor constructs a packaged_task object that has a copy of fn stored in its associated asynchronous state, and uses alloc for memory allocation.

packaged_task::~packaged_task Destructor

Destroys a packaged_task object.

~packaged_task();

Remarks

If the associated asynchronous state is not ready, the destructor stores a future_error exception that has an error code of broken_promise as the result in the associated asynchronous state, and any threads that are blocked on the associated asynchronous state become unblocked.

packaged_task::reset Method

Uses a new associated asynchronous state to replace the existing associated asynchronous state.

void reset();

Remarks

In effect, this method executes *this = packaged_task(move(fn)), where fn is the function object that's stored in the associated asynchronous state for this object. Therefore, the state of the object is cleared, and get_future, operator(), and make_ready_at_thread_exit can be called as if on a newly-constructed object.

packaged_task::swap Method

Exchanges the associated asynchronous state with that of a specified object.

void swap(packaged_task& Right) noexcept;

Parameters

Right
A packaged_task object.

packaged_task::valid Method

Specifies whether the object has an associated asynchronous state.

bool valid() const;

Return Value

true if the object has an associated asynchronous state; otherwise, false.

See Also

Header Files Reference
<future>