joinable and detached POSIX threads (not fully tested yet)
[wxWidgets.git] / docs / latex / wx / thread.tex
CommitLineData
eaaa6a06
JS
1\section{\class{wxThread}}\label{wxthread}
2
6e6110ee 3A thread is basically a path of execution through a program. Threads are also
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
VZ
11There are two types of threads in wxWindows: {\it detached} and {\it joinable}
12ones, just as in POSIX thread API (but unlike Win32 threads where all threads
13are joinable). The difference between the two is that only joinbale threads
14can return a return code - it is returned by Wait() function. The detached
15threads (default) can not be waited for.
16
17You shouldn't hurry to create all the threads joinable, however, because this
18has a disadvantage as well: you {\bf must} Wait() for a joinable thread of the
19system resources used by it will never be freed and you also must delete the
20corresponding wxThread object yourself, while detached threads are of the
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
25heap because the thread will call {\tt delete this;} upon termination. The
26joinable threads may be created on stack (don't create global thread objects
27because they allocate memory in their constructor which is a badthing to do),
28although usually they will be created on the heap as well.
29
eaaa6a06
JS
30\wxheading{Derived from}
31
32None.
33
954b8ae6
JS
34\wxheading{Include files}
35
36<wx/thread.h>
37
eaaa6a06
JS
38\wxheading{See also}
39
e2a6f233 40\helpref{wxMutex}{wxmutex}, \helpref{wxCondition}{wxcondition}, \helpref{wxCriticalSection}{wxcriticalsection}
eaaa6a06
JS
41
42\latexignore{\rtfignore{\wxheading{Members}}}
43
28d9589a 44\membersection{wxThread::wxThread}\label{wxthreadctor}
eaaa6a06
JS
45
46\func{}{wxThread}{\void}
47
9063ea8e
VZ
48Constructor creates a new detached (default) or joinable C++ thread object. It
49does not create (or starts execution of) the real thread - for this you should
50use \helpref{Create}{wxthreadcreate} and \helpref{Run}{wxthreadrun} methods.
eaaa6a06
JS
51
52\membersection{wxThread::\destruct{wxThread}}
53
54\func{}{\destruct{wxThread}}{\void}
55
9063ea8e
VZ
56Destructor frees the ressources associated with the thread. Notice that you
57should never delete a detached thread - you may only call
58\helpref{Delete}{wxthreaddelete} on it or wait until it terminates (and auto
59destructs) itself. Because the detached threads delete themselves, they can
60only be allocated on the heap.
61
62The joinable threads, however, may and should be deleted explicitly and
63\helpref{Delete}{wxthreaddelete} and \helpref{Kill}{wxthreadkill} functions
64will not delete the C++ thread object. It is also safe to allocate them on
65stack.
eaaa6a06
JS
66
67\membersection{wxThread::Create}\label{wxthreadcreate}
68
69\func{wxThreadError}{Create}{\void}
70
28d9589a
VZ
71Creates a new thread. The thread object is created in the suspended state, you
72should call \helpref{Run}{wxthreadrun} to start running it.
eaaa6a06
JS
73
74\wxheading{Return value}
75
76One of:
77
78\twocolwidtha{7cm}
79\begin{twocollist}\itemsep=0pt
6e6110ee
VZ
80\twocolitem{{\bf wxTHREAD\_NO\_ERROR}}{There was no error.}
81\twocolitem{{\bf wxTHREAD\_NO\_RESOURCE}}{There were insufficient resources to create a new thread.}
82\twocolitem{{\bf wxTHREAD\_RUNNING}}{The thread is already running.}
eaaa6a06
JS
83\end{twocollist}
84
28d9589a 85\membersection{wxThread::Delete}\label{wxthreaddelete}
eaaa6a06 86
43191e0c 87\func{void}{Delete}{\void}
eaaa6a06 88
9063ea8e
VZ
89Calling \helpref{Delete}{wxthreaddelete} is a graceful way to terminate the
90thread. It asks the thread to terminate and, if the thread code is well
91written, the thread will terminate after the next call to
92\helpref{TestDestroy}{wxthreadtestdestroy} which should happen quiet soon.
93
94However, if the thread doesn't call \helpref{TestDestroy}{wxthreadtestdestroy}
95often enough (or at all), the function will not return immediately, but wait
96until the thread terminates. As it may take a long time, the message processing
97is not stopped during this function execution, so the message handlers may be
98called from inside it!
99
100Delete() may be called for thread in any state: running, paused or even not yet
101created. Moreover, it must be called if \helpref{Create}{wxthreadcreate} or
102\helpref{Run}{wxthreadrun} failed for a detached thread to free the memory
103occupied by the thread object (it will be done in the destructor for joinable
104threads).
105
9fc3ad34
VZ
106Delete() may be called for thread in any state: running, paused or even not yet created. Moreover,
107it must be called if \helpref{Create}{wxthreadcreate} or \helpref{Run}{wxthreadrun} fail to free
108the memory occupied by the thread object.
109
9063ea8e
VZ
110For detached threads Delete() will also delete the C++ thread object, but it
111will not do this for joinable ones.
eaaa6a06 112
9063ea8e 113This function can only be called from another thread context.
eaaa6a06 114
43191e0c
VZ
115\membersection{wxThread::Entry}\label{wxthreadentry}
116
9063ea8e 117\func{virtual ExitCode}{Entry}{\void}
43191e0c
VZ
118
119This is the entry point of the thread. This function is pure virtual and must
120be implemented by any derived class. The thread execution will start here.
121
9063ea8e
VZ
122The returned value is the thread exit code which is only useful for the
123joinable threads and is the value returned by \helpref{Wait}{wxthreadwait}.
43191e0c 124
9063ea8e
VZ
125This function is called by wxWindows itself and should never be called
126directly.
eaaa6a06 127
9063ea8e
VZ
128\membersection{wxThread::GetId}\label{wxthreadgetid}
129
130\constfunc{unsigned long}{GetId}{\void}
eaaa6a06 131
28d9589a
VZ
132Gets the thread identifier: this is a platform dependent number which uniquely identifies the
133thread throughout the system during its existence (i.e. the thread identifiers may be reused).
eaaa6a06
JS
134
135\membersection{wxThread::GetPriority}\label{wxthreadgetpriority}
136
137\constfunc{int}{GetPriority}{\void}
138
139Gets the priority of the thread, between zero and 100.
140
9063ea8e 141The following priorities are defined:
eaaa6a06
JS
142
143\twocolwidtha{7cm}
144\begin{twocollist}\itemsep=0pt
e14dccff
KB
145\twocolitem{{\bf WXTHREAD\_MIN\_PRIORITY}}{0}
146\twocolitem{{\bf WXTHREAD\_DEFAULT\_PRIORITY}}{50}
147\twocolitem{{\bf WXTHREAD\_MAX\_PRIORITY}}{100}
eaaa6a06
JS
148\end{twocollist}
149
150\membersection{wxThread::IsAlive}\label{wxthreadisalive}
151
152\constfunc{bool}{IsAlive}{\void}
153
28d9589a 154Returns TRUE if the thread is alive (i.e. started and not terminating).
eaaa6a06 155
9063ea8e
VZ
156\membersection{wxThread::IsDetached}\label{wxthreadisdetached}
157
158\constfunc{bool}{IsDetached}{\void}
159
160Returns TRUE if the thread is of detached kind, FALSE if it is a joinable one.
161
eaaa6a06
JS
162\membersection{wxThread::IsMain}\label{wxthreadismain}
163
9063ea8e 164\func{static bool}{IsMain}{\void}
eaaa6a06 165
6e6110ee 166Returns TRUE if the calling thread is the main application thread.
eaaa6a06 167
28d9589a
VZ
168\membersection{wxThread::IsPaused}\label{wxthreadispaused}
169
170\constfunc{bool}{IsPaused}{\void}
171
172Returns TRUE if the thread is paused.
173
174\membersection{wxThread::IsRunning}\label{wxthreadisrunning}
eaaa6a06 175
28d9589a 176\constfunc{bool}{IsRunning}{\void}
eaaa6a06 177
28d9589a
VZ
178Returns TRUE if the thread is running.
179
180\membersection{wxThread::Kill}\label{wxthreadkill}
181
182\func{wxThreadError}{Kill}{\void}
183
184Immediately terminates the target thread. {\bf This function is dangerous and should
185be used with extreme care (and not used at all whenever possible)!} The resources
186allocated to the thread will not be freed and the state of the C runtime library
187may become inconsistent. Use \helpref{Delete()}{wxthreaddelete} instead.
eaaa6a06 188
9063ea8e
VZ
189For detached threads Kill() will also delete the associated C++ object.
190
191This function can only be called from another thread context.
192
eaaa6a06
JS
193\membersection{wxThread::OnExit}\label{wxthreadonexit}
194
195\func{void}{OnExit}{\void}
196
28d9589a
VZ
197Called when the thread exits. This function is called in the context of the thread
198associated with the wxThread object, not in the context of the main thread.
eaaa6a06 199
9063ea8e
VZ
200This function should never be called directly.
201
202\membersection{wxThread::Pause}\label{wxthreadpause}
203
204\func{wxThreadError}{Pause}{\void}
205
206Suspends the thread. Under some implementations (Win32), the thread is
207suspended immediately, under others it will only be suspended when it calls
208\helpref{TestDestroy}{wxthreadtestdestroy} for the next time (hence, if the
209thread doesn't call it at all, it won't be suspended).
210
211This function can only be called from another thread context.
212
e2a6f233
JS
213\membersection{wxThread::Run}\label{wxthreadrun}
214
215\func{wxThreadError}{Run}{\void}
216
9063ea8e
VZ
217Starts the thread execution. Should be called after
218\helpref{Create}{wxthreadcreate}.
219
220This function can only be called from another thread context.
e2a6f233 221
eaaa6a06
JS
222\membersection{wxThread::SetPriority}\label{wxthreadsetpriority}
223
224\func{void}{SetPriority}{\param{int}{ priority}}
225
226Sets the priority of the thread, between zero and 100. This must be set before the thread is created.
227
228The following priorities are already defined:
229
230\twocolwidtha{7cm}
231\begin{twocollist}\itemsep=0pt
e14dccff
KB
232\twocolitem{{\bf WXTHREAD\_MIN\_PRIORITY}}{0}
233\twocolitem{{\bf WXTHREAD\_DEFAULT\_PRIORITY}}{50}
234\twocolitem{{\bf WXTHREAD\_MAX\_PRIORITY}}{100}
eaaa6a06 235\end{twocollist}
28d9589a
VZ
236
237\membersection{wxThread::Sleep}\label{wxthreadsleep}
238
9063ea8e 239\func{static void}{Sleep}{\param{unsigned long }{milliseconds}}
28d9589a
VZ
240
241Pauses the thread execution for the given amount of time.
242
243This function should be used instead of \helpref{wxSleep}{wxsleep} by all worker
244(i.e. all except the main one) threads.
245
9063ea8e
VZ
246\membersection{wxThread::Resume}\label{wxthreadresume}
247
248\func{wxThreadError}{Resume}{\void}
249
250Resumes a thread suspended by the call to \helpref{Pause}{wxthreadpause}.
251
252This function can only be called from another thread context.
253
254\membersection{wxThread::TestDestroy}\label{wxthreadtestdestroy}
255
256\func{bool}{TestDestroy}{\void}
257
258This function should be periodically called by the thread to ensure that calls
259to \helpref{Pause}{wxthreadpause} and \helpref{Delete}{wxthreaddelete} will
260work. If it returns TRUE, the thread should exit as soon as possible.
261
28d9589a
VZ
262\membersection{wxThread::This}\label{wxthreadthis}
263
9063ea8e 264\func{static wxThread *}{This}{\void}
28d9589a
VZ
265
266Return the thread object for the calling thread. NULL is returned if the calling thread
267is the main (GUI) thread, but \helpref{IsMain}{wxthreadismain} should be used to test
268whether the thread is really the main one because NULL may also be returned for the thread
269not created with wxThread class. Generally speaking, the return value for such thread
270is undefined.
271
272\membersection{wxThread::Yield}\label{wxthreadyield}
273
9063ea8e 274\func{void}{Yield}{\void}
28d9589a
VZ
275
276Give the rest of the thread time slice to the system allowing the other threads to run.
277See also \helpref{Sleep()}{wxthreadsleep}.
e2a6f233 278
9063ea8e
VZ
279\membersection{wxThread::Wait}\label{wxthreadwait}
280
281\constfunc{ExitCode}{Wait}{\void}
282
283Waits until the thread terminates and returns its exit code or {\tt
284(ExitCode)-1} on error.
285
286You can only Wait() for joinable (not detached) threads.
287
288This function can only be called from another thread context.