std::future

 

C++

Language

Standard Library Headers

Freestanding and hosted implementations

Named requirements

Language support library

Concepts library (C++20)

Diagnostics library

Utilities library

Strings library

Containers library

Iterators library

Ranges library (C++20)

Algorithms library

Numerics library

Input/output library

Localizations library

Regular expressions library (C++11)

Atomic operations library (C++11)

Thread support library (C++11)

Filesystem library (C++17)

Technical Specifications

 

Thread support library

Threads
thread (C++11)
hardware_destructive_interference_sizehardware_constructive_interference_size (C++17)(C++17)
this_thread namespace
get_id (C++11) yield (C++11)	sleep_for (C++11) sleep_until (C++11)
Mutual exclusion
mutex (C++11) recursive_mutex (C++11) shared_mutex (C++17)	timed_mutex (C++11) recursive_timed_mutex (C++11) shared_timed_mutex (C++14)
Generic lock management
lock_guard (C++11) scoped_lock (C++17) unique_lock (C++11) shared_lock (C++14) defer_lock_ttry_to_lock_tadopt_lock_t (C++11)(C++11)(C++11)	lock (C++11) try_lock (C++11) defer_locktry_to_lockadopt_lock (C++11)(C++11)(C++11) once_flag (C++11) call_once (C++11)
Condition variables
condition_variable (C++11)
condition_variable_any (C++11)
notify_all_at_thread_exit (C++11)
cv_status (C++11)
Futures
promise (C++11) future (C++11) shared_future (C++11) packaged_task (C++11) async (C++11)	launch (C++11) future_status (C++11) future_error (C++11) future_category (C++11) future_errc (C++11)

 

std::future

future::future

future::~future

future::operator=

future::share

Getting the result

future::get

State

future::valid

future::wait

future::wait_for

future::wait_until

 

Defined in header <future>
template< class T > class future;	(1)	(since C++11)
template< class T > class future<T&>;	(2)	(since C++11)
template<>          class future<void>;	(3)	(since C++11)

The class template std::future provides a mechanism to access the result of asynchronous operations:

• An asynchronous operation (created via std::async, std::packaged_task, or std::promise) can provide a std::future object to the creator of that asynchronous operation.

• The creator of the asynchronous operation can then use a variety of methods to query, wait for, or extract a value from the std::future. These methods may block if the asynchronous operation has not yet provided a value.

• When the asynchronous operation is ready to send a result to the creator, it can do so by modifying shared state (e.g. std::promise::set_value) that is linked to the creator's std::future.

Note that std::future references shared state that is not shared with any other asynchronous return objects (as opposed to std::shared_future).

Member functions

(constructor)	constructs the future object (public member function)
(destructor)	destructs the future object (public member function)
operator=	moves the future object (public member function)
share	transfers the shared state from *this to a shared_future and returns it (public member function)
Getting the result
get	returns the result (public member function)
State
valid	checks if the future has a shared state (public member function)
wait	waits for the result to become available (public member function)
wait_for	waits for the result, returns if it is not available for the specified timeout duration (public member function)
wait_until	waits for the result, returns if it is not available until specified time point has been reached (public member function)

Example

Run this code

#include <iostream>
#include <future>
#include <thread>
 
int main()
{
    // future from a packaged_task
    std::packaged_task<int()> task([]{ return 7; }); // wrap the function
    std::future<int> f1 = task.get_future();  // get a future
    std::thread t(std::move(task)); // launch on a thread
 
    // future from an async()
    std::future<int> f2 = std::async(std::launch::async, []{ return 8; });
 
    // future from a promise
    std::promise<int> p;
    std::future<int> f3 = p.get_future();
    std::thread( [&p]{ p.set_value_at_thread_exit(9); }).detach();
 
    std::cout << "Waiting..." << std::flush;
    f1.wait();
    f2.wait();
    f3.wait();
    std::cout << "Done!\nResults are: "
              << f1.get() << ' ' << f2.get() << ' ' << f3.get() << '\n';
    t.join();
}

Output:

Waiting...Done!
Results are: 7 8 9

See also

async (C++11)	runs a function asynchronously (potentially in a new thread) and returns a std::future that will hold the result (function template)
shared_future (C++11)	waits for a value (possibly referenced by other futures) that is set asynchronously (class template)