glibmm 2.66.10

Public Member Functions | List of all members
Glib::Threads::Cond Class Reference
Threads

An opaque data structure to represent a condition. More...

`#include <glibmm/threads.h>`

## Public Member Functions
| Cond ()
| Cond (const Cond &)=delete
Cond & | operator= (const Cond &)=delete
| ~Cond ()
void | signal ()
| If threads are waiting for this Cond, exactly one of them is woken up.
void | broadcast ()
| If threads are waiting for this Cond, all of them are woken up.
void | wait (Mutex & mutex)
| Waits until this thread is woken up on this Cond.
bool | wait_until (Mutex & mutex, gint64 end_time)
| Waits until this thread is woken up on this Cond, but not longer than until the time specified by end_time.
GCond * | gobj ()

## Detailed Description

An opaque data structure to represent a condition.

A Cond is an object that threads can block on, if they find a certain condition to be false. If other threads change the state of this condition they can signal the Cond, such that the waiting thread is woken up.

Deprecated
  Please use std::condition_variable instead.

Usage example:
  Glib::Threads::Cond data_cond;
  Glib::Threads::Mutex data_mutex;
  void* current_data = nullptr;
  void push_data(void* data)
  {
  Glib::Threads::Mutex::Lock lock(data_mutex);
  current_data = data;
  data_cond.signal();
  }
  void* pop_data()
  {
  Glib::Threads::Mutex::Lock lock(data_mutex);
  while (!current_data)
  data_cond.wait(data_mutex);
  void* const data = current_data;
  current_data = nullptr;
  return data;
  }
  Glib::Threads::Cond
  An opaque data structure to represent a condition.
  Definition threads.h:527
  Glib::Threads::Cond::wait
  void wait(Mutex &mutex)
  Waits until this thread is woken up on this Cond.
  Glib::Threads::Cond::signal
  void signal()
  If threads are waiting for this Cond, exactly one of them is woken up.
  Glib::Threads::Mutex::Lock
  Utility class for exception-safe mutex locking.
  Definition threads.h:298
  Glib::Threads::Mutex
  Represents a mutex (mutual exclusion).
  Definition threads.h:243

## Constructor & Destructor Documentation

## ◆ Cond() [1/2]

Glib::Threads::Cond::Cond | ( |  | ) |

## ◆ Cond() [2/2]

Glib::Threads::Cond::Cond | ( | const Cond & |  | ) |
| delete

## ◆ ~Cond()

Glib::Threads::Cond::~Cond | ( |  | ) |

## Member Function Documentation

## ◆ broadcast()

void Glib::Threads::Cond::broadcast | ( |  | ) |

If threads are waiting for this Cond, all of them are woken up.

It is good practice to hold the same lock as the waiting threads, while calling this method, though not required.

## ◆ gobj()

GCond * Glib::Threads::Cond::gobj | ( |  | ) |
| inline

## ◆ operator=()

Cond & Glib::Threads::Cond::operator= | ( | const Cond & |  | ) |
| delete

## ◆ signal()

void Glib::Threads::Cond::signal | ( |  | ) |

If threads are waiting for this Cond, exactly one of them is woken up.

It is good practice to hold the same lock as the waiting thread, while calling this method, though not required.

## ◆ wait()

void Glib::Threads::Cond::wait | ( | Mutex & | mutex | ) |

Waits until this thread is woken up on this Cond.

The mutex is unlocked before falling asleep and locked again before resuming.

Parameters

  mutex | A Mutex that is currently locked.

Note
  It is important to use the wait() and wait_until() methods only inside a loop, which checks for the condition to be true as it is not guaranteed that the waiting thread will find it fulfilled, even if the signaling thread left the condition in that state. This is because another thread can have altered the condition, before the waiting thread got the chance to be woken up, even if the condition itself is protected by a Mutex.

## ◆ wait_until()

bool Glib::Threads::Cond::wait_until | ( | Mutex & | mutex,
|  | gint64 | end_time )

Waits until this thread is woken up on this Cond, but not longer than until the time specified by end_time.

The mutex is unlocked before falling asleep and locked again before resuming.

Usage example:
  Extending the example presented in the documentation of class Cond.
  void* pop_data_timed()
  {
  Glib::Threads::Mutex::Lock lock(data_mutex);
  // Wait at most 5 seconds.
  const gint64 end_time = g_get_monotonic_time() + 5 * G_TIME_SPAN_SECOND;
  while (!current_data)
  if (!data_cond.wait_until(data_mutex, end_time)
  return nullptr; // timeout
  void* const data = current_data;
  current_data = nullptr;
  return data;
  }
  The end time is calculated once, before entering the loop, and reused. This is the motivation behind the use of absolute time. If a relative time of 5 seconds were passed directly to the call and a spurious wakeup occurred, the program would have to start over waiting again, which would lead to a total wait time of more than 5 seconds.

Parameters

  mutex | A Mutex that is currently locked.
  end_time | The monotonic time to wait until, in microseconds. See g_get_monotonic_time().

Returns
  true if the condition variable was signalled (or in the case of a spurious wakeup), false if end_time has passed.

Note
  It is important to use the wait() and wait_until() methods only inside a loop, which checks for the condition to be true as it is not guaranteed that the waiting thread will find it fulfilled, even if the signaling thread left the condition in that state. This is because another thread can have altered the condition, before the waiting thread got the chance to be woken up, even if the condition itself is protected by a Mutex.