C++ Reference ยท Concurrency
C++ std::future and std::promise
Reference for std::future, std::shared_future and std::promise: passing a value or an exception between threads, get, wait_for, valid and broken promises.
A std::promise<T> and a std::future<T> (header <future>) are the two ends of a one-shot channel between threads. The producer holds the promise and calls set_value() (or set_exception()) once. The consumer holds the matching future, obtained with promise.get_future(), and calls get(), which blocks until the value is ready and then returns it, or rethrows the stored exception.
A future is not tied to a thread: it only represents "a result that will exist later". std::async and std::packaged_task produce futures too. A std::future can be read only once; use std::shared_future (from future.share()) when several threads need the same result.
std::promise<int> p; std::future<int> f = p.get_future(); std::thread t([&p] { p.set_value(42); }); int answer = f.get(); // 42 t.join();
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 promise { public: promise(); promise(promise&&) noexcept; std::future<R> get_future(); void set_value(const R& v); // void specialization: set_value() void set_exception(std::exception_ptr p); void set_value_at_thread_exit(const R& v); }; template<class R> class future { public: R get(); // may be called once bool valid() const noexcept; void wait() const; template<class Rep, class Period> std::future_status wait_for(const std::chrono::duration<Rep, Period>&) const; template<class Clock, class Duration> std::future_status wait_until(const std::chrono::time_point<Clock, Duration>&) const; std::shared_future<R> share() noexcept; };
| Name | Description |
|---|---|
get_future() |
Returns the future for this promise. May be called only once. |
set_value / set_exception |
Store the result or an exception. Only one of them, only once. |
get() |
Waits, then returns the value (moved out) or throws the stored exception. Afterwards valid() is false. |
wait_for / wait_until |
Return future_status::ready, timeout or deferred. |
share() |
Converts into a copyable std::shared_future. |
Returns: get() returns R (R& for future<R&>). Errors: std::future_error is thrown with codes such as promise_already_satisfied (setting twice), future_already_retrieved (get_future twice), no_state and broken_promise (promise destroyed unsatisfied). Calling get() on an invalid future is undefined behavior.
Usage notes
get()consumes the result. Call it once, or convert toshared_future, whoseget()returns a const reference and can be called repeatedly from many threads.- Always satisfy or destroy the promise on every path. If the producer throws before
set_value, catch and useset_exception; otherwise the consumer getsbroken_promise. - A future is a result, not a thread. Starting the thread and joining it stays your job (or use
std::async). wait_foris for polling and timeouts.future_status::readymeansget()will not block.- Futures from
std::asyncblock in their destructor when launched asynchronously; futures from a promise do not. - Synchronization is built in: everything written before
set_valueis visible afterget(). - For streams of values use a queue with a condition variable; a promise carries exactly one result.
- Move-only: promises and futures can be moved but not copied.