std::future

 

C++

Language

Concepts

Utilities library

Strings library

Containers library

Algorithms library

Iterators library

Numerics library

Input/output library

Localizations library

Regular expressions library (C++11)

Atomic operations library (C++11)

Thread support library (C++11)

 

Thread support library

Threads
thread (C++11)
this_thread namespace
get_id (C++11) yield (C++11)	sleep_for (C++11) sleep_until (C++11)
Mutual exclusion
mutex (C++11) timed_mutex (C++11)	recursive_mutex (C++11) recursive_timed_mutex (C++11)
Generic lock management
lock_guard (C++11) unique_lock (C++11) defer_lock_t try_to_lock_t adopt_lock_t (C++11) (C++11) (C++11)	lock (C++11) try_lock (C++11) defer_lock try_to_lock adopt_lock (C++11) (C++11) (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 defines an asynchronous return object, which references a shared state and does not share it with any other asynchronous return objects (as opposed to std::shared_future). Whenever a task is executed asynchronously (via std::async, std::packaged_task, or std::promise), a shared state is created, which is initially empty, but eventually holds the return value or the exception thrown by the task. An instance of std::future may be created that references that shared state. This instance can be used by another thread to check if the asynchronous task completed, to wait for completion, and to read the return value or the exception stored in the shared state once ready.

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	returns a shared_future referring to the result associated to *this (public member function)
Getting the result
get	returns the result (public member function)
State
valid	checks if the result is available (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

#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(std::move(task)).detach(); // 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( [](std::promise<int>& p){ p.set_value(9); }, 
                 std::ref(p) ).detach();
 
    std::cout << "Waiting...";
    f1.wait();
    f2.wait();
    f3.wait();
    std::cout << "Done!\nResults are: "
              << f1.get() << ' ' << f2.get() << ' ' << f3.get() << '\n';
}

Output:

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

See also

async (C++11)	provides a facility to launch a function in a new thread and acquire its return value asynchronously (function template)
shared_future (C++11)	waits for a value that is set asynchronously. The internal state is shared among several objects (class template)