Skip to content
Tutorials Center
My learning

Topics

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.

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

C++ Handing a value to another thread

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++ Exceptions, broken promises and shared_future

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 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 to shared_future, whose get() 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 use set_exception; otherwise the consumer gets broken_promise.
  • A future is a result, not a thread. Starting the thread and joining it stays your job (or use std::async).
  • wait_for is for polling and timeouts. future_status::ready means get() will not block.
  • Futures from std::async block in their destructor when launched asynchronously; futures from a promise do not.
  • Synchronization is built in: everything written before set_value is visible after get().
  • 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.