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