packaged_task Class

 

The new home for Visual Studio documentation is Visual Studio 2017 Documentation on docs.microsoft.com.

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.

template <class>
class packaged_task;

Public Constructors

NameDescription
packaged_task::packaged_task ConstructorConstructs a packaged_task object.
packaged_task::~packaged_task DestructorDestroys a packaged_task object.

Public Methods

NameDescription
packaged_task::get_future MethodReturns a future object that has the same associated asynchronous state.
packaged_task::make_ready_at_thread_exit MethodCalls the callable object that's stored in the associated asynchronous state and atomically stores the returned value.
packaged_task::reset MethodReplaces the associated asynchronous state.
packaged_task::swap MethodExchanges the associated asynchronous state with that of a specified object.
packaged_task::valid MethodSpecifies whether the object has an associated asynchronous state.

Public Operators

NameDescription
packaged_task::operator=Transfers an associated asynchronous state from a specified object.
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.
packaged_task::operator boolSpecifies whether the object has an associated asynchronous state.

Header: future

Namespace: std

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.

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.

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.

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.

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.

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.

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.

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.

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

void swap(packaged_task& Right) noexcept;

Parameters

Right
A packaged_task object.

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.

Header Files Reference
<future>

Show: