std::future (3) - Linux Manuals

std::future: std::future

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

              constructs the future object
constructor (public member function)
              destructs the future object
destructor (public member function)
              moves the future object
operator= (public member function)
              transfers the shared state from *this to a shared_future and returns it
share (public member function)

Getting the result

              returns the result
get (public member function)

State

              checks if the future has a shared state
valid (public member function)
              waits for the result to become available
wait (public member function)
              waits for the result, returns if it is not available for the specified timeout duration
wait_for (public member function)
              waits for the result, returns if it is not available until specified time point has been reached
wait_until (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