Discrete Dipole Approximation Project  1.0
Plugin based Discrete Dipole Approximation (DDA) software package.
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.


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;
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_condition->Broadcast(); // same as Signal() here -- one waiter only
return 0; } };
int main() {
Thread::Condition condition(mutex);
// the mutex should be initially locked
// 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);
// wait for the thread termination: Wait() atomically unlocks the mutex
// which allows the thread to continue and starts waiting
// 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)

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 ( )

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

See Also
bool Thread::Condition::Signal ( )

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
bool Thread::Condition::Wait ( unsigned long  timeout,
bool  execpt = true 

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
trueExited on reciving singal.
falseExited earlly due to error or timeout.
TimeoutExceptionRaised on timeout if except is true
See Also
template<typename functor >
bool Thread::Condition::Wait ( functor  func)

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
trueExited on reciving singal.
falseExited earlly due to error.
See Also
Wait(unsigned long,bool)