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

FreeBSD Manual Pages

  
 
  

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

NAME
       std::condition_variable - std::condition_variable

Synopsis
	  Defined in header <condition_variable>
	  class	condition_variable;		  (since C++11)

	  std::condition_variable  is  a synchronization primitive used	with a
       std::mutex to
	  block	one or more threads  until  another  thread  both  modifies  a
       shared variable (the
	  condition) and notifies the std::condition_variable.

	  The thread that intends to modify the	shared variable	must:

	   1. Acquire a	std::mutex (typically via std::lock_guard).
	   2. Modify the shared	variable while the lock	is owned.
	   3.  Call  notify_one	 or  notify_all	on the std::condition_variable
       (can be done after
	      releasing	the lock).

	  Even if the shared variable is atomic, it  must  be  modified	 while
       owning the mutex	to
	  correctly publish the	modification to	the waiting thread.

	  Any thread that intends to wait on a std::condition_variable must:

	   1. Acquire a	std::unique_lock<std::mutex> on	the mutex used to pro-
       tect the	shared
	      variable.
	   2. Do one of	the following:

	   1.  Check  the  condition, in case it was already updated and noti-
       fied.
	   2. Call wait, wait_for, or wait_until on  the  std::condition_vari-
       able (atomically
	      releases	the mutex and suspends thread execution	until the con-
       dition variable is
	      notified,	a timeout expires, or a	spurious wakeup	 occurs,  then
       atomically
	      acquires the mutex before	returning).
	   3. Check the	condition and resume waiting if	not satisfied.

	  or:
	   1.  Use  the	predicated overload of wait, wait_for, and wait_until,
       which performs
	      the same three steps.

	  std::condition_variable works	 only  with  std::unique_lock<std::mu-
       tex>, which allows
	  for  maximal	efficiency  on	some  platforms.  std::condition_vari-
       able_any	provides a
	  condition variable that works	with any BasicLockable object, such as
	  std::shared_lock.

	  Condition  variables	permit	concurrent  invocation	of  the	 wait,
       wait_for, wait_until,
	  notify_one and notify_all member functions.

	  The class std::condition_variable is a StandardLayoutType. It	is not
	  CopyConstructible, MoveConstructible,	CopyAssignable,	or MoveAssign-
       able.

Member functions
	  constructor	constructs the object
			(public	member function)
	  destructor	destructs the object
			(public	member function)
	  operator=	not copy-assignable
	  [deleted]	(public	member function)

Notification
	  notify_one	notifies one waiting thread
			(public	member function)
	  notify_all	notifies all waiting threads
			(public	member function)

Waiting
	  wait		blocks the current thread until	the condition variable
       is awakened
			(public	member function)
			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)

Native handle
	  native_handle	returns	the native handle
			(public	member function)

Example
	  std::condition_variable  is used in combination with a std::mutex to
       facilitate
	  inter-thread communication.

       // Run this code

	#include <condition_variable>
	#include <iostream>
	#include <mutex>
	#include <string>
	#include <thread>

	std::mutex m;
	std::condition_variable	cv;
	std::string data;
	bool ready = false;
	bool processed = false;

	void worker_thread()
	{
	    // wait until main() sends data
	    std::unique_lock lk(m);
	    cv.wait(lk,	[]{ return ready; });

	    // after the wait, we own the lock
	    std::cout << "Worker thread	is processing data\n";
	    data += " after processing";

	    // send data back to main()
	    processed =	true;
	    std::cout << "Worker thread	signals	data processing	completed\n";

	    // manual unlocking	is done	before notifying, to avoid waking up
	    // the waiting thread only to block	again (see notify_one for  de-
       tails)
	    lk.unlock();
	    cv.notify_one();
	}

	int main()
	{
	    std::thread	worker(worker_thread);

	    data = "Example data";
	    // send data to the	worker thread
	    {
		std::lock_guard	lk(m);
		ready =	true;
		std::cout << "main() signals data ready	for processing\n";
	    }
	    cv.notify_one();

	    // wait for	the worker
	    {
		std::unique_lock lk(m);
		cv.wait(lk, []{	return processed; });
	    }
	    std::cout << "Back in main(), data = " << data << '\n';

	    worker.join();
	}

Output:
	main() signals data ready for processing
	Worker thread is processing data
	Worker thread signals data processing completed
	Back in	main(),	data = Example data after processing

See also
	  condition_variable_any provides a condition variable associated with
       any lock	type
	  (C++11)		 (class)
	  mutex			 provides basic	mutual exclusion facility
	  (C++11)		 (class)
	  lock_guard		  implements a strictly	scope-based mutex own-
       ership wrapper
	  (C++11)		 (class	template)
	  unique_lock		 implements movable mutex ownership wrapper
	  (C++11)		 (class	template)

http://cppreference.com		  2024.06.10	    std::condition_variable(3)

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

home | help