]> git.saurik.com Git - wxWidgets.git/blob - docs/latex/wx/thread.tex
Applied patch [ 818336 ] Add timestamp to gzip out stream
[wxWidgets.git] / docs / latex / wx / thread.tex
1 \section{\class{wxThread}}\label{wxthread}
2
3 A thread is basically a path of execution through a program. Threads are
4 sometimes called {\it light-weight processes}, but the fundamental difference
5 between threads and processes is that memory spaces of different processes are
6 separated while all threads share the same address space. While it makes it
7 much easier to share common data between several threads, it also makes much
8 easier to shoot oneself in the foot, so careful use of synchronization objects
9 such as \helpref{mutexes}{wxmutex} and/or \helpref{critical sections}{wxcriticalsection} is recommended.
10
11 There are two types of threads in wxWindows: {\it detached} and {\it joinable}
12 ones, just as in the POSIX thread API (but unlike Win32 threads where all threads
13 are joinable). The difference between the two is that only joinable threads
14 can return a return code -- this is returned by the Wait() function. Detached
15 threads (the default type) cannot be waited for.
16
17 You shouldn't hurry to create all the threads joinable, however, because this
18 has a disadvantage as well: you {\bf must} Wait() for a joinable thread or the
19 system resources used by it will never be freed, and you also must delete the
20 corresponding wxThread object yourself. In contrast, detached threads are of the
21 "fire-and-forget" kind: you only have to start a detached thread and it will
22 terminate and destroy itself.
23
24 This means, of course, that all detached threads {\bf must} be created on the
25 heap because the thread will call {\tt delete this;} upon termination. Joinable
26 threads may be created on the stack although more usually they will be created
27 on the heap as well. Don't create global thread objects because they allocate
28 memory in their constructor, which will cause problems for the memory checking
29 system.
30
31 \wxheading{Derived from}
32
33 None.
34
35 \wxheading{Include files}
36
37 <wx/thread.h>
38
39 \wxheading{See also}
40
41 \helpref{wxMutex}{wxmutex}, \helpref{wxCondition}{wxcondition}, \helpref{wxCriticalSection}{wxcriticalsection}
42
43 \latexignore{\rtfignore{\wxheading{Members}}}
44
45
46 \membersection{wxThread::wxThread}\label{wxthreadctor}
47
48 \func{}{wxThread}{\param{wxThreadKind }{kind = wxTHREAD\_DETACHED}}
49
50 This constructor creates a new detached (default) or joinable C++ thread object. It
51 does not create or start execution of the real thread -- for this you should
52 use the \helpref{Create}{wxthreadcreate} and \helpref{Run}{wxthreadrun} methods.
53
54 The possible values for {\it kind} parameters are:
55
56 \twocolwidtha{7cm}
57 \begin{twocollist}\itemsep=0pt
58 \twocolitem{{\bf wxTHREAD\_DETACHED}}{Create a detached thread.}
59 \twocolitem{{\bf wxTHREAD\_JOINABLE}}{Create a joinable thread}
60 \end{twocollist}
61
62
63 \membersection{wxThread::\destruct{wxThread}}
64
65 \func{}{\destruct{wxThread}}{\void}
66
67 The destructor frees the resources associated with the thread. Notice that you
68 should never delete a detached thread -- you may only call
69 \helpref{Delete}{wxthreaddelete} on it or wait until it terminates (and auto
70 destructs) itself. Because the detached threads delete themselves, they can
71 only be allocated on the heap.
72
73 Joinable threads should be deleted explicitly. The \helpref{Delete}{wxthreaddelete} and \helpref{Kill}{wxthreadkill} functions
74 will not delete the C++ thread object. It is also safe to allocate them on
75 stack.
76
77
78 \membersection{wxThread::Create}\label{wxthreadcreate}
79
80 \func{wxThreadError}{Create}{\param{unsigned int }{stackSize = 0}}
81
82 Creates a new thread. The thread object is created in the suspended state, and you
83 should call \helpref{Run}{wxthreadrun} to start running it. You may optionally
84 specify the stack size to be allocated to it (Ignored on platforms that don't
85 support setting it explicitly, eg. Unix).
86
87 \wxheading{Return value}
88
89 One of:
90
91 \twocolwidtha{7cm}
92 \begin{twocollist}\itemsep=0pt
93 \twocolitem{{\bf wxTHREAD\_NO\_ERROR}}{There was no error.}
94 \twocolitem{{\bf wxTHREAD\_NO\_RESOURCE}}{There were insufficient resources to create a new thread.}
95 \twocolitem{{\bf wxTHREAD\_RUNNING}}{The thread is already running.}
96 \end{twocollist}
97
98
99 \membersection{wxThread::Delete}\label{wxthreaddelete}
100
101 \func{void}{Delete}{\void}
102
103 Calling \helpref{Delete}{wxthreaddelete} is a graceful way to terminate the
104 thread. It asks the thread to terminate and, if the thread code is well
105 written, the thread will terminate after the next call to
106 \helpref{TestDestroy}{wxthreadtestdestroy} which should happen quite soon.
107
108 However, if the thread doesn't call \helpref{TestDestroy}{wxthreadtestdestroy}
109 often enough (or at all), the function will not return immediately, but wait
110 until the thread terminates. As it may take a long time, and the message processing
111 is not stopped during this function execution, message handlers may be
112 called from inside it!
113
114 Delete() may be called for a thread in any state: running, paused or even not
115 yet created. Moreover, it must be called if \helpref{Create}{wxthreadcreate} or
116 \helpref{Run}{wxthreadrun} fail in order to free the memory occupied by the
117 thread object. However, you should not call Delete() on a detached thread which
118 already terminated -- doing so will probably result in a crash because the
119 thread object doesn't exist any more.
120
121 For detached threads Delete() will also delete the C++ thread object, but it
122 will not do this for joinable ones.
123
124 This function can only be called from another thread context.
125
126
127 \membersection{wxThread::Entry}\label{wxthreadentry}
128
129 \func{virtual ExitCode}{Entry}{\void}
130
131 This is the entry point of the thread. This function is pure virtual and must
132 be implemented by any derived class. The thread execution will start here.
133
134 The returned value is the thread exit code which is only useful for
135 joinable threads and is the value returned by \helpref{Wait}{wxthreadwait}.
136
137 This function is called by wxWindows itself and should never be called
138 directly.
139
140
141 \membersection{wxThread::Exit}\label{wxthreadexit}
142
143 \func{void}{Exit}{\param{ExitCode }{exitcode = 0}}
144
145 This is a protected function of the wxThread class and thus can only be called
146 from a derived class. It also can only be called in the context of this
147 thread, i.e. a thread can only exit from itself, not from another thread.
148
149 This function will terminate the OS thread (i.e. stop the associated path of
150 execution) and also delete the associated C++ object for detached threads.
151 \helpref{wxThread::OnExit}{wxthreadonexit} will be called just before exiting.
152
153
154 \membersection{wxThread::GetCPUCount}\label{wxthreadgetcpucount}
155
156 \func{static int}{GetCPUCount}{\void}
157
158 Returns the number of system CPUs or -1 if the value is unknown.
159
160 \wxheading{See also}
161
162 \helpref{SetConcurrency}{wxthreadsetconcurrency}
163
164
165 \membersection{wxThread::GetCurrentId}\label{wxthreadgetcurrentid}
166
167 \func{static unsigned long}{GetCurrentId}{\void}
168
169 Returns the platform specific thread ID of the current thread as a
170 long. This can be used to uniquely identify threads, even if they are
171 not wxThreads.
172
173
174 \membersection{wxThread::GetId}\label{wxthreadgetid}
175
176 \constfunc{unsigned long}{GetId}{\void}
177
178 Gets the thread identifier: this is a platform dependent number that uniquely identifies the
179 thread throughout the system during its existence (i.e. the thread identifiers may be reused).
180
181
182 \membersection{wxThread::GetPriority}\label{wxthreadgetpriority}
183
184 \constfunc{int}{GetPriority}{\void}
185
186 Gets the priority of the thread, between zero and 100.
187
188 The following priorities are defined:
189
190 \twocolwidtha{7cm}
191 \begin{twocollist}\itemsep=0pt
192 \twocolitem{{\bf WXTHREAD\_MIN\_PRIORITY}}{0}
193 \twocolitem{{\bf WXTHREAD\_DEFAULT\_PRIORITY}}{50}
194 \twocolitem{{\bf WXTHREAD\_MAX\_PRIORITY}}{100}
195 \end{twocollist}
196
197
198 \membersection{wxThread::IsAlive}\label{wxthreadisalive}
199
200 \constfunc{bool}{IsAlive}{\void}
201
202 Returns \true if the thread is alive (i.e. started and not terminating).
203
204 Note that this function can only be saely used with joinable threads, not
205 detached ones as the latter delete themselves and so when the real thread is
206 not alive any longer it is not possible to call this function neither because
207 the wxThread object doesn't exist any more as well.
208
209
210 \membersection{wxThread::IsDetached}\label{wxthreadisdetached}
211
212 \constfunc{bool}{IsDetached}{\void}
213
214 Returns \true if the thread is of the detached kind, \false if it is a joinable
215 one.
216
217
218 \membersection{wxThread::IsMain}\label{wxthreadismain}
219
220 \func{static bool}{IsMain}{\void}
221
222 Returns \true if the calling thread is the main application thread.
223
224
225 \membersection{wxThread::IsPaused}\label{wxthreadispaused}
226
227 \constfunc{bool}{IsPaused}{\void}
228
229 Returns \true if the thread is paused.
230
231
232 \membersection{wxThread::IsRunning}\label{wxthreadisrunning}
233
234 \constfunc{bool}{IsRunning}{\void}
235
236 Returns \true if the thread is running.
237
238 This method may only be safely used for joinable threads, see the remark in
239 \helpref{IsAlive}{wxthreadisalive}.
240
241
242 \membersection{wxThread::Kill}\label{wxthreadkill}
243
244 \func{wxThreadError}{Kill}{\void}
245
246 Immediately terminates the target thread. {\bf This function is dangerous and should
247 be used with extreme care (and not used at all whenever possible)!} The resources
248 allocated to the thread will not be freed and the state of the C runtime library
249 may become inconsistent. Use \helpref{Delete()}{wxthreaddelete} instead.
250
251 For detached threads Kill() will also delete the associated C++ object.
252 However this will not happen for joinable threads and this means that you will
253 still have to delete the wxThread object yourself to avoid memory leaks.
254 In neither case \helpref{OnExit}{wxthreadonexit} of the dying thread will be
255 called, so no thread-specific cleanup will be performed.
256
257 This function can only be called from another thread context, i.e. a thread
258 cannot kill itself.
259
260 It is also an error to call this function for a thread which is not running or
261 paused (in the latter case, the thread will be resumed first) -- if you do it,
262 a {\tt wxTHREAD\_NOT\_RUNNING} error will be returned.
263
264
265 \membersection{wxThread::OnExit}\label{wxthreadonexit}
266
267 \func{void}{OnExit}{\void}
268
269 Called when the thread exits. This function is called in the context of the
270 thread associated with the wxThread object, not in the context of the main
271 thread. This function will not be called if the thread was
272 \helpref{killed}{wxthreadkill}.
273
274 This function should never be called directly.
275
276
277 \membersection{wxThread::Pause}\label{wxthreadpause}
278
279 \func{wxThreadError}{Pause}{\void}
280
281 Suspends the thread. Under some implementations (Win32), the thread is
282 suspended immediately, under others it will only be suspended when it calls
283 \helpref{TestDestroy}{wxthreadtestdestroy} for the next time (hence, if the
284 thread doesn't call it at all, it won't be suspended).
285
286 This function can only be called from another thread context.
287
288
289 \membersection{wxThread::Run}\label{wxthreadrun}
290
291 \func{wxThreadError}{Run}{\void}
292
293 Starts the thread execution. Should be called after
294 \helpref{Create}{wxthreadcreate}.
295
296 This function can only be called from another thread context.
297
298
299 \membersection{wxThread::SetPriority}\label{wxthreadsetpriority}
300
301 \func{void}{SetPriority}{\param{int}{ priority}}
302
303 Sets the priority of the thread, between $0$ and $100$. It can only be set
304 after calling \helpref{Create()}{wxthreadcreate} but before calling
305 \helpref{Run()}{wxthreadrun}.
306
307 The following priorities are already defined:
308
309 \twocolwidtha{7cm}
310 \begin{twocollist}\itemsep=0pt
311 \twocolitem{{\bf WXTHREAD\_MIN\_PRIORITY}}{0}
312 \twocolitem{{\bf WXTHREAD\_DEFAULT\_PRIORITY}}{50}
313 \twocolitem{{\bf WXTHREAD\_MAX\_PRIORITY}}{100}
314 \end{twocollist}
315
316
317 \membersection{wxThread::Sleep}\label{wxthreadsleep}
318
319 \func{static void}{Sleep}{\param{unsigned long }{milliseconds}}
320
321 Pauses the thread execution for the given amount of time.
322
323 This function should be used instead of \helpref{wxSleep}{wxsleep} by all worker
324 threads (i.e. all except the main one).
325
326
327 \membersection{wxThread::Resume}\label{wxthreadresume}
328
329 \func{wxThreadError}{Resume}{\void}
330
331 Resumes a thread suspended by the call to \helpref{Pause}{wxthreadpause}.
332
333 This function can only be called from another thread context.
334
335
336 \membersection{wxThread::SetConcurrency}\label{wxthreadsetconcurrency}
337
338 \func{static bool}{SetConcurrency}{\param{size\_t }{level}}
339
340 Sets the thread concurrency level for this process. This is, roughly, the
341 number of threads that the system tries to schedule to run in parallel.
342 The value of $0$ for {\it level} may be used to set the default one.
343
344 Returns true on success or false otherwise (for example, if this function is
345 not implemented for this platform -- currently everything except Solaris).
346
347
348 \membersection{wxThread::TestDestroy}\label{wxthreadtestdestroy}
349
350 \func{bool}{TestDestroy}{\void}
351
352 This function should be called periodically by the thread to ensure that calls
353 to \helpref{Pause}{wxthreadpause} and \helpref{Delete}{wxthreaddelete} will
354 work. If it returns true, the thread should exit as soon as possible.
355
356
357 \membersection{wxThread::This}\label{wxthreadthis}
358
359 \func{static wxThread *}{This}{\void}
360
361 Return the thread object for the calling thread. NULL is returned if the calling thread
362 is the main (GUI) thread, but \helpref{IsMain}{wxthreadismain} should be used to test
363 whether the thread is really the main one because NULL may also be returned for the thread
364 not created with wxThread class. Generally speaking, the return value for such a thread
365 is undefined.
366
367
368 \membersection{wxThread::Yield}\label{wxthreadyield}
369
370 \func{void}{Yield}{\void}
371
372 Give the rest of the thread time slice to the system allowing the other threads to run.
373 See also \helpref{Sleep()}{wxthreadsleep}.
374
375
376 \membersection{wxThread::Wait}\label{wxthreadwait}
377
378 \constfunc{ExitCode}{Wait}{\void}
379
380 Waits until the thread terminates and returns its exit code or {\tt (ExitCode)-1} on error.
381
382 You can only Wait() for joinable (not detached) threads.
383
384 This function can only be called from another thread context.
385