#include <wx/thread.h>

Detailed Description

wxCondition variables correspond to pthread conditions or to Win32 event objects.

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 wxThread::Wait for the worker thread, but if there are several worker threads it already makes much more sense).

Note that a call to wxCondition::Signal may happen before the other thread calls wxCondition::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 wxCondition::Signal. Of course, this means that this call is going to block until wxCondition::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:

class MySignallingThread : public wxThread
{
public:
    MySignallingThread(wxMutex *mutex, wxCondition *condition)
    {
        m_mutex = mutex;
        m_condition = condition;
    }
    virtual ExitCode Entry()
    {
        ... 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!
        wxMutexLocker lock(*m_mutex);
        m_condition->Broadcast(); // same as Signal() here -- one waiter only
        return 0;
    }
private:
    wxCondition *m_condition;
    wxMutex *m_mutex;
};
int main()
{
    wxMutex mutex;
    wxCondition 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 = new MySignallingThread(&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 use a joinable thread and call wxThread::Wait on it, but this example does illustrate the importance of properly locking the mutex when using wxCondition.

Library: wxBase

Category: Threading

See Also: wxThread, wxMutex

Public Member Functions
	wxCondition (wxMutex &mutex)
	Default and only constructor.

	~wxCondition ()
	Destroys the wxCondition object.

wxCondError	Broadcast ()
	Broadcasts to all waiting threads, waking all of them up.

bool	IsOk () const
	Returns true if the object had been initialized successfully, false if an error occurred.

wxCondError	Signal ()
	Signals the object waking up at most one thread.

wxCondError	Wait ()
	Waits until the condition is signalled.

template<typename Functor >
wxCondError	Wait (const Functor &predicate)
	Waits until the condition is signalled and the associated condition true.

wxCondError	WaitTimeout (unsigned long milliseconds)
	Waits until the condition is signalled or the timeout has elapsed.

Constructor & Destructor Documentation

wxCondition::wxCondition ( wxMutex & mutex )

Default and only constructor.

The mutex must be locked by the caller before calling Wait() function. Use IsOk() to check if the object was successfully initialized.

wxCondition::~wxCondition ( )

Destroys the wxCondition object.

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

Member Function Documentation

wxCondError wxCondition::Broadcast ( )

Broadcasts to all waiting threads, waking all of them up.

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

See Also: Signal()

bool wxCondition::IsOk ( ) const

Returns true if the object had been initialized successfully, false if an error occurred.

wxCondError wxCondition::Signal ( )

Signals the object waking up at most one thread.

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

wxCondError wxCondition::Wait ( )

Waits until the condition is signalled.

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.

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.

Returns: Returns wxCOND_NO_ERROR on success, another value if an error occurred.

See Also: WaitTimeout()

template<typename Functor >

wxCondError wxCondition::Wait ( const Functor & predicate )

Waits until the condition is signalled and the associated condition true.

This is a convenience overload that may be used to ignore spurious awakenings while waiting for a specific condition to become true.

Equivalent to

while ( !predicate() )
{
    wxCondError e = Wait();
    if ( e != wxCOND_NO_ERROR )
        return e;
}
return wxCOND_NO_ERROR;

The predicate would typically be a C++11 lambda:

condvar.Wait([]{return value == 1;});

Since: 3.0

wxCondError wxCondition::WaitTimeout ( unsigned long milliseconds )

Waits until the condition is signalled or the timeout has elapsed.

This method is identical to Wait() except that it returns, with the return code of wxCOND_TIMEOUT as soon as the given timeout expires.

Parameters

milliseconds Timeout in milliseconds

Returns: Returns wxCOND_NO_ERROR if the condition was signalled, wxCOND_TIMEOUT if the timeout elapsed before this happened or another error code from wxCondError enum.

Detailed Description

Example

Public Member Functions

Constructor & Destructor Documentation

Member Function Documentation