Thread::Condition Class Reference

Detailed Description

They may be used in a multithreaded application to wait until the given condition becomes true which happens when the condition becomes signaled.

For example, if a worker thread is doing some long task and another thread has to wait until it is finished, the latter thread will wait on the condition object and the worker thread will signal it on exit (this example is not perfect because in this particular case it would be much better to just Thread::Join() for the worker thread, but if there are several worker threads it already makes much more sense).

Note that a call to Condition::Signal() may happen before the other thread calls Condition::Wait() and, just as with the pthread conditions, the signal is then lost and so if you want to be sure that you don't miss it you must keep the mutex associated with the condition initially locked and lock it again before calling Condition::Signal(). Of course, this means that this call is going to block until Condition::Wait() is called by another thread.

Example

This example shows how a main thread may launch a worker thread which starts running and then waits until the main thread signals it to continue:

#include "thread.h"

class MySignallingThread : public Thread::Thread {
    Thread::Condition *m_condition;
    Thread::Mutex *m_mutex;
public:
    MySignallingThread(Thread::Mutex *mutex, Thread::Condition *condition) {
        m_mutex = mutex;
        m_condition = condition;
        Thread::Thread(NULL,NULL); }

    virtual void * Entry(void * arg) {
        ... do our job ...

        // tell the other(s) thread(s) that we're about to terminate: we must
        // lock the mutex first or we might signal the condition before the
        // waiting threads start waiting on it!
        m_mutex->Lock();
        m_condition->Broadcast(); // same as Signal() here -- one waiter only
        m_mutex->Unlock();
        return 0; } };

int main() {
    Thread::Mutex mutex;
    Thread::Condition condition(mutex);

    // the mutex should be initially locked
    mutex.Lock();

    // create and run the thread but notice that it won't be able to
    // exit (and signal its exit) before we unlock the mutex below
    MySignallingThread thread(&mutex, &condition);

    thread.Run();

    // wait for the thread termination: Wait() atomically unlocks the mutex
    // which allows the thread to continue and starts waiting
    condition.Wait();

    // now we can exit
    return 0; }

Of course, here it would be much better to simply call Thread::Join() on it, which is called in the destructor automatically but this example does illustrate the importance of properly locking the mutex when using wxCondition.

#include "thread.h"

Public Member Functions
	Condition (Mutex &mutex)
	Default and only constructor. More...
	~Condition ()
	Destroys the Condition object. More...
bool	Broadcast ()
	Broadcasts to all waiting threads, waking all of them up. More...
bool	Signal ()
	Signals the object waking up at most one thread. More...
bool	Wait (unsigned long timeout, bool execpt=true)
	Waits until the condition is signalled or the timeout has elapsed. More...
template<typename functor >
bool	Wait (functor func)
	Waits until the func() returns true. More...

Constructor & Destructor Documentation

Thread::Condition::Condition ( Thread::Mutex &  mutex )

inline

The mutex must be locked by the caller before calling Wait() function.

Thread::Condition::~Condition

(

)

The destructor is not virtual so this class should not be used polymorphically.

Member Function Documentation

bool Thread::Condition::Broadcast ( )

inline

Note that this method may be called whether the mutex associated with this condition is locked or not.

See Also

Signal()

bool Thread::Condition::Signal ( )

inline

If several threads are waiting on the same condition, the exact thread which is woken up is undefined. If no threads are waiting, the signal is lost and the condition would have to be signalled again to wake up any thread which may start waiting on it later.

Note that this method may be called whether the mutex associated with this condition is locked or not.

See Also

Broadcast()

bool Thread::Condition::Wait ( unsigned long  timeout, bool  execpt = true  )

inline

This method atomically releases the lock on the mutex associated with this condition (this is why it must be locked prior to calling Wait()) and puts the thread to sleep until Signal() or Broadcast() is called. It then locks the mutex again and returns. It also returns with a timeout error if timeout is excceded.

Note that even if Signal() had been called before Wait() without waking up any thread, the thread would still wait for another one and so it is important to ensure that the condition will be signalled after Wait() or the thread may sleep forever.

Return values

true	Exited on reciving singal.
false	Exited earlly due to error or timeout.

Exceptions

TimeoutException

Raised on timeout if except is true

See Also

Wait(functor)

template<typename functor >

bool Thread::Condition::Wait ( functor  func )

inline

This method will test func() immedatly and the wait until a singal is recived to repeat the test until func() returns true.

This method dosen't have a timeout as func() must be constant until a singal is recived.

Return values

true	Exited on reciving singal.
false	Exited earlly due to error.

See Also

Wait(unsigned long,bool)