ConditionVariable Class Reference
[Rtos]

The ConditionVariable class is a synchronization primitive that allows threads to wait until a particular condition occurs. More...

#include <ConditionVariable.h>

Inherits NonCopyable< ConditionVariable >.

Detailed Description

The ConditionVariable class is a synchronization primitive that allows threads to wait until a particular condition occurs.

Use the condition variable in conjunction with a mutex to safely wait for or notify waiters of condition changes to a resource accessible by multiple threads.

The thread that intends to wait on a ConditionVariable must:

• Acquire a lock on a mutex.
• Execute `wait`, `wait_for` or `wait_until`. While the thread is waiting, the mutex is unlocked.
• When the condition variable has been notified, or in the case of `wait_for` and `wait_until` the timeout expires, the thread is awakened.

The thread that intends to notify a ConditionVariable must:

• Acquire a lock on the mutex used to construct the condition variable.
• Execute `notify_one` or `notify_all` on the condition variable.

All threads waiting on the condition variable wake when `ConditionVariablenotify_all` is called. At least one thread waiting on the condition variable wakes when `ConditionVariablenotify_one` is called.

While a thread is waiting for notification of a ConditionVariable, it releases the lock held on the mutex. The ConditionVariable reacquires the mutex lock before exiting the wait function.

#### Unspecified behavior

• The thread that is unblocked on `ConditionVariablenotify_one` is unspecified if there are multiple waiters.
• When `ConditionVariablenotify_one` or `ConditionVariablenotify_all` is called and there are one or more waiters, and one or more threads attempting to acquire the condition variable's mutex, the order in which the mutex is acquired is unspecified.
• Spurious notifications (not triggered by the application) can occur.

#### Undefined behavior

• Calling wait if the mutex is not locked by the current thread is undefined behavior.
• The order in which waiting threads acquire the condition variable's mutex after `ConditionVariablenotify_all` is called is undefined.
• The behavior of `ConditionVariablewait` and `ConditionVariablewait_for` is undefined if the condition variable's mutex is locked more than once by the calling thread.

Note:

Synchronization level: Thread safe

Example:

 #include "mbed.h"

 Mutex mutex;
 ConditionVariable cv(mutex);

 // These variables are protected by locking the mutex.
 uint32_t work_count = 0;
 bool done = false;

 void worker_thread()
 {
   // Acquire lock on mutex before accessing protected variables and waiting.
   mutex.lock();

   while (done == false) {
     printf("Worker thread: Count: %lu\r\n", work_count);

     // Wait for main thread to notify the condition variable.
     printf("Worker thread: Waiting\r\n");
     cv.wait();
   }

   printf("Worker: Exiting\r\n");

   // The condition variable acquires the lock when exiting the `wait` function.
   // Unlock mutex when exiting the thread.
   mutex.unlock();
 }

 int main()
 {
   Thread thread;
   thread.start(worker_thread);

   for (int i = 0; i < 5; i++) {
     // Acquire lock on mutex before modifying variables and notifying.
     mutex.lock();

     // Change count and notify waiters.
     work_count++;
     printf("Main thread: Set count to: %lu\r\n", work_count);
     printf("Main thread: Notifying worker thread\r\n");
     cv.notify_all();

     // Mutex must be unlocked before the worker thread can acquire it.
     mutex.unlock();

     wait(1.0);
   }

   // Change done and notify waiters of this.
   mutex.lock();
   done = true;
   cv.notify_all();
   mutex.unlock();

   thread.join();

   printf("Main: Exiting\r\n");
 }

Definition at line 152 of file ConditionVariable.h.

Constructor & Destructor Documentation