NAME¶

std::future - std::future

Synopsis¶

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)
transfers the shared state from *this to a shared_future and returns
share 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)
waits for the result, returns if it is not available for the specified
wait_for timeout duration
(public member function)
waits for the result, returns if it is not available until specified
wait_until time point has been reached
(public member function)

Examples¶

// 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

Example with exceptions

// Run this code

#include <thread>
#include <iostream>
#include <future>

int main()
{
std::promise<int> p;
std::future<int> f = p.get_future();

std::thread t([&p]{
try {
// code that may throw
throw std::runtime_error("Example");
} catch(...) {
try {
// store anything thrown in the promise
p.set_exception(std::current_exception());
} catch(...) {} // set_exception() may throw too
}
});

try {
std::cout << f.get();
} catch(const std::exception& e) {
std::cout << "Exception from the thread: " << e.what() << '\n';
}
t.join();
}

Output:¶

Exception from the thread: Example

See also¶

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