# Futures, promises and async

> A future and its provider share one heap-allocated state that carries exactly one value or exception from one thread to another. This page covers promise, packaged_task and std::async, the launch-policy and destructor traps, the future_error cases, and why standard futures cannot be chained.

- **Source:** C++ Atlas (https://cppatlas.com/topics/futures-promises-and-async)
- **Track:** Concurrency
- **Estimated reading time:** 13 minutes
- **ISO C++ clauses:** [futures.state] (https://eel.is/c++draft/futures.state), [futures.errors] (https://eel.is/c++draft/futures.errors), [futures.future.error] (https://eel.is/c++draft/futures.future.error), [futures.promise] (https://eel.is/c++draft/futures.promise), [futures.unique.future] (https://eel.is/c++draft/futures.unique.future), [futures.shared.future] (https://eel.is/c++draft/futures.shared.future), [futures.async] (https://eel.is/c++draft/futures.async), [futures.task] (https://eel.is/c++draft/futures.task)
- **cppreference links:** [std::future](https://en.cppreference.com/w/cpp/thread/future), [std::promise](https://en.cppreference.com/w/cpp/thread/promise), [std::shared_future](https://en.cppreference.com/w/cpp/thread/shared_future), [std::packaged_task](https://en.cppreference.com/w/cpp/thread/packaged_task), [std::async](https://en.cppreference.com/w/cpp/thread/async), [std::launch](https://en.cppreference.com/w/cpp/thread/launch), [std::future_errc](https://en.cppreference.com/w/cpp/thread/future_errc), [std::future::get](https://en.cppreference.com/w/cpp/thread/future/get)
- **Prerequisites:** threads-and-jthread, condition-variables-and-waiting, exceptions-and-stack-unwinding, copy-and-move

## The one idea

Every future-based handoff is built on one object you never name: the *shared state*. It is allocated by the producer side, and it holds a slot for either a value or an exception, a "ready" flag, and sometimes a deferred function waiting to run. The producer side is an *asynchronous provider*: a `std::promise`, a `std::packaged_task`, or the machinery behind `std::async`. The consumer side is an *asynchronous return object*: a `std::future` or a `std::shared_future`. Both sides hold references to the same shared state, and it is destroyed when the last reference is released.

Making the state ready synchronizes with whoever observes that it is ready, through `wait` or `get`. So a value set through a promise, and everything the producer wrote before setting it, is visible to the thread that gets it, with no extra locking.

> **Mental model.** A promise and its future are the two ends of a one-shot pipe that carries exactly one thing, a value or an exception. Each end can be used once, and if the sending end is dropped without sending, the pipe delivers a "broken promise" error instead.

## promise and future

A `std::promise<T>` creates the shared state. `get_future()` hands out the matching `std::future<T>`, and `set_value` or `set_exception` makes the state ready. In another thread, `future::get()` blocks until the state is ready and then returns the value or rethrows the exception.

```cpp
#include <future>
#include <thread>

int main() {
  std::promise<int> p;
  std::future<int> f = p.get_future();
  std::thread t([&p] { p.set_value(42); });   // the producer
  int v = f.get();                            // blocks until ready, then 42
  t.join();
  return v == 42 ? 0 : 1;
}
```

Each operation has a single-use rule, and breaking one throws `std::future_error`, whose `code()` compares equal to a `std::future_errc` value:

- calling `get_future()` a second time gives `future_already_retrieved`;
- setting a value or exception a second time gives `promise_already_satisfied`;
- using a promise that has no shared state, for example a moved-from one, gives `no_state`;
- destroying a promise whose state is not ready *abandons* the state: the promise stores a `future_error` with `broken_promise` and makes the state ready, so the waiting `get()` throws it instead of blocking forever.

```cpp
#include <future>
#include <iostream>

int main() {
  std::future<int> f;
  {
    std::promise<int> p;
    f = p.get_future();
  }   // p abandons the shared state here
  try {
    f.get();
  } catch (const std::future_error& e) {
    std::cout << (e.code() == std::future_errc::broken_promise) << '\n';   // 1
  }
}
```

`set_value_at_thread_exit` and `set_exception_at_thread_exit` store the result immediately but delay making the state ready until the current thread has destroyed its `thread_local` objects. They are the safe way to signal completion from a detached thread.

## get moves the value out, and then the future is empty

`std::future<T>::get()` is a one-time operation. It waits, then *moves* the value out of the shared state and releases the state, after which `valid()` is false. That is why `future<std::unique_ptr<T>>` works. The reference form `future<T&>` returns the reference, and `future<void>` returns nothing.

Calling `get`, or any member other than the destructor, move assignment, `share` and `valid`, on a future whose `valid()` is false is undefined behavior. The standard recommends that implementations throw `future_error` with `no_state` in that case, and libstdc++ does, but code must not rely on it.

> **Standardese.** [futures.unique.future] says that calling any member function other than the destructor, the move-assignment operator, `share` or `valid` on a `future` whose `valid() == false` is undefined, and adds as recommended practice that implementations detect this and throw `future_error` with `no_state`.

When several consumers need the result, call `share()` to convert the future into a `std::shared_future<T>`. A shared future is copyable, and its `get()` returns `const T&` and leaves the value in place, so it can be called any number of times. Give each thread its own copy of the `shared_future` rather than sharing one object between threads. If the state holds an exception, every `get()` rethrows the stored exception.

```cpp
#include <future>
#include <memory>

int main() {
  std::promise<std::unique_ptr<int>> p;
  std::future<std::unique_ptr<int>> f = p.get_future();
  p.set_value(std::make_unique<int>(3));
  std::unique_ptr<int> v = f.get();   // moved out; f.valid() is now false

  std::promise<int> q;
  std::shared_future<int> s = q.get_future().share();
  q.set_value(9);
  const int& a = s.get();
  const int& b = s.get();             // same object, still there: &a == &b
  return *v + a - b;
}
```

## packaged_task: a callable that fills a promise

`std::packaged_task<R(Args...)>` wraps a callable together with a shared state. Calling the task runs the callable and stores its return value, or the exception it throws, in the state. Like a promise, it hands out exactly one future. It is move-only, so it can be pushed into a work queue as `std::move(task)`, and a type-erasing wrapper that accepts move-only callables, such as C++23's `std::move_only_function`, can hold it.

Calling the task a second time throws `future_error` with `promise_already_satisfied`, because the state is already ready. `reset()` abandons the old state and creates a fresh one, so the task can run again with a new future. A task destroyed without ever being called abandons its state, and its future reports `broken_promise`.

```cpp
#include <future>
#include <thread>

int square(int x) { return x * x; }

int main() {
  std::packaged_task<int(int)> task(square);
  std::future<int> f = task.get_future();
  std::thread t(std::move(task), 7);   // the task runs on t and fills the state
  int r = f.get();                     // 49
  t.join();
  return r == 49 ? 0 : 1;
}
```

## std::async and its launch policies

`std::async(policy, f, args...)` decay-copies its arguments, as `std::thread` does, and returns a future for the result. The policy is a bitmask of `std::launch` values:

- `std::launch::async` runs the function as if on a new thread, with its own fresh `thread_local` objects. If no thread can be started, `async` throws `std::system_error` with `resource_unavailable_try_again`.
- `std::launch::deferred` stores the function in the shared state and runs nothing. The first call to `get` or `wait` on any future sharing that state runs it, synchronously, in the calling thread. If nobody ever asks, it never runs.
- Both bits, which is what you get when you omit the policy, let the implementation choose either one.

The default is a trap. Code written as if the work runs concurrently is not guaranteed to. Thread-local variables may belong to the calling thread, and a polling loop on `wait_for` can spin forever, because the timed waits never run a deferred function. They return `std::future_status::deferred` immediately instead.

```cpp
#include <chrono>
#include <future>

int main() {
  using namespace std::chrono_literals;
  auto f = std::async([] { return 42; });   // policy: async | deferred
  // while (f.wait_for(10ms) != std::future_status::ready) {}
  //   ^ never ends if the implementation chose deferred
  if (f.wait_for(0s) == std::future_status::deferred) {
    // nothing is running; get() below will run the function right here
  }
  return f.get();
}
```

If you need concurrency, say `std::launch::async`. If you want lazy evaluation, say `std::launch::deferred`. Leave the choice to the implementation only when you truly do not care.

## The blocking destructor of async futures

When `std::async` launches a thread, the standard requires that the thread's completion synchronize with the return of the first function that detects the state is ready or of the last function that releases the state, whichever comes first. In practice that means the destructor of the last future referring to such a state blocks until the task finishes. No other future does this: a future from a `promise` or a `packaged_task` releases its state without waiting.

The consequence is easy to miss when the future is a temporary:

```cpp
#include <chrono>
#include <cstdio>
#include <future>
#include <thread>

int main() {
  (void)std::async(std::launch::async, [] {
    std::this_thread::sleep_for(std::chrono::milliseconds(100));
    std::puts("a");
  });   // the temporary future's destructor waits here
  (void)std::async(std::launch::async, [] { std::puts("b"); });
}   // always prints a, then b: the two calls run one after the other
```

Since C++20 `std::async` is marked `[[nodiscard]]`, so compilers warn about the discarded result. The cast to `void` above silences the warning but not the waiting. To run work in the background, keep the future alive for as long as you want concurrency.

> **Pitfall.** The blocking destructor makes `std::async` futures behave differently from all others, which matters to code that stores futures generically. A container of futures from `std::async` waits for every task when it is destroyed. The same container filled from promises does not.

## Why standard futures do not chain

A `std::future` has no way to say "when this is ready, run that". The only ways to consume it are to block in `get` or `wait`, or to poll with `wait_for`. Composing asynchronous steps therefore costs a thread blocked in `get` per step, or a polling loop. The Concurrency TS proposed `future::then`, `when_all` and `when_any` under `std::experimental`, but they were never adopted into the standard. The common criticisms were that they left unclear which thread runs a continuation, and that every step needed its own heap-allocated, synchronized shared state.

C++26 takes a different route with `std::execution`, the senders and receivers model. A sender describes work without starting it, adaptors such as `then` and `when_all` compose senders into larger ones, and a scheduler decides where each piece runs. That model is the subject of the senders-and-receivers topic. Futures remain the simple tool for a single result handed from one thread to another.

## What to remember

- Promise, packaged_task and async write a shared state; future and shared_future read it. Making the state ready synchronizes with the thread that observes it.
- Each promise allows one `get_future` and one result. Violations throw `future_error` with `future_already_retrieved` or `promise_already_satisfied`.
- A promise or packaged_task destroyed without a result stores `broken_promise`, so `get()` throws rather than hangs.
- Exceptions travel through the shared state; `get()` rethrows them in the consuming thread.
- `future::get()` moves the value out and invalidates the future. Using an invalid future is undefined; libstdc++ throws `no_state`.
- `shared_future` is copyable, returns `const T&`, and can be read many times; give each thread its own copy.
- `packaged_task` runs once per state; a second call throws `promise_already_satisfied`, and `reset()` starts over.
- The default `std::async` policy may defer the work; timed waits then return `future_status::deferred` and never run it.
- The last future from an `async` that launched a thread blocks in its destructor, so discarded results serialize.
- Standard futures cannot chain. C++26 senders replace continuation-style composition.

## Concept Map Outline

- **Futures, promises and async:** Providers and futures share one state that carries exactly one value or exception between threads.
  - **Shared state:** Holds a value or exception, a ready flag, and possibly a deferred function.
    - **Providers:** promise, packaged_task and std::async write the result into the state.
    - **Return objects:** future and shared_future read the result; the last reference destroys the state.
    - **Synchronization:** Making the state ready synchronizes with the wait or get that observes it.
  - **promise and future:** A one-shot pipe: one get_future, one result, one get.
    - **broken_promise:** A provider destroyed without a result stores this error, so get throws instead of hanging.
    - **Single-use errors:** future_already_retrieved for a second get_future; promise_already_satisfied for a second result.
    - **get moves out:** future<T>::get moves the value and releases the state; valid() is then false.
    - **Invalid future:** Using a future with valid() false is undefined; throwing no_state is only recommended.
    - **At thread exit:** set_value_at_thread_exit makes the state ready after thread_local objects are destroyed.
  - **shared_future:** Copyable view of the state for many consumers, made by future::share().
    - **Repeatable get:** get returns const T& and leaves the value in place; every get rethrows a stored exception.
    - **One copy per thread:** Give each thread its own shared_future object rather than sharing one.
  - **packaged_task:** A move-only callable that stores its result or exception in a shared state.
    - **Run once:** A second call throws promise_already_satisfied.
    - **reset:** Abandons the old state and creates a fresh one, which needs a new future.
  - **std::async:** Decay-copies arguments and returns a future for the function's result.
    - **launch::async:** Runs as if on a new thread; throws system_error if no thread can be started.
    - **launch::deferred:** Runs lazily in the thread that first calls get or wait; never if nobody asks.
    - **Default policy:** async | deferred lets the implementation choose; timed waits may return deferred forever.
    - **Blocking destructor:** The last future for a launched async state waits for the task, so discarded results serialize.
  - **No continuations:** Standard futures can only be blocked on or polled, never chained.
    - **Concurrency TS:** future::then, when_all and when_any stayed in std::experimental and were not adopted.
    - **C++26 senders:** std::execution composes work lazily with schedulers; see senders-and-receivers.

## Standardese Quiz Questions

### Question 1 [warmup] ([futures.promise], [futures.state], [futures.errors])

What does this program print?

```cpp
#include <future>
#include <iostream>

int main() {
  std::future<int> f;
  {
    std::promise<int> p;
    f = p.get_future();
  }
  try {
    std::cout << f.get() << '\n';
  } catch (const std::future_error& e) {
    std::cout << (e.code() == std::future_errc::broken_promise) << '\n';
  }
}
```

A. `0`, the value-initialized `int`
B. Nothing: `f.get()` blocks forever because no value is ever set
C. `1`
D. Undefined behavior: the future outlives its promise

**Answer (C):** `1`

**Why:** Destroying a promise whose shared state is not ready abandons the state: it stores a `future_error` with `broken_promise` and makes the state ready. So `get()` does not block; it throws, and the comparison prints `1`. The future keeps the shared state alive by itself, so outliving the promise is normal, not undefined.

### Question 2 [warmup] ([futures.async], [futures.unique.future])

What does this program print?

```cpp
#include <future>
#include <iostream>
#include <stdexcept>

int main() {
  auto f = std::async(std::launch::async, []() -> int {
    throw std::runtime_error("boom");
  });
  try {
    std::cout << f.get() << '\n';
  } catch (const std::runtime_error& e) {
    std::cout << "caught " << e.what() << '\n';
  }
}
```

A. Nothing: `std::terminate` is called because the exception escapes a thread
B. `caught boom`
C. `0`, because the task produced no value
D. Nothing: `get` throws `std::future_error` with `broken_promise`, which is not caught

**Answer (B):** `caught boom`

**Why:** `std::async` runs the function so that an exception it throws is stored in the shared state rather than escaping the thread. `get()` then rethrows that exception in the calling thread, where the handler catches it. Termination is what happens with a raw `std::thread`, which is the tempting confusion; `broken_promise` only arises when a provider is destroyed without storing anything.

### Question 3 [warmup] ([futures.promise], [futures.errors])

What does this program print?

```cpp
#include <future>
#include <iostream>

int main() {
  std::promise<int> p;
  auto f1 = p.get_future();
  try {
    auto f2 = p.get_future();
  } catch (const std::future_error& e) {
    std::cout << (e.code() == std::future_errc::future_already_retrieved) << '\n';
  }
  p.set_value(5);
  std::cout << f1.get() << '\n';
}
```

A. `5` only: the second call returns another future to the same state
B. `1` and then an exception from `f1.get()`, because the failed call broke the state
C. `0` then `5`
D. `1` then `5`

**Answer (D):** `1` then `5`

**Why:** A promise hands out exactly one future. The second `get_future` throws `future_error` with `future_already_retrieved`, and the comparison prints `1`. The failed call leaves the shared state untouched, so `set_value(5)` and `f1.get()` work normally. Sharing a result between several consumers is the job of `shared_future`, not of repeated `get_future` calls.

### Question 4 [tricky] ([futures.async], [futures.state], [class.temporary])

What is guaranteed about the output?

```cpp
#include <chrono>
#include <cstdio>
#include <future>
#include <thread>

int main() {
  std::async(std::launch::async, [] {
    std::this_thread::sleep_for(std::chrono::milliseconds(100));
    std::puts("a");
  });
  std::async(std::launch::async, [] { std::puts("b"); });
}
```

A. `a` then `b`
B. `b` then `a`, because the second task does not sleep
C. `a` and `b` in an unspecified order
D. Possibly nothing, because `main` may return before either task runs

**Answer (A):** `a` then `b`

**Why:** Each call returns a temporary future that is destroyed at the end of its full-expression. Because that future is the last reference to a shared state created by `std::async` with a launched thread, the thread's completion synchronizes with the return from that release, so the destructor waits for the first task before the second call starts. The two tasks therefore run one after the other. The tempting `b` then `a` assumes the futures can be dropped without waiting, which is true only of futures from promises and packaged tasks. Compilers warn here because `std::async` is `[[nodiscard]]` since C++20, but the code is valid.

### Question 5 [tricky] ([futures.async], [futures.unique.future])

Which statement about this loop is correct?

```cpp
#include <chrono>
#include <future>

int main() {
  using namespace std::chrono_literals;
  auto f = std::async([] { return 42; });
  while (f.wait_for(10ms) != std::future_status::ready) {
    // do other work
  }
  return f.get();
}
```

A. It always ends, because the default policy is `std::launch::async`
B. It may never end: if the implementation chose deferred execution, `wait_for` returns `deferred` and never runs the function
C. It always ends, because `wait_for` runs a deferred function when it is called
D. It is undefined behavior to call `wait_for` on a future from `std::async`

**Answer (B):** It may never end: if the implementation chose deferred execution, `wait_for` returns `deferred` and never runs the function

**Why:** With no policy argument, `std::async` uses `launch::async | launch::deferred` and the implementation may pick either. A deferred function only runs on a call to `get` or a non-timed `wait`; the timed waits just return `future_status::deferred`. So if deferred is chosen, the loop condition never becomes false. Mainstream implementations usually launch a thread here, which is why the first option is tempting, but the standard does not require it.

### Question 6 [tricky] ([futures.task.members], [futures.errors])

What does this program print?

```cpp
#include <future>
#include <iostream>

int main() {
  std::packaged_task<int()> task([] { return 7; });
  auto f = task.get_future();
  task();
  try {
    task();
  } catch (const std::future_error& e) {
    std::cout << (e.code() == std::future_errc::promise_already_satisfied);
  }
  std::cout << f.get() << '\n';
}
```

A. `7`: the second call just recomputes into the same state
B. `07`
C. `17`
D. `1` and then `get()` throws, because the second call broke the state

**Answer (C):** `17`

**Why:** The first call stores 7 and makes the shared state ready. A second call would have to store into a state that is already satisfied, so it throws `future_error` with `promise_already_satisfied` and prints `1`. The stored 7 is unaffected, so `f.get()` returns it. To run a task again you must call `reset()`, which creates a new shared state and requires a new future.

### Question 7 [standardese] ([futures.unique.future])

What does the C++23 standard say about the second `f.get()`?

```cpp
#include <future>
#include <iostream>

int main() {
  std::future<int> f = std::async(std::launch::async, [] { return 1; });
  std::cout << f.get() << '\n';
  std::cout << f.get() << '\n';
}
```

A. It returns 1 again, because the value stays in the shared state
B. It is required to throw `future_error` with `no_state`
C. Undefined behavior
D. It is ill-formed, because `get` may be called only once

**Answer (C):** Undefined behavior

**Why:** `future::get` releases the shared state, so afterwards `valid()` is false. [futures.unique.future] says that calling any member other than the destructor, move assignment, `share` or `valid` on such a future is undefined. Throwing `future_error` with `no_state` is only recommended practice, which libstdc++ follows, so it is not a guarantee. Returning the value again is what `shared_future::get` does.

### Question 8 [standardese] ([futures.async], [futures.state])

Under the C++23 standard, which future's destructor may block waiting for unfinished work?

A. Any `std::future` whose shared state is not yet ready
B. The last future referring to a state from `std::async` called with `std::launch::deferred`
C. A future obtained from a `std::packaged_task` that is running on another thread
D. The last future or shared_future referring to a not-yet-ready state created by `std::async` that launched a thread

**Answer (D):** The last future or shared_future referring to a not-yet-ready state created by `std::async` that launched a thread

**Why:** [futures.async] requires the completion of a thread launched by `std::async` to synchronize with the return of the last function that releases the shared state, if no one has observed readiness first, which forces that release to wait. No such rule exists for promises or packaged tasks, whose futures release their state immediately. A deferred function never runs if nobody calls `get` or `wait`, so its future has nothing to wait for.
