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

FreeBSD Manual Pages

  
 
  

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

NAME
       std::condition_variable::wait_for - std::condition_variable::wait_for

Synopsis
	  template< class Rep, class Period >

	  std::cv_status    wait_for(	 std::unique_lock<std::mutex>&	 lock,
       (1) (since C++11)

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

	  bool	     wait_for(	     std::unique_lock<std::mutex>&	 lock,
       (2) (since C++11)
			 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)	    Equivalent	      to	return	      wait_until(lock,
       std::chrono::steady_clock::now()	+
	  rel_time, std::move(pred));.
	  This	overload may be	used to	ignore spurious	awakenings while wait-
       ing for a specific
	  condition to become true.

	  Right	after wait_for returns,	lock.owns_lock() is true, and lock.mu-
       tex() is	locked
	  by the calling thread. If  these  postconditions  cannot  be	satis-
       fied^[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
	  rel_time - the maximum duration to wait
	  pred	   - the predicate to check whether the	waiting	 can  be  com-
       pleted

Type requirements
	  -
	  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) The latest	result of pred() before	returning to the caller.

Exceptions
	  1) Timeout-related exceptions.
	  2) 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	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...le::wait_for(3)

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

home | help