std::future
From cppreference.com
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::futureobject 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).
Contents |
[edit]Member functions
| constructs the future object (public member function) | |
| destructs the future object (public member function) | |
| moves the future object (public member function) | |
| transfers the shared state from *this to a shared_future and returns it (public member function) | |
Getting the result | |
| returns the result (public member function) | |
State | |
| checks if the future has a shared state (public member function) | |
| waits for the result to become available (public member function) | |
| waits for the result, returns if it is not available for the specified timeout duration (public member function) | |
| waits for the result, returns if it is not available until specified time point has been reached (public member function) | |
[edit]Examples
Run this code
#include <future>#include <iostream>#include <thread> int main(){// future from a packaged_taskstd::packaged_task<int()> task([]{return7;});// wrap the function std::future<int> f1 = task.get_future();// get a futurestd::thread t(std::move(task));// launch on a thread // future from an async() std::future<int> f2 =std::async(std::launch::async, []{return8;}); // future from a promisestd::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
[edit]Example with exceptions
Run this code
#include <future>#include <iostream>#include <thread> int main(){std::promise<int> p; std::future<int> f = p.get_future(); std::thread t([&p]{try{// code that may throwthrowstd::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(conststd::exception& e){std::cout<<"Exception from the thread: "<< e.what()<<'\n';} t.join();}
Output:
Exception from the thread: Example
[edit]See also
(C++11) | runs a function asynchronously (potentially in a new thread) and returns a std::future that will hold the result (function template) |
(C++11) | waits for a value (possibly referenced by other futures) that is set asynchronously (class template) |
