C++ Reference ยท Concurrency
C++ std::packaged_task class
Reference for std::packaged_task: wrap any callable so that calling it stores the result in a future, run it on a thread or queue, reset it and handle exceptions.
std::packaged_task<R(Args...)> (header <future>) wraps a callable together with a hidden promise. Calling the task runs the callable and stores its return value, or the exception it threw, in a shared state that you read through the future from get_future(). The task itself does not start any thread: you decide where and when to call it.
This separation makes packaged_task the right building block for thread pools and task queues. The queue stores packaged_task objects; workers pop and invoke them; the code that enqueued the task keeps the future. It is move-only, so queue items are usually std::moved or wrapped in a std::move_only_function.
std::packaged_task<int(int, int)> task([](int a, int b) { return a + b; }); std::future<int> result = task.get_future(); task(2, 3); // runs now, in this thread int five = result.get();
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with std::cin or std::getline), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with std::cin or std::getline), it gets the next line from this box.
Syntax
template<class R, class... Args> class packaged_task<R(Args...)> { public: packaged_task() noexcept; template<class F> explicit packaged_task(F&& f); packaged_task(packaged_task&&) noexcept; packaged_task(const packaged_task&) = delete; bool valid() const noexcept; std::future<R> get_future(); void operator()(Args... args); void make_ready_at_thread_exit(Args... args); void reset(); void swap(packaged_task&) noexcept; };
| Name | Description |
|---|---|
F |
Any callable whose call with Args... returns something convertible to R. |
get_future() |
Returns the future for the result. May be called once per shared state. |
operator() |
Invokes the callable and stores the result or exception. |
reset() |
Discards the old shared state and creates a new one, so the task can run again. |
valid() |
true if the task has a shared state (it does not after being moved from). |
Returns: operator() returns nothing; the result goes to the future. Errors: std::future_error with promise_already_satisfied if the task is called twice without reset(), no_state if invalid, future_already_retrieved if get_future() is called twice.
Usage notes
- No thread is created.
packaged_taskonly connects a callable to a future; comparestd::async, which also starts the work. - Move-only: pass it to
std::threador containers withstd::move. Astd::functioncannot hold it (it requires copyable callables);std::move_only_function(C++23) can. - Exceptions are captured and rethrown by
future.get(), so a worker thread does not terminate on a failing job. - Destroying an unrun task with a future still alive makes
get()throwbroken_promise. - The future's destructor does not block for a
packaged_task(unlike a future fromasync). - Thread pools: typical design is a mutex, a condition variable and a queue of tasks, as in the second example plus the pattern from
condition_variable. - Signature matters: the task type is
packaged_task<int(int)>, notpackaged_task<decltype(f)>for a lambda.