+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
+\helpref{Wait()}{wxthreadwait} for the worker thread, but if there are several
+worker threads it already makes much more sense).
+
+Note that a call to \helpref{Signal()}{wxconditionsignal} may happen before the
+other thread calls \helpref{Wait()}{wxconditionwait} 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
+\helpref{Signal()}{wxconditionsignal}. Of course, this means that this call is
+going to block until \helpref{Wait()}{wxconditionwait} is called by another
+thread.
+
+\wxheading{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:
+
+\begin{verbatim}
+class MySignallingThread : public wxThread
+{
+public:
+ MySignallingThread(wxMutex *mutex, wxCondition *condition)
+ {
+ m_mutex = mutex;
+ m_condition = condition;
+
+ Create();
+ }
+
+ 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;
+}
+\end{verbatim}
+
+Of course, here it would be much better to simply use a joinable thread and
+call \helpref{wxThread::Wait}{wxthreadwait} on it, but this example does
+illustrate the importance of properly locking the mutex when using
+wxCondition.
+
+\wxheading{Constants}
+
+The following return codes are returned by wxCondition member functions:
+
+\begin{verbatim}
+enum wxCondError
+{
+ wxCOND_NO_ERROR = 0, // successful completion
+ wxCOND_INVALID, // object hasn't been initialized successfully
+ wxCOND_TIMEOUT, // WaitTimeout() has timed out
+ wxCOND_MISC_ERROR // some other error
+};
+\end{verbatim}
projects / wxWidgets.git / blobdiff