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