home | help 
std::condit...::wait_until(3)  C++ Standard Libary std::condit...::wait_until(3)

NAME
     std::condition_variable::wait_until - std::condition_variable::wait_until

Synopsis
	template< class Clock, class Duration >

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

			const std::chrono::time_point<Clock, Duration>&
	abs_time );
	template< class Clock, class Duration, class Predicate >

	bool wait_until( std::unique_lock<std::mutex>& lock,
			 const std::chrono::time_point<Clock,  Duration>&    (2)
     (since C++11)
	abs_time,

			 Predicate pred );

	wait_until  causes the current thread to block until the condition vari-
     able is
	notified, the given time point has been reached, 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 exe-
     cuted, or
	abs_time is reached. It may also be unblocked spuriously.
	When unblocked, calls lock.lock() (possibly blocking on the lock),  then
     returns.
	2) Equivalent to while (!pred())
	    if (wait_until(lock, abs_time) == std::cv_status::timeout)
		return pred();
	return true;.
	This  overload	may  be used to ignore spurious awakenings while waiting
     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_until returns, lock.owns_lock() is true,  and	lock.mu-
     tex() 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  unde-
     fined:

	  * 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.  a	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
	abs_time - the time point where waiting expires
	pred	 - the predicate to check whether the waiting can be completed

Type requirements
	-
	Predicate must meet the requirements of FunctionObject.

Return value
	1) std::cv_status::timeout if abs_time has been reached, 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
	The standard recommends that the clock tied to abs_time be used to  mea-
     sure time;
	that clock is not required to be a monotonic clock. There are no guaran-
     tees
	regarding the behavior of this function if the clock is adjusted discon-
     tinuously,
	but the existing implementations convert abs_time from Clock to
	std::chrono::system_clock  and	delegate to POSIX pthread_cond_timedwait
     so that the
	wait honors adjustments to the system clock, but not  to  the  user-pro-
     vided Clock. In
	any  case,  the  function  also  may  wait  for  longer than until after
     abs_time has been
	reached due to scheduling or resource contention delays.

	Even if the clock in use is std::chrono::steady_clock or another monoto-
     nic clock, a
	system clock adjustment may induce a spurious wakeup.

	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		 Correct
     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 awak-
     ened
		 (public member function)
		 blocks the current thread until the condition variable is awak-
     ened or after
	wait_for the specified timeout duration
		 (public member function)

Hidden category:
	  * Pages with unreviewed LWG DR marker

http://cppreference.com 	   2024.06.10	   std::condit...::wait_until(3)
home | help