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

FreeBSD Manual Pages

  
 
  

home | help 
std::condit...ny::wait_for(3) C++ Standard Libarystd::condit...ny::wait_for(3)

NAME
       std::condition_variable_any::wait_for	   -	  std::condition_vari-
       able_any::wait_for

Synopsis
	  template< class Lock,	class Rep, class Period	>

	  std::cv_status	   wait_for(		Lock&		 lock,
       (1) (since C++11)

				   const std::chrono::duration<Rep, Period>&
	  rel_time );
	  template< class Lock,	class Rep, class Period, class Predicate >

	  bool	 wait_for(   Lock&   lock,   const  std::chrono::duration<Rep,
       (2) (since C++11)
	  Period>& rel_time,

			 Predicate pred	);
	  template< class Lock,	class Rep, class Period, class Predicate >

	  bool	  wait_for(    Lock&	 lock,	   std::stop_token     stoken,
       (3) (since C++20)
			 const std::chrono::duration<Rep, Period>& rel_time,

			 Predicate pred	);

	  wait_for  causes  the	 current  thread  to block until the condition
       variable	is
	  notified, the	given duration has been	elapsed, or a spurious	wakeup
       occurs. pred can
	  be optionally	provided to detect spurious wakeup.

	  1)	    Equivalent	      to	return	      wait_until(lock,
       std::chrono::steady_clock::now()	+
	  rel_time);.
	  2,3) Waiting for a specific condition	to become true,	can be used to
       ignore spurious
	  awakenings.
	  2)	    Equivalent	      to	return	      wait_until(lock,
       std::chrono::steady_clock::now()	+
	  rel_time, std::move(pred));.
	  3)  Registers	*this for the duration of this call, to	be notified if
       a stop request
	  is made on stoken's associated stop-state; it	is then	equivalent  to
       return
	  wait_until(lock, std::move(stoken),
			    std::chrono::steady_clock::now()	+    rel_time,
       std::move(pred));.

	  Right	after wait_for returns,	lock is	locked by the calling  thread.
       If this
	  postcondition	cannot be satisfied^[1], calls std::terminate.

	   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
	  stoken   - a stop token to register interruption for
	  rel_time - the maximum duration to wait
	  pred	    -  the  predicate to check whether the waiting can be com-
       pleted

Type requirements
	  -
	  Lock must meet the requirements of BasicLockable.
	  -
	  Predicate must meet the requirements of FunctionObject.

Return value
	  1) std::cv_status::timeout if	rel_time has been  elapsed  since  the
       beginning of this
	  call,	otherwise std::cv_status::no_timeout.
	  2,3) The latest result of pred() before returning to the caller.

Exceptions
	  1) Timeout-related exceptions.
	  2,3) Timeout-related exceptions, and any exception thrown by pred.

Notes
	  Even	if notified under lock,	overload (1) makes no guarantees about
       the state of the
	  associated predicate when returning due to timeout.

	  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_any 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 2093 C++11      timeout-related exceptions  were	      mentions
       these exceptions
			      missing in the specification
	  LWG  2135  C++11	 the  behavior	was unclear if		 calls
       std::terminate in
			      lock.lock() throws an exception	    this case

See also
	  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_until until specified time point	has been reached
		     (public member function)

Hidden category:
	    * Pages with unreviewed LWG	DR marker

http://cppreference.com		  2024.06.10	 std::condit...ny::wait_for(3)

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

home | help