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{Derived from}
  83
  84 None.
  85
  86 \wxheading{Include files}
  87
  88 <wx/thread.h>
  89
  90 \wxheading{See also}
  91
  92 \helpref{wxThread}{wxthread}, \helpref{wxMutex}{wxmutex}
  93
  94 \latexignore{\rtfignore{\wxheading{Members}}}
  95
  96 \membersection{wxCondition::wxCondition}\label{wxconditionconstr}
  97
  98 \func{}{wxCondition}{\param{wxMutex\& }{mutex}}
  99
 100 Default and only constructor. The {\it mutex} must be locked by the caller
 101 before calling \helpref{Wait}{wxconditionwait} function.
 102
 103 \membersection{wxCondition::\destruct{wxCondition}}
 104
 105 \func{}{\destruct{wxCondition}}{\void}
 106
 107 Destroys the wxCondition object. The destructor is not virtual so this class
 108 should not be used polymorphically.
 109
 110 \membersection{wxCondition::Broadcast}\label{wxconditionbroadcast}
 111
 112 \func{void}{Broadcast}{\void}
 113
 114 Broadcasts to all waiting threads, waking all of them up. Note that this method
 115 may be called whether the mutex associated with this condition is locked or
 116 not.
 117
 118 \wxheading{See also}
 119
 120 \helpref{wxCondition::Signal}{wxconditionsignal}
 121
 122 \membersection{wxCondition::Signal}\label{wxconditionsignal}
 123
 124 \func{void}{Signal}{\void}
 125
 126 Signals the object waking up at most one thread. If several threads are waiting
 127 on the same condition, the exact thread which is woken up is undefined. If no
 128 threads are waiting, the signal is lost and the condition would have to be
 129 signalled again to wake up any thread which may start waiting on it later.
 130
 131 Note that this method may be called whether the mutex associated with this
 132 condition is locked or not.
 133
 134 \wxheading{See also}
 135
 136 \helpref{wxCondition::Broadcast}{wxconditionbroadcast}
 137
 138 \membersection{wxCondition::Wait}\label{wxconditionwait}
 139
 140 \func{void}{Wait}{\void}
 141
 142 Waits until the condition is signalled.
 143
 144 \func{bool}{Wait}{\param{unsigned long}{ sec}, \param{unsigned long}{ nsec}}
 145
 146 Waits until the condition is signalled or the timeout has elapsed.
 147
 148 Note that the mutex associated with this condition {\bf must} be acquired by
 149 the thread before calling this method.
 150
 151 \wxheading{Parameters}
 152
 153 \docparam{sec}{Timeout in seconds}
 154
 155 \docparam{nsec}{Timeout nanoseconds component (added to {\it sec}).}
 156
 157 \wxheading{Return value}
 158
 159 The second form returns {\tt true} if the condition has been signalled, or
 160 {\tt false} if it returned because the timeout has elapsed.
 161
 162