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

FreeBSD Manual Pages

  
 
  

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

NAME
       std::promise - std::promise

Synopsis
	  Defined in header <future>
	  template< class R > class promise;	 (1) (since C++11)
	  template< class R > class promise<R&>; (2) (since C++11)
	  template<> class promise<void>;	 (3) (since C++11)

	  1) base template
	  2)  non-void	specialization,	 used  to  communicate objects between
       threads
	  3) void specialization, used to communicate stateless	events

	  The class template std::promise provides a facility to store a value
       or an exception
	  that is later	acquired asynchronously	via a std::future object  cre-
       ated by the
	  std::promise	object.	 Note that the std::promise object is meant to
       be used only
	  once.

	  Each promise is associated with a shared state, which	contains  some
       state
	  information  and  a result which may be not yet evaluated, evaluated
       to a value
	  (possibly void) or evaluated to an exception.	A promise may do three
       things with the
	  shared state:

	    * make ready: the promise stores the result	or  the	 exception  in
       the shared state.
	      Marks  the  state	ready and unblocks any thread waiting on a fu-
       ture associated
	      with the shared state.
	    * release: the promise gives up its	reference to the shared	state.
       If this was the
	      last such	reference, the shared state is destroyed. Unless  this
       was a shared
	      state  created by	std::async which is not	yet ready, this	opera-
       tion does not
	      block.
	    * abandon: the promise  stores  the	 exception  of	type  std::fu-
       ture_error with error
	      code  std::future_errc::broken_promise,  makes  the shared state
       ready, and then
	      releases it.

	  The promise is the "push" end	of  the	 promise-future	 communication
       channel:	the
	  operation  that stores a value in the	shared state synchronizes-with
       (as defined in
	  std::memory_order) the successful return from	any function  that  is
       waiting on the
	  shared  state	 (such	as std::future::get). Concurrent access	to the
       same shared state
	  may  conflict	  otherwise:   for   example   multiple	  callers   of
       std::shared_future::get must
	  either all be	read-only or provide external synchronization.

Member functions
	  constructor		       constructs the promise object
				       (public member function)
	  destructor		       destructs the promise object
				       (public member function)
	  operator=		       assigns the shared state
				       (public member function)
	  swap			       swaps two promise objects
				       (public member function)

Getting	the result
	  get_future			returns	 a  future associated with the
       promised	result
				       (public member function)

Setting	the result
	  set_value		       sets the	result to specific value
				       (public member function)
				       sets the	result to specific value while
       delivering the
	  set_value_at_thread_exit     notification only at thread exit
				       (public member function)
	  set_exception		       sets the	result to indicate  an	excep-
       tion
				       (public member function)
				       sets  the  result to indicate an	excep-
       tion while
	  set_exception_at_thread_exit delivering  the	notification  only  at
       thread exit
				       (public member function)

Non-member functions
	  std::swap(std::promise) specializes the std::swap algorithm
	  (C++11)		  (function template)

Helper classes
	  std::uses_allocator<std::promise>  specializes the std::uses_alloca-
       tor type	trait
	  (C++11)			    (class template specialization)

Example
	  This example shows how promise<int> can be used as  signals  between
       threads.

       // Run this code

	#include <vector>
	#include <thread>
	#include <future>
	#include <numeric>
	#include <iostream>
	#include <chrono>

	void accumulate(std::vector<int>::iterator first,
			std::vector<int>::iterator last,
			std::promise<int> accumulate_promise)
	{
	    int	sum = std::accumulate(first, last, 0);
	    accumulate_promise.set_value(sum);	// Notify future
	}

	void do_work(std::promise<void>	barrier)
	{
	    std::this_thread::sleep_for(std::chrono::seconds(1));
	    barrier.set_value();
	}

	int main()
	{
	    //	Demonstrate  using  promise<int>  to transmit a	result between
       threads.
	    std::vector<int> numbers = { 1, 2, 3, 4, 5,	6 };
	    std::promise<int> accumulate_promise;
	    std::future<int>  accumulate_future	 =  accumulate_promise.get_fu-
       ture();
	    std::thread	   work_thread(accumulate,    numbers.begin(),	  num-
       bers.end(),
				    std::move(accumulate_promise));

	    // future::get() will wait until the future	has a valid result and
       retrieves it.
	    // Calling wait() before get() is not needed
	    //accumulate_future.wait();	 // wait for result
	    std::cout << "result=" << accumulate_future.get() << '\n';
	    work_thread.join();	 // wait for thread completion

	    //	Demonstrate  using  promise<void>  to  signal  state   between
       threads.
	    std::promise<void> barrier;
	    std::future<void> barrier_future = barrier.get_future();
	    std::thread	new_work_thread(do_work, std::move(barrier));
	    barrier_future.wait();
	    new_work_thread.join();
	}

Output:
	result=21

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

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

home | help