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

FreeBSD Manual Pages

  
 
  

home | help 
std::condit...riable::wait(3) C++ Standard Libarystd::condit...riable::wait(3)

NAME
       std::condition_variable::wait - std::condition_variable::wait

Synopsis
	  void wait( std::unique_lock<std::mutex>& lock	);		   (1)
       (since C++11)
	  template< class Predicate >					   (2)
       (since C++11)
	  void wait( std::unique_lock<std::mutex>& lock, Predicate pred	);

	  wait causes the current thread to block until	the condition variable
       is notified or
	  a  spurious wakeup occurs. pred can be optionally provided to	detect
       spurious	wakeup.

	  1) Atomically	calls lock.unlock() and	blocks on *this.
	  The thread will be unblocked when notify_all()  or  notify_one()  is
       executed. It may
	  also be unblocked spuriously.
	  When	unblocked,  calls lock.lock() (possibly	blocking on the	lock),
       then returns.
	  2) Equivalent	to
	  while	(!pred())
	      wait(lock);.
	  This overload	may be used to ignore spurious awakenings while	 wait-
       ing for a specific
	  condition to become true.
	  If pred() is ill-formed, or
	  the return value of pred() is	not convertible	to bool
	  (until C++20)
	  decltype(pred()) does	not model boolean-testable
	  (since C++20), the program is	ill-formed.

	  Right	after wait returns, lock.owns_lock() is	true, and lock.mutex()
       is locked by
	  the calling thread. If these postconditions cannot be	satisfied^[1],
       calls
	  std::terminate.

	  If any of the	following conditions is	satisfied, the behavior	is un-
       defined:

	    * lock.owns_lock() is false.
	    * lock.mutex() is not locked by the	calling	thread.
	    * If some other threads are	also waiting on	*this, lock.mutex() is
       different from
	      the  mutex unlocked by the waiting functions (wait, wait_for and
       wait_until)
	      called on	*this by those threads.
	   1.  This can	happen if the re-locking of the	mutex throws an	excep-
       tion.

Parameters
	  lock - an lock which must be locked by the calling thread
	  pred - the predicate to check	whether	the waiting can	be completed

Type requirements
	  -
	  Predicate must meet the requirements of FunctionObject.

Exceptions
	  1) Throws nothing.
	  2) Any exception thrown by pred.

Notes
	  The effects of  notify_one()/notify_all()  and  each	of  the	 three
       atomic parts of
	  wait()/wait_for()/wait_until()  (unlock+wait,	wakeup,	and lock) take
       place in	a
	  single total order that can be viewed	as modification	 order	of  an
       atomic variable:
	  the  order  is  specific to this individual condition	variable. This
       makes it
	  impossible for notify_one() to, for example, be delayed and  unblock
       a thread	that
	  started waiting just after the call to notify_one() was made.

Example
       // Run this code

	#include <chrono>
	#include <condition_variable>
	#include <iostream>
	#include <thread>

	std::condition_variable	cv;
	std::mutex cv_m; // This mutex is used for three purposes:
			 // 1) to synchronize accesses to i
			 // 2) to synchronize accesses to std::cerr
			 // 3) for the condition variable cv
	int i =	0;

	void waits()
	{
	    std::unique_lock<std::mutex> lk(cv_m);
	    std::cerr << "Waiting... \n";
	    cv.wait(lk,	[]{ return i ==	1; });
	    std::cerr << "...finished waiting. i == 1\n";
	}

	void signals()
	{
	    std::this_thread::sleep_for(std::chrono::seconds(1));
	    {
		std::lock_guard<std::mutex> lk(cv_m);
		std::cerr << "Notifying...\n";
	    }
	    cv.notify_all();

	    std::this_thread::sleep_for(std::chrono::seconds(1));

	    {
		std::lock_guard<std::mutex> lk(cv_m);
		i = 1;
		std::cerr << "Notifying	again...\n";
	    }
	    cv.notify_all();
	}

	int main()
	{
	    std::thread	t1(waits), t2(waits), t3(waits), t4(signals);
	    t1.join();
	    t2.join();
	    t3.join();
	    t4.join();
	}

Possible output:
	Waiting...
	Waiting...
	Waiting...
	Notifying...
	Notifying again...
	...finished waiting. i == 1
	...finished waiting. i == 1
	...finished waiting. i == 1

	  Defect reports

	  The following	behavior-changing defect reports were applied retroac-
       tively to
	  previously published C++ standards.

	     DR	    Applied  to	       Behavior	as published		  Cor-
       rect behavior
	  LWG 2135  C++11	the  behavior  was  unclear  if		 calls
       std::terminate in this
			      lock.lock() throws an exception	  case

See also
		     blocks the	current	thread until the condition variable is
       awakened	or
	  wait_for   after the specified timeout duration
		     (public member function)
		     blocks the	current	thread until the condition variable is
       awakened	or
	  wait_until until specified time point	has been reached
		     (public member function)
	  C documentation for
	  cnd_wait

External links
	  1.   The Old New Thing article: Spurious wake-ups in Win32 condition
       variables.

Hidden category:
	    * Pages with unreviewed LWG	DR marker

http://cppreference.com		  2024.06.10	 std::condit...riable::wait(3)

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

home | help