32 Thread support library [thread]

32.9 Futures [futures]

32.9.10 Class template packaged_­task [futures.task]

32.9.10.1 General [futures.task.general]

1
#
The class template packaged_­task defines a type for wrapping a function or callable object so that the return value of the function or callable object is stored in a future when it is invoked.
2
#
When the packaged_­task object is invoked, its stored task is invoked and the result (whether normal or exceptional) stored in the shared state.
Any futures that share the shared state will then be able to access the stored result.
namespace std { template<class> class packaged_task; // not defined template<class R, class... ArgTypes> class packaged_task<R(ArgTypes...)> { public: // construction and destruction packaged_task() noexcept; template<class F> explicit packaged_task(F&& f); ~packaged_task(); // no copy packaged_task(const packaged_task&) = delete; packaged_task& operator=(const packaged_task&) = delete; // move support packaged_task(packaged_task&& rhs) noexcept; packaged_task& operator=(packaged_task&& rhs) noexcept; void swap(packaged_task& other) noexcept; bool valid() const noexcept; // result retrieval future<R> get_future(); // execution void operator()(ArgTypes... ); void make_ready_at_thread_exit(ArgTypes...); void reset(); }; template<class R, class... ArgTypes> void swap(packaged_task<R(ArgTypes...)>& x, packaged_task<R(ArgTypes...)>& y) noexcept; }

32.9.10.2 Member functions [futures.task.members]

🔗
packaged_task() noexcept;
1
#
Effects: The object has no shared state and no stored task.
🔗
template<class F> packaged_task(F&& f);
2
#
Constraints: remove_­cvref_­t<F> is not the same type as packaged_­task<R(ArgTypes...)>.
3
#
Mandates: is_­invocable_­r_­v<R, F&, ArgTypes...> is true.
4
#
Preconditions: Invoking a copy of f behaves the same as invoking f.
5
#
Effects: Constructs a new packaged_­task object with a shared state and initializes the object's stored task with std​::​forward<F>(f).
6
#
Throws: Any exceptions thrown by the copy or move constructor of f, or bad_­alloc if memory for the internal data structures could not be allocated.
🔗
packaged_task(packaged_task&& rhs) noexcept;
7
#
Effects: Transfers ownership of rhs's shared state to *this, leaving rhs with no shared state.
Moves the stored task from rhs to *this.
8
#
Postconditions: rhs has no shared state.
🔗
packaged_task& operator=(packaged_task&& rhs) noexcept;
9
#
Effects:
🔗
~packaged_task();
10
#
Effects: Abandons any shared state ([futures.state]).
🔗
void swap(packaged_task& other) noexcept;
11
#
Effects: Exchanges the shared states and stored tasks of *this and other.
12
#
Postconditions: *this has the same shared state and stored task (if any) as other prior to the call to swap.
other has the same shared state and stored task (if any) as *this prior to the call to swap.
🔗
bool valid() const noexcept;
13
#
Returns: true only if *this has a shared state.
🔗
future<R> get_future();
14
#
Returns: A future object that shares the same shared state as *this.
15
#
Synchronization: Calls to this function do not introduce data races ([intro.multithread]) with calls to operator() or make_­ready_­at_­thread_­exit.
[Note 1:
Such calls need not synchronize with each other.
— end note]
16
#
Throws: A future_­error object if an error occurs.
17
#
Error conditions:
  • (17.1)
    future_­already_­retrieved if get_­future has already been called on a packaged_­task object with the same shared state as *this.
  • (17.2)
    no_­state if *this has no shared state.
🔗
void operator()(ArgTypes... args);
18
#
Effects: As if by INVOKE<R>(f, t, t, …, t) ([func.require]), where f is the stored task of *this and t, t, …, t are the values in args....
If the task returns normally, the return value is stored as the asynchronous result in the shared state of *this, otherwise the exception thrown by the task is stored.
The shared state of *this is made ready, and any threads blocked in a function waiting for the shared state of *this to become ready are unblocked.
19
#
Throws: A future_­error exception object if there is no shared state or the stored task has already been invoked.
20
#
Error conditions:
  • (20.1)
    promise_­already_­satisfied if the stored task has already been invoked.
  • (20.2)
    no_­state if *this has no shared state.
🔗
void make_ready_at_thread_exit(ArgTypes... args);
21
#
Effects: As if by INVOKE<R>(f, t, t, …, t) ([func.require]), where f is the stored task and t, t, …, t are the values in args....
If the task returns normally, the return value is stored as the asynchronous result in the shared state of *this, otherwise the exception thrown by the task is stored.
In either case, this is done without making that state ready ([futures.state]) immediately.
Schedules the shared state to be made ready when the current thread exits, after all objects of thread storage duration associated with the current thread have been destroyed.
22
#
Throws: future_­error if an error condition occurs.
23
#
Error conditions:
  • (23.1)
    promise_­already_­satisfied if the stored task has already been invoked.
  • (23.2)
    no_­state if *this has no shared state.
🔗
void reset();
24
#
Effects: As if *this = packaged_­task(std​::​move(f)), where f is the task stored in *this.
[Note 2:
This constructs a new shared state for *this.
The old state is abandoned ([futures.state]).
— end note]
25
#
Throws:
  • (25.1)
    bad_­alloc if memory for the new shared state could not be allocated.
  • (25.2)
    any exception thrown by the move constructor of the task stored in the shared state.
  • (25.3)
    future_­error with an error condition of no_­state if *this has no shared state.

32.9.10.3 Globals [futures.task.nonmembers]

🔗
template<class R, class... ArgTypes> void swap(packaged_task<R(ArgTypes...)>& x, packaged_task<R(ArgTypes...)>& y) noexcept;
1
#
Effects: As if by x.swap(y).