std::future

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

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)

Example

#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

(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)

© cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
http://en.cppreference.com/w/cpp/thread/future