Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help 
std::future(3)		      C++ Standard Libary		std::future(3)

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::pack-
       aged_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_fu-
       ture 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 func-
       tion
	    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 fu-
       tures) that is set
	  (C++11)	asynchronously
			(class template)

http://cppreference.com		  2022.07.31			std::future(3)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=std::future&sektion=3&manpath=FreeBSD+Ports+15.0>

home | help