1\section{\class{wxCondition}}\label{wxcondition} 2 3wxCondition variables correspond to pthread conditions or to Win32 event 4objects. They may be used in a multithreaded application to wait until the 5given condition becomes true which happens when the condition becomes signaled. 6 7For example, if a worker thread is doing some long task and another thread has 8to wait until it is finished, the latter thread will wait on the condition 9object and the worker thread will signal it on exit (this example is not 10perfect because in this particular case it would be much better to just 11\helpref{Wait()}{wxthreadwait} for the worker thread, but if there are several 12worker threads it already makes much more sense). 13 14Note that a call to \helpref{Signal()}{wxconditionsignal} may happen before the 15other thread calls \helpref{Wait()}{wxconditionwait} and, just as with the 16pthread conditions, the signal is then lost and so if you want to be sure that 17you don't miss it you must keep the mutex associated with the condition 18initially locked and lock it again before calling 19\helpref{Signal()}{wxconditionsignal}. Of course, this means that this call is 20going to block until \helpref{Wait()}{wxconditionwait} is called by another 21thread. 22 23\wxheading{Example} 24 25This example shows how a main thread may launch a worker thread which starts 26running and then waits until the main thread signals it to continue: 27 28\begin{verbatim} 29class MySignallingThread : public wxThread 30{ 31public: 32 MySignallingThread(wxMutex *mutex, wxCondition *condition) 33 { 34 m_mutex = mutex; 35 m_condition = condition; 36 37 Create(); 38 } 39 40 virtual ExitCode Entry() 41 { 42 ... do our job ... 43 44 // tell the other(s) thread(s) that we're about to terminate: we must 45 // lock the mutex first or we might signal the condition before the 46 // waiting threads start waiting on it! 47 wxMutexLocker lock(*m_mutex); 48 m_condition->Broadcast(); // same as Signal() here -- one waiter only 49 50 return 0; 51 } 52 53private: 54 wxCondition *m_condition; 55 wxMutex *m_mutex; 56}; 57 58int main() 59{ 60 wxMutex mutex; 61 wxCondition condition(mutex); 62 63 // the mutex should be initially locked 64 mutex.Lock(); 65 66 // create and run the thread but notice that it won't be able to 67 // exit (and signal its exit) before we unlock the mutex below 68 MySignallingThread *thread = new MySignallingThread(&mutex, &condition); 69 70 thread->Run(); 71 72 // wait for the thread termination: Wait() atomically unlocks the mutex 73 // which allows the thread to continue and starts waiting 74 condition.Wait(); 75 76 // now we can exit 77 return 0; 78} 79\end{verbatim} 80 81Of course, here it would be much better to simply use a joinable thread and 82call \helpref{wxThread::Wait}{wxthreadwait} on it, but this example does 83illustrate the importance of properly locking the mutex when using 84wxCondition. 85 86\wxheading{Constants} 87 88The following return codes are returned by wxCondition member functions: 89 90\begin{verbatim} 91enum wxCondError 92{ 93 wxCOND_NO_ERROR = 0, // successful completion 94 wxCOND_INVALID, // object hasn't been initialized successfully 95 wxCOND_TIMEOUT, // WaitTimeout() has timed out 96 wxCOND_MISC_ERROR // some other error 97}; 98\end{verbatim} 99 100\wxheading{Derived from} 101 102None. 103 104\wxheading{Include files} 105 106<wx/thread.h> 107 108\wxheading{See also} 109 110\helpref{wxThread}{wxthread}, \helpref{wxMutex}{wxmutex} 111 112\latexignore{\rtfignore{\wxheading{Members}}} 113 114\membersection{wxCondition::wxCondition}\label{wxconditionctor} 115 116\func{}{wxCondition}{\param{wxMutex\& }{mutex}} 117 118Default and only constructor. The {\it mutex} must be locked by the caller 119before calling \helpref{Wait}{wxconditionwait} function. 120 121Use \helpref{IsOk}{wxconditionisok} to check if the object was successfully 122initialized. 123 124\membersection{wxCondition::\destruct{wxCondition}}\label{wxconditiondtor} 125 126\func{}{\destruct{wxCondition}}{\void} 127 128Destroys the wxCondition object. The destructor is not virtual so this class 129should not be used polymorphically. 130 131\membersection{wxCondition::Broadcast}\label{wxconditionbroadcast} 132 133\func{void}{Broadcast}{\void} 134 135Broadcasts to all waiting threads, waking all of them up. Note that this method 136may be called whether the mutex associated with this condition is locked or 137not. 138 139\wxheading{See also} 140 141\helpref{wxCondition::Signal}{wxconditionsignal} 142 143\membersection{wxCondition::IsOk}\label{wxconditionisok} 144 145\constfunc{bool}{IsOk}{\void} 146 147Returns {\tt true} if the object had been initialized successfully, {\tt false} 148if an error occurred. 149 150\membersection{wxCondition::Signal}\label{wxconditionsignal} 151 152\func{void}{Signal}{\void} 153 154Signals the object waking up at most one thread. If several threads are waiting 155on the same condition, the exact thread which is woken up is undefined. If no 156threads are waiting, the signal is lost and the condition would have to be 157signalled again to wake up any thread which may start waiting on it later. 158 159Note that this method may be called whether the mutex associated with this 160condition is locked or not. 161 162\wxheading{See also} 163 164\helpref{wxCondition::Broadcast}{wxconditionbroadcast} 165 166\membersection{wxCondition::Wait}\label{wxconditionwait} 167 168\func{wxCondError}{Wait}{\void} 169 170Waits until the condition is signalled. 171 172This method atomically releases the lock on the mutex associated with this 173condition (this is why it must be locked prior to calling Wait) and puts the 174thread to sleep until \helpref{Signal}{wxconditionsignal} or 175\helpref{Broadcast}{wxconditionbroadcast} is called. It then locks the mutex 176again and returns. 177 178Note that even if \helpref{Signal}{wxconditionsignal} had been called before 179Wait without waking up any thread, the thread would still wait for another one 180and so it is important to ensure that the condition will be signalled after 181Wait or the thread may sleep forever. 182 183\wxheading{Return value} 184 185Returns {\tt wxCOND\_NO\_ERROR} on success, another value if an error occurred. 186 187\wxheading{See also} 188 189\helpref{WaitTimeout}{wxconditionwaittimeout} 190 191 192\membersection{wxCondition::WaitTimeout}\label{wxconditionwaittimeout} 193 194\func{wxCondError}{WaitTimeout}{\param{unsigned long}{ milliseconds}} 195 196Waits until the condition is signalled or the timeout has elapsed. 197 198This method is identical to \helpref{Wait}{wxconditionwait} except that it 199returns, with the return code of {\tt wxCOND\_TIMEOUT} as soon as the given 200timeout expires. 201 202\wxheading{Parameters} 203 204\docparam{milliseconds}{Timeout in milliseconds} 205 206\wxheading{Return value} 207 208Returns {\tt wxCOND\_NO\_ERROR} if the condition was signalled, 209{\tt wxCOND\_TIMEOUT} if the timeout elapsed before this happened or another 210error code from wxCondError enum. 211 212