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 MyWaitingThread : public wxThread
  26 {
  27 public:
  28     MyWaitingThread(wxMutex *mutex, wxCondition *condition)
  29     {
  30         m_mutex = mutex;
  31         m_condition = condition;
  32
  33         Create();
  34     }
  35
  36     virtual ExitCode Entry()
  37     {
  38         // wait for the signal from the main thread: it is absolutely necessary
  39         // to look the mutex before doing it!
  40         m_mutex->Lock();
  41         m_condition->Signal();
  42         m_mutex->Unlock();
  43
  44         ... do our job ...
  45
  46         return 0;
  47     }
  48
  49 private:
  50     wxCondition *m_condition;
  51 };
  52
  53 int main()
  54 {
  55     wxMutex mutex;
  56     wxCondition condition(mutex);
  57
  58     for ( int i = 0; i < 10; i++ )
  59     {
  60         MyWaitingThread *thread = new MyWaitingThread(&mutex, &condition);
  61
  62         thread->Run();
  63     }
  64
  65     // wake up one of the threads
  66     condition.Signal();
  67
  68     // wake up all the other ones
  69     condition.Broadcast();
  70
  71     ... wait until they terminate or do something else ...
  72
  73     return 0;
  74 }
  75 \end{verbatim}
  76
  77 \wxheading{Derived from}
  78
  79 None.
  80
  81 \wxheading{Include files}
  82
  83 <wx/thread.h>
  84
  85 \wxheading{See also}
  86
  87 \helpref{wxThread}{wxthread}, \helpref{wxMutex}{wxmutex}
  88
  89 \latexignore{\rtfignore{\wxheading{Members}}}
  90
  91 \membersection{wxCondition::wxCondition}\label{wxconditionconstr}
  92
  93 \func{}{wxCondition}{\param{wxMutex\& }{mutex}}
  94
  95 Default and only constructor. The {\it mutex} must be locked by the caller
  96 before calling \helpref{Wait}{wxconditionwait} function.
  97
  98 \membersection{wxCondition::\destruct{wxCondition}}
  99
 100 \func{}{\destruct{wxCondition}}{\void}
 101
 102 Destroys the wxCondition object. The destructor is not virtual so this class
 103 should not be used polymorphically.
 104
 105 \membersection{wxCondition::Broadcast}\label{wxconditionbroadcast}
 106
 107 \func{void}{Broadcast}{\void}
 108
 109 Broadcasts to all waiting threads, waking all of them up. Note that this method
 110 may be called whether the mutex associated with this condition is locked or
 111 not.
 112
 113 \wxheading{See also}
 114
 115 \helpref{wxCondition::Signal}{wxconditionsignal}
 116
 117 \membersection{wxCondition::Signal}\label{wxconditionsignal}
 118
 119 \func{void}{Signal}{\void}
 120
 121 Signals the object waking up at most one thread. If several threads are waiting
 122 on the same condition, the exact thread which is woken up is undefined. If no
 123 threads are waiting, the signal is lost and the condition would have to be
 124 signalled again to wake up any thread which may start waiting on it later.
 125
 126 Note that this method may be called whether the mutex associated with this
 127 condition is locked or not.
 128
 129 \wxheading{See also}
 130
 131 \helpref{wxCondition::Broadcast}{wxconditionbroadcast}
 132
 133 \membersection{wxCondition::Wait}\label{wxconditionwait}
 134
 135 \func{void}{Wait}{\void}
 136
 137 Waits until the condition is signalled.
 138
 139 \func{bool}{Wait}{\param{unsigned long}{ sec}, \param{unsigned long}{ nsec}}
 140
 141 Waits until the condition is signalled or the timeout has elapsed.
 142
 143 Note that the mutex associated with this condition {\bf must} be acquired by
 144 the thread before calling this method.
 145
 146 \wxheading{Parameters}
 147
 148 \docparam{sec}{Timeout in seconds}
 149
 150 \docparam{nsec}{Timeout nanoseconds component (added to {\it sec}).}
 151
 152 \wxheading{Return value}
 153
 154 The second form returns {\tt TRUE} if the condition has been signalled, or
 155 {\tt FALSE} if it returned because the timeout has elapsed.
 156
 157