Skip to content
Tutorials Center
My learning

Topics

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.

C++
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

C++ Run a task on a thread of your choice

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.

C++ A tiny task queue

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

C++
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_task only connects a callable to a future; compare std::async, which also starts the work.
  • Move-only: pass it to std::thread or containers with std::move. A std::function cannot 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() throw broken_promise.
  • The future's destructor does not block for a packaged_task (unlike a future from async).
  • 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)>, not packaged_task<decltype(f)> for a lambda.