Xfce Foundation Classes

Xfc::G::Condition Class Reference

A GCond C++ wrapper interface. More...

#include <xfc/glib/thread.hh>

Inheritance diagram for Xfc::G::Condition:

List of all members.

Public Member Functions

Constructors

Condition ()
Creates a new condition. This constructor will abort, if G::Thread::init() has not been called yet.
~Condition ()
Destructor. Frees the condition.

Accessors

GCond * g_cond () const
Get a pointer to the GCond structure.

Methods

void signal ()
If threads are waiting for the condition, exactly one of them is woken up.
void broadcast ()
If threads are waiting for the condition, all of them are woken up.
bool wait (Mutex &mutex, const TimeVal *abs_time=0)
Waits until a thread is woken up on condition.

Detailed Description

A GCond C++ wrapper interface.

The Condition object represents a condition 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 Condition, such that the waiting thread is woken up.

Example: Using G::Condition to block a thread until a condition is satisfied.

    G::Condition *data_cond = 0; // Must be initialized somewhere.
    G::Mutex *data_mutex = 0; // Must be initialized somewhere.
    void *current_data = 0;
   
    void push_data(void *data)
    {
        data_mutex->lock();
        current_data = data;
        data_cond->signal();
        data_mutex->unlock();
    }
   
    void* pop_data()
    {
        data_mutex->lock();
        while (!current_data)
                data_cond->wait(*data_mutex);
        void *data = current_data;
        current_data = 0;
        data_mutex->unlock();
        return data;
    }

Whenever a thread calls pop_data() now, it will wait until current_data is non-null, i.e. until some other thread has called push_data().

Note, it is important to use the wait() method 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, like above.

Member Function Documentation

void Xfc::G::Condition::broadcast ( )

If threads are waiting for the condition, all of them are woken up.
It is good practice to lock the same mutex as the waiting threads, while calling this method, though not required. This method can also be used if g_thread_init() has not yet been called, and will do nothing then.

void Xfc::G::Condition::signal ( )

If threads are waiting for the condition, 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. This method can also be used, if g_thread_init() has not yet been called, and will do nothing then.

bool Xfc::G::Condition::wait ( Mutex & mutex,

const TimeVal * abs_time = 0

)

Waits until a thread is woken up on condition.

Parameters:

mutex A Mutex that is currently locked.

abs_time A TimeVal determining the final time, or null for unlimited time.

Returns:
true if the thread is woken up in time, or if abs_time is null.
The mutex is unlocked before falling asleep and locked again before resuming. If abs_time is null, timed_wait() acts like g_cond_wait(). If abs_time is specified, this method waits no longer than the time abs_time specifies. To easily calculate abs_time a combination of G::get_current_time() and G::TimeVal::add() can be used. This method can be used if g_thread_init() has not yet been called, and will immediately return true then.

The documentation for this class was generated from the following file:

thread.hh

Xfce Foundation Classes

XFC 4.3