std::condition_variable::wait

unconditional (1)	void wait (unique_lock<mutex>& lck);
predicate (2)	template <class Predicate> void wait (unique_lock<mutex>& lck, Predicate pred);

Wait until notified

The execution of the current thread (which shall have locked lck's mutex) is blocked until notified.

At the moment of blocking the thread, the function automatically calls lck.unlock(), allowing other locked threads to continue.

Once notified (explicitly, by some other thread), the function unblocks and calls lck.lock(), leaving lck in the same state as when the function was called. Then the function returns (notice that this last mutex locking may block again the thread before returning).

Generally, the function is notified to wake up by a call in another thread either to member notify_one or to member notify_all. But certain implementations may produce spurious wake-up calls without any of these functions being called. Therefore, users of this function shall ensure their condition for resumption is met.

If pred is specified (2), the function only blocks if pred returns false, and notifications can only unblock the thread when it becomes true (which is specially useful to check against spurious wake-up calls). This version (2) behaves as if implemented as:

`1`	`while (!pred()) wait(lck);`

Parameters

lck: A unique_lock object whose mutex object is currently locked by this thread.
All concurrent calls to wait member functions of this object shall use the same underlying mutex object (as returned by lck.mutex()).
pred: A callable object or function that takes no arguments and returns a value that can be evaluated as a bool.
This is called repeatedly until it evaluates to true.

Return value

none

Example

// condition_variable::wait (with predicate)
#include <iostream>           // std::cout
#include <thread>             // std::thread, std::this_thread::yield
#include <mutex>              // std::mutex, std::unique_lock
#include <condition_variable> // std::condition_variable

std::mutex mtx;
std::condition_variable cv;

int cargo = 0;
bool shipment_available() {return cargo!=0;}

void consume (int n) {
  for (int i=0; i<n; ++i) {
    std::unique_lock<std::mutex> lck(mtx);
    cv.wait(lck,shipment_available);
    // consume:
    std::cout << cargo << '\n';
    cargo=0;
  }
}

int main ()
{
  std::thread consumer_thread (consume,10);

  // produce 10 items when needed:
  for (int i=0; i<10; ++i) {
    while (shipment_available()) std::this_thread::yield();
    std::unique_lock<std::mutex> lck(mtx);
    cargo = i+1;
    cv.notify_one();
  }

  consumer_thread.join();

  return 0;
}

Output:

Data races

The function performs three atomic operations:

The initial unlocking of lck and simultaneous entry into the waiting state.
The unblocking of the waiting state.
The locking of lck before returning.

Atomic operations on the object are ordered according to a single total order, with the three atomic operations in this function happening in the same relative order as above.

Exception safety

If any parameter has a value that is not valid for this function (such as if lck's mutex object is not locked by the calling thread), it causes undefined behavior.

Otherwise, if an exception is thrown, both the condition_variable object and the arguments are in a valid state (basic guarantee). Additionally, on exception, the state of lck is attempted to be restored before exiting the function scope (by calling lck.lock()).

It may throw system_error in case of failure (transmitting any error condition from the respective call to lock or unlock).
The predicate version (2) may also throw exceptions thrown by pred.

Otherwise:
The unconditional version (1) never throws exceptions (no-throw guarantee).
The predicate version (2) may throw exceptions thrown by pred, leaving both the condition_variable object and the arguments in a valid state (basic guarantee).

If the function is not able to restore the lock and return at some point (such as if some attempt to lock or unlock throws), std::terminate is called.

classes

enum classes

functions

member functions