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} but, in marked contrast
  16 with the pthread conditions, this will still work as the missed signals are
  17 queued and \helpref{Wait()}{wxconditionwait} simply returns immediately if
  18 there are ny pending signals.
  19
  20 However, the calls to \helpref{Broadcast()}{wxconditionbroadcast} are {\bf not}
  21 queued and so it will only wake up the threads already waiting on the
  22 condition. Accordingly, you will probably want to use a mutex to ensure that
  23 the thread(s) you want to be waken up have indeed started to wait before
  24 calling \helpref{Broadcast()}{wxconditionbroadcast}.
  25
  26 \wxheading{Example}
  27
  28 This example shows how a main thread may launch a worker thread and wait until
  29 it starts running:
  30
  31 \begin{verbatim}
  32 class MyWaitingThread : public wxThread
  33 {
  34 public:
  35     MyWaitingThread(wxCondition *condition)
  36     {
  37         m_condition = condition;
  38
  39         Create();
  40     }
  41
  42     virtual ExitCode Entry()
  43     {
  44         // let the main thread know that we started running
  45         m_condition->Signal();
  46
  47         ... do our job ...
  48
  49         return 0;
  50     }
  51
  52 private:
  53     wxCondition *m_condition;
  54 };
  55
  56 int main()
  57 {
  58     wxCondition condition;
  59     MyWaitingThread *thread - new MyWaitingThread(&condition);
  60
  61     thread->Run();
  62
  63     // wait until the thread really starts running
  64     condition.Wait();
  65
  66     ...
  67
  68     return 0;
  69 }
  70 \end{verbatim}
  71
  72 \wxheading{Derived from}
  73
  74 None.
  75
  76 \wxheading{Include files}
  77
  78 <wx/thread.h>
  79
  80 \wxheading{See also}
  81
  82 \helpref{wxThread}{wxthread}, \helpref{wxMutex}{wxmutex}
  83
  84 \latexignore{\rtfignore{\wxheading{Members}}}
  85
  86 \membersection{wxCondition::wxCondition}\label{wxconditionconstr}
  87
  88 \func{}{wxCondition}{\void}
  89
  90 Default constructor.
  91
  92 \membersection{wxCondition::\destruct{wxCondition}}
  93
  94 \func{}{\destruct{wxCondition}}{\void}
  95
  96 Destroys the wxCondition object.
  97
  98 \membersection{wxCondition::Broadcast}\label{wxconditionbroadcast}
  99
 100 \func{void}{Broadcast}{\void}
 101
 102 Broadcasts to all waiting objects.
 103
 104 \membersection{wxCondition::Signal}\label{wxconditionsignal}
 105
 106 \func{void}{Signal}{\void}
 107
 108 Signals the object.
 109
 110 \membersection{wxCondition::Wait}\label{wxconditionwait}
 111
 112 \func{void}{Wait}{\void}
 113
 114 Waits indefinitely.
 115
 116 \func{bool}{Wait}{\param{unsigned long}{ sec}, \param{unsigned long}{ nsec}}
 117
 118 Waits until a signal is raised or the timeout has elapsed.
 119
 120 \wxheading{Parameters}
 121
 122 \docparam{sec}{Timeout in seconds}
 123
 124 \docparam{nsec}{Timeout nanoseconds component (added to {\it sec}).}
 125
 126 \wxheading{Return value}
 127
 128 The second form returns if the signal was raised, or FALSE if there was a timeout.
 129