Namespaces
Variants
Views
Actions

std::condition_variable

From cppreference.com
< cpp‎ | thread
 
 
Thread support library
Threads
(C++11)
this_thread namespace
(C++11)
(C++11)
(C++11)
Mutual exclusion
(C++11)
Generic lock management
(C++11)
(C++11)
(C++11)
(C++11)(C++11)(C++11)
(C++11)
(C++11)
Condition variables
condition_variable
(C++11)
(C++11)
Futures
(C++11)
(C++11)
(C++11)
(C++11)
 
 
Defined in header <condition_variable>
class condition_variable;
(since C++11)

The condition_variable class is a synchronization primitive that can be used to block a thread, or multiple threads at the same time, until:

  • a notification is received from another thread
  • a timeout expires, or
  • a spurious wakeup occurs

Any thread that intends to wait on std::condition_variable has to acquire a std::unique_lock<std::mutex> first. The wait operations atomically release the mutex and suspend the execution of the thread. When the condition variable is notified, the thread is awakened, and the mutex is reacquired.

std::condition_variable works only with std::unique_lock<std::mutex>; this restriction allows for maximal efficiency on some platforms. std::condition_variable_any provides a condition variable that works with any BasicLockable object.

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, MoveAssignable.

Contents

[edit] Member types

Member type Definition
native_handle_type implementation-defined

[edit] Member functions

constructs the object
(public member function) [edit]
destructs the object
(public member function) [edit]
operator=
[deleted]
not copy-assignable
(public member function) [edit]
Notification
notifies one waiting thread
(public member function) [edit]
notifies all waiting threads
(public member function) [edit]
Waiting
blocks the current thread until the condition variable is woken up
(public member function) [edit]
blocks the current thread until the condition variable is woken up or after the specified timeout duration
(public member function) [edit]
blocks the current thread until the condition variable is woken up or until specified time point has been reached
(public member function) [edit]
Native handle
returns the native handle
(public member function) [edit]

[edit] Example

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

#include <iostream>
#include <string>
#include <thread>
#include <mutex>
#include <condition_variable>
 
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<std::mutex> 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 details)
    lk.unlock();
    cv.notify_one();
}
 
int main()
{
    std::thread worker(worker_thread);
 
    data = "Example data";
    // send data to the worker thread
    {
        std::lock_guard<std::mutex> lk(m);
        ready = true;
        std::cout << "main() signals data ready for processing\n";
    }
    cv.notify_one();
 
    // wait for the worker
    {
        std::unique_lock<std::mutex> 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