]> git.saurik.com Git - wxWidgets.git/blame - docs/latex/wx/conditn.tex
We surely don't need two debugging sections,
[wxWidgets.git] / docs / latex / wx / conditn.tex
CommitLineData
eaaa6a06
JS
1\section{\class{wxCondition}}\label{wxcondition}
2
9063ea8e
VZ
3wxCondition variables correspond to pthread conditions or to Win32 event
4objects. They may be used in a multithreaded application to wait until the
5given condition becomes true which happens when the condition becomes signaled.
6
7For example, if a worker thread is doing some long task and another thread has
f6bcfd97 8to wait until it is finished, the latter thread will wait on the condition
9063ea8e
VZ
9object and the worker thread will signal it on exit (this example is not
10perfect 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
12worker threads it already makes much more sense).
eaaa6a06 13
60ce696e 14Note that a call to \helpref{Signal()}{wxconditionsignal} may happen before the
be809868
VZ
15other thread calls \helpref{Wait()}{wxconditionwait} and, just as with the
16pthread conditions, the signal is then lost and so if you want to be sure to
17get it you must use a mutex together with the condition variable.
60ce696e
VZ
18
19\wxheading{Example}
20
be809868
VZ
21This example shows how a main thread may launch a worker thread which starts
22running and then waits until the main thread signals it to continue:
60ce696e
VZ
23
24\begin{verbatim}
d30ff492 25class MySignallingThread : public wxThread
60ce696e
VZ
26{
27public:
d30ff492 28 MySignallingThread(wxMutex *mutex, wxCondition *condition)
60ce696e 29 {
be809868 30 m_mutex = mutex;
60ce696e
VZ
31 m_condition = condition;
32
33 Create();
34 }
35
36 virtual ExitCode Entry()
37 {
60ce696e
VZ
38 ... do our job ...
39
d30ff492
VZ
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
60ce696e
VZ
46 return 0;
47 }
48
49private:
50 wxCondition *m_condition;
d30ff492 51 wxMutex *m_mutex;
60ce696e
VZ
52};
53
54int main()
55{
be809868 56 wxMutex mutex;
c112e100 57 wxCondition condition(mutex);
be809868 58
d30ff492
VZ
59 // the mutex should be initially locked
60 mutex.Lock();
60ce696e 61
d30ff492
VZ
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);
60ce696e 65
d30ff492 66 thread->Run();
be809868 67
d30ff492
VZ
68 // wait for the thread termination: Wait() atomically unlocks the mutex
69 // which allows the thread to continue and starts waiting
70 condition.Wait();
60ce696e 71
d30ff492 72 // now we can exit
60ce696e
VZ
73 return 0;
74}
75\end{verbatim}
f6bcfd97 76
d30ff492
VZ
77Of course, here it would be much better to simply use a joinable thread and
78call \helpref{wxThread::Wait}{wxthreadwait} on it, but this example does
79illustrate the importance of properly locking the mutex when using
80wxCondition.
81
eaaa6a06
JS
82\wxheading{Derived from}
83
84None.
85
954b8ae6
JS
86\wxheading{Include files}
87
88<wx/thread.h>
89
eaaa6a06
JS
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
c112e100 98\func{}{wxCondition}{\param{wxMutex\& }{mutex}}
eaaa6a06 99
c112e100
VZ
100Default and only constructor. The {\it mutex} must be locked by the caller
101before calling \helpref{Wait}{wxconditionwait} function.
eaaa6a06
JS
102
103\membersection{wxCondition::\destruct{wxCondition}}
104
105\func{}{\destruct{wxCondition}}{\void}
106
be809868
VZ
107Destroys the wxCondition object. The destructor is not virtual so this class
108should not be used polymorphically.
eaaa6a06
JS
109
110\membersection{wxCondition::Broadcast}\label{wxconditionbroadcast}
111
112\func{void}{Broadcast}{\void}
113
be809868
VZ
114Broadcasts to all waiting threads, waking all of them up. Note that this method
115may be called whether the mutex associated with this condition is locked or
116not.
117
118\wxheading{See also}
119
120\helpref{wxCondition::Signal}{wxconditionsignal}
eaaa6a06
JS
121
122\membersection{wxCondition::Signal}\label{wxconditionsignal}
123
124\func{void}{Signal}{\void}
125
be809868
VZ
126Signals the object waking up at most one thread. If several threads are waiting
127on the same condition, the exact thread which is woken up is undefined. If no
128threads are waiting, the signal is lost and the condition would have to be
129signalled again to wake up any thread which may start waiting on it later.
130
131Note that this method may be called whether the mutex associated with this
132condition is locked or not.
133
134\wxheading{See also}
135
136\helpref{wxCondition::Broadcast}{wxconditionbroadcast}
eaaa6a06
JS
137
138\membersection{wxCondition::Wait}\label{wxconditionwait}
139
f6bcfd97 140\func{void}{Wait}{\void}
eaaa6a06 141
be809868 142Waits until the condition is signalled.
eaaa6a06 143
f6bcfd97 144\func{bool}{Wait}{\param{unsigned long}{ sec}, \param{unsigned long}{ nsec}}
eaaa6a06 145
be809868
VZ
146Waits until the condition is signalled or the timeout has elapsed.
147
148Note that the mutex associated with this condition {\bf must} be acquired by
149the thread before calling this method.
eaaa6a06
JS
150
151\wxheading{Parameters}
152
eaaa6a06
JS
153\docparam{sec}{Timeout in seconds}
154
155\docparam{nsec}{Timeout nanoseconds component (added to {\it sec}).}
156
157\wxheading{Return value}
158
cc81d32f
VS
159The second form returns {\tt true} if the condition has been signalled, or
160{\tt false} if it returned because the timeout has elapsed.
be809868 161
eaaa6a06 162