docs/latex/wx/conditn.tex

   1 \section{\class{wxCondition}}\label{wxcondition}
   2
   3 wxCondition variables correspond to pthread conditions or to Win32 event
   4 objects. They may be used in a multithreaded application to wait until the
   5 given condition becomes true which happens when the condition becomes signaled.
   6
   7 For example, if a worker thread is doing some long task and another thread has
   8 to wait until it is finished, the latter thread will wait on the condition
   9 object and the worker thread will signal it on exit (this example is not
  10 perfect 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
  12 worker threads it already makes much more sense).
  13
  14 Note that a call to \helpref{Signal()}{wxconditionsignal} may happen before the
  15 other thread calls \helpref{Wait()}{wxconditionwait} and, just as with the
  16 pthread conditions, the signal is then lost and so if you want to be sure that
  17 you don't miss it you must keep the mutex associated with the condition
  18 initially locked and lock it again before calling
  19 \helpref{Signal()}{wxconditionsignal}. Of course, this means that this call is
  20 going to block until \helpref{Wait()}{wxconditionwait} is called by another
  21 thread.
  22
  23 \wxheading{Example}
  24
  25 This example shows how a main thread may launch a worker thread which starts
  26 running and then waits until the main thread signals it to continue:
  27
  28 \begin{verbatim}
  29 class MySignallingThread : public wxThread
  30 {
  31 public:
  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
  53 private:
  54     wxCondition *m_condition;
  55     wxMutex *m_mutex;
  56 };
  57
  58 int 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
  81 Of course, here it would be much better to simply use a joinable thread and
  82 call \helpref{wxThread::Wait}{wxthreadwait} on it, but this example does
  83 illustrate the importance of properly locking the mutex when using
  84 wxCondition.
  85
  86 \wxheading{Constants}
  87
  88 The following return codes are returned by wxCondition member functions:
  89
  90 \begin{verbatim}
  91 enum 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
 102 None.
 103
 104 \wxheading{Include files}
 105
 106 <wx/thread.h>
 107
 108 \wxheading{Library}
 109
 110 \helpref{wxBase}{librarieslist}
 111
 112 \wxheading{See also}
 113
 114 \helpref{wxThread}{wxthread}, \helpref{wxMutex}{wxmutex}
 115
 116 \latexignore{\rtfignore{\wxheading{Members}}}
 117
 118 \membersection{wxCondition::wxCondition}\label{wxconditionctor}
 119
 120 \func{}{wxCondition}{\param{wxMutex\& }{mutex}}
 121
 122 Default and only constructor. The {\it mutex} must be locked by the caller
 123 before calling \helpref{Wait}{wxconditionwait} function.
 124
 125 Use \helpref{IsOk}{wxconditionisok} to check if the object was successfully
 126 initialized.
 127
 128 \membersection{wxCondition::\destruct{wxCondition}}\label{wxconditiondtor}
 129
 130 \func{}{\destruct{wxCondition}}{\void}
 131
 132 Destroys the wxCondition object. The destructor is not virtual so this class
 133 should not be used polymorphically.
 134
 135 \membersection{wxCondition::Broadcast}\label{wxconditionbroadcast}
 136
 137 \func{void}{Broadcast}{\void}
 138
 139 Broadcasts to all waiting threads, waking all of them up. Note that this method
 140 may be called whether the mutex associated with this condition is locked or
 141 not.
 142
 143 \wxheading{See also}
 144
 145 \helpref{wxCondition::Signal}{wxconditionsignal}
 146
 147 \membersection{wxCondition::IsOk}\label{wxconditionisok}
 148
 149 \constfunc{bool}{IsOk}{\void}
 150
 151 Returns {\tt true} if the object had been initialized successfully, {\tt false}
 152 if an error occurred.
 153
 154 \membersection{wxCondition::Signal}\label{wxconditionsignal}
 155
 156 \func{void}{Signal}{\void}
 157
 158 Signals the object waking up at most one thread. If several threads are waiting
 159 on the same condition, the exact thread which is woken up is undefined. If no
 160 threads are waiting, the signal is lost and the condition would have to be
 161 signalled again to wake up any thread which may start waiting on it later.
 162
 163 Note that this method may be called whether the mutex associated with this
 164 condition is locked or not.
 165
 166 \wxheading{See also}
 167
 168 \helpref{wxCondition::Broadcast}{wxconditionbroadcast}
 169
 170 \membersection{wxCondition::Wait}\label{wxconditionwait}
 171
 172 \func{wxCondError}{Wait}{\void}
 173
 174 Waits until the condition is signalled.
 175
 176 This method atomically releases the lock on the mutex associated with this
 177 condition (this is why it must be locked prior to calling Wait) and puts the
 178 thread to sleep until \helpref{Signal}{wxconditionsignal} or
 179 \helpref{Broadcast}{wxconditionbroadcast} is called. It then locks the mutex
 180 again and returns.
 181
 182 Note that even if \helpref{Signal}{wxconditionsignal} had been called before
 183 Wait without waking up any thread, the thread would still wait for another one
 184 and so it is important to ensure that the condition will be signalled after
 185 Wait or the thread may sleep forever.
 186
 187 \wxheading{Return value}
 188
 189 Returns {\tt wxCOND\_NO\_ERROR} on success, another value if an error occurred.
 190
 191 \wxheading{See also}
 192
 193 \helpref{WaitTimeout}{wxconditionwaittimeout}
 194
 195
 196 \membersection{wxCondition::WaitTimeout}\label{wxconditionwaittimeout}
 197
 198 \func{wxCondError}{WaitTimeout}{\param{unsigned long}{ milliseconds}}
 199
 200 Waits until the condition is signalled or the timeout has elapsed.
 201
 202 This method is identical to \helpref{Wait}{wxconditionwait} except that it
 203 returns, with the return code of {\tt wxCOND\_TIMEOUT} as soon as the given
 204 timeout expires.
 205
 206 \wxheading{Parameters}
 207
 208 \docparam{milliseconds}{Timeout in milliseconds}
 209
 210 \wxheading{Return value}
 211
 212 Returns {\tt wxCOND\_NO\_ERROR} if the condition was signalled,
 213 {\tt wxCOND\_TIMEOUT} if the timeout elapsed before this happened or another
 214 error code from wxCondError enum.
 215