]> git.saurik.com Git - wxWidgets.git/blame - docs/latex/wx/thread.tex
Set/GetWindowMenu added to MDI parent frame under MSW
[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
2f02cb89
VZ
108the memory occupied by the thread object. However, you should not call Delete()
109on a detached thread which already terminated - doing so will probably result
110in a crash because the thread object doesn't exist any more.
9fc3ad34 111
9063ea8e
VZ
112For detached threads Delete() will also delete the C++ thread object, but it
113will not do this for joinable ones.
eaaa6a06 114
9063ea8e 115This function can only be called from another thread context.
eaaa6a06 116
43191e0c
VZ
117\membersection{wxThread::Entry}\label{wxthreadentry}
118
9063ea8e 119\func{virtual ExitCode}{Entry}{\void}
43191e0c
VZ
120
121This is the entry point of the thread. This function is pure virtual and must
122be implemented by any derived class. The thread execution will start here.
123
9063ea8e
VZ
124The returned value is the thread exit code which is only useful for the
125joinable threads and is the value returned by \helpref{Wait}{wxthreadwait}.
43191e0c 126
9063ea8e
VZ
127This function is called by wxWindows itself and should never be called
128directly.
eaaa6a06 129
ef8d96c2
VZ
130\membersection{wxThread::GetCPUCount}\label{wxthreadgetcpucount}
131
132\func{static int}{GetCPUCount}{\void}
133
134Returns the number of system CPUs or -1 if the value is unknown.
135
136\wxheading{See also}
137
138\helpref{SetConcurrency}{wxthreadsetconcurrency}
139
9063ea8e
VZ
140\membersection{wxThread::GetId}\label{wxthreadgetid}
141
142\constfunc{unsigned long}{GetId}{\void}
eaaa6a06 143
28d9589a
VZ
144Gets the thread identifier: this is a platform dependent number which uniquely identifies the
145thread throughout the system during its existence (i.e. the thread identifiers may be reused).
eaaa6a06
JS
146
147\membersection{wxThread::GetPriority}\label{wxthreadgetpriority}
148
149\constfunc{int}{GetPriority}{\void}
150
151Gets the priority of the thread, between zero and 100.
152
9063ea8e 153The following priorities are defined:
eaaa6a06
JS
154
155\twocolwidtha{7cm}
156\begin{twocollist}\itemsep=0pt
e14dccff
KB
157\twocolitem{{\bf WXTHREAD\_MIN\_PRIORITY}}{0}
158\twocolitem{{\bf WXTHREAD\_DEFAULT\_PRIORITY}}{50}
159\twocolitem{{\bf WXTHREAD\_MAX\_PRIORITY}}{100}
eaaa6a06
JS
160\end{twocollist}
161
162\membersection{wxThread::IsAlive}\label{wxthreadisalive}
163
164\constfunc{bool}{IsAlive}{\void}
165
28d9589a 166Returns TRUE if the thread is alive (i.e. started and not terminating).
eaaa6a06 167
9063ea8e
VZ
168\membersection{wxThread::IsDetached}\label{wxthreadisdetached}
169
170\constfunc{bool}{IsDetached}{\void}
171
172Returns TRUE if the thread is of detached kind, FALSE if it is a joinable one.
173
eaaa6a06
JS
174\membersection{wxThread::IsMain}\label{wxthreadismain}
175
9063ea8e 176\func{static bool}{IsMain}{\void}
eaaa6a06 177
6e6110ee 178Returns TRUE if the calling thread is the main application thread.
eaaa6a06 179
28d9589a
VZ
180\membersection{wxThread::IsPaused}\label{wxthreadispaused}
181
182\constfunc{bool}{IsPaused}{\void}
183
184Returns TRUE if the thread is paused.
185
186\membersection{wxThread::IsRunning}\label{wxthreadisrunning}
eaaa6a06 187
28d9589a 188\constfunc{bool}{IsRunning}{\void}
eaaa6a06 189
28d9589a
VZ
190Returns TRUE if the thread is running.
191
192\membersection{wxThread::Kill}\label{wxthreadkill}
193
194\func{wxThreadError}{Kill}{\void}
195
196Immediately terminates the target thread. {\bf This function is dangerous and should
197be used with extreme care (and not used at all whenever possible)!} The resources
198allocated to the thread will not be freed and the state of the C runtime library
199may become inconsistent. Use \helpref{Delete()}{wxthreaddelete} instead.
eaaa6a06 200
9063ea8e
VZ
201For detached threads Kill() will also delete the associated C++ object.
202
203This function can only be called from another thread context.
204
eaaa6a06
JS
205\membersection{wxThread::OnExit}\label{wxthreadonexit}
206
207\func{void}{OnExit}{\void}
208
28d9589a
VZ
209Called when the thread exits. This function is called in the context of the thread
210associated with the wxThread object, not in the context of the main thread.
eaaa6a06 211
9063ea8e
VZ
212This function should never be called directly.
213
214\membersection{wxThread::Pause}\label{wxthreadpause}
215
216\func{wxThreadError}{Pause}{\void}
217
218Suspends the thread. Under some implementations (Win32), the thread is
219suspended immediately, under others it will only be suspended when it calls
220\helpref{TestDestroy}{wxthreadtestdestroy} for the next time (hence, if the
221thread doesn't call it at all, it won't be suspended).
222
223This function can only be called from another thread context.
224
e2a6f233
JS
225\membersection{wxThread::Run}\label{wxthreadrun}
226
227\func{wxThreadError}{Run}{\void}
228
9063ea8e
VZ
229Starts the thread execution. Should be called after
230\helpref{Create}{wxthreadcreate}.
231
232This function can only be called from another thread context.
e2a6f233 233
eaaa6a06
JS
234\membersection{wxThread::SetPriority}\label{wxthreadsetpriority}
235
236\func{void}{SetPriority}{\param{int}{ priority}}
237
238Sets the priority of the thread, between zero and 100. This must be set before the thread is created.
239
240The following priorities are already defined:
241
242\twocolwidtha{7cm}
243\begin{twocollist}\itemsep=0pt
e14dccff
KB
244\twocolitem{{\bf WXTHREAD\_MIN\_PRIORITY}}{0}
245\twocolitem{{\bf WXTHREAD\_DEFAULT\_PRIORITY}}{50}
246\twocolitem{{\bf WXTHREAD\_MAX\_PRIORITY}}{100}
eaaa6a06 247\end{twocollist}
28d9589a
VZ
248
249\membersection{wxThread::Sleep}\label{wxthreadsleep}
250
9063ea8e 251\func{static void}{Sleep}{\param{unsigned long }{milliseconds}}
28d9589a
VZ
252
253Pauses the thread execution for the given amount of time.
254
255This function should be used instead of \helpref{wxSleep}{wxsleep} by all worker
256(i.e. all except the main one) threads.
257
9063ea8e
VZ
258\membersection{wxThread::Resume}\label{wxthreadresume}
259
260\func{wxThreadError}{Resume}{\void}
261
262Resumes a thread suspended by the call to \helpref{Pause}{wxthreadpause}.
263
264This function can only be called from another thread context.
265
ef8d96c2
VZ
266\membersection{wxThread::SetConcurrency}\label{wxthreadsetconcurrency}
267
268\func{static bool}{SetConcurrency}{\param{size\_t }{level}}
269
270Sets the thread concurrency level for this process. This is, roughly, the
271number of threads that the system tries to schedule to run in parallel.
272The value of $0$ for {\it level} may be used to set the default one.
273
274Returns TRUE on success or FALSE otherwise (for example, if this function is
275not implemented for this platform (currently everything except Solaris)).
276
9063ea8e
VZ
277\membersection{wxThread::TestDestroy}\label{wxthreadtestdestroy}
278
279\func{bool}{TestDestroy}{\void}
280
281This function should be periodically called by the thread to ensure that calls
282to \helpref{Pause}{wxthreadpause} and \helpref{Delete}{wxthreaddelete} will
283work. If it returns TRUE, the thread should exit as soon as possible.
284
28d9589a
VZ
285\membersection{wxThread::This}\label{wxthreadthis}
286
9063ea8e 287\func{static wxThread *}{This}{\void}
28d9589a
VZ
288
289Return the thread object for the calling thread. NULL is returned if the calling thread
290is the main (GUI) thread, but \helpref{IsMain}{wxthreadismain} should be used to test
291whether the thread is really the main one because NULL may also be returned for the thread
292not created with wxThread class. Generally speaking, the return value for such thread
293is undefined.
294
295\membersection{wxThread::Yield}\label{wxthreadyield}
296
9063ea8e 297\func{void}{Yield}{\void}
28d9589a
VZ
298
299Give the rest of the thread time slice to the system allowing the other threads to run.
300See also \helpref{Sleep()}{wxthreadsleep}.
e2a6f233 301
9063ea8e
VZ
302\membersection{wxThread::Wait}\label{wxthreadwait}
303
304\constfunc{ExitCode}{Wait}{\void}
305
306Waits until the thread terminates and returns its exit code or {\tt
307(ExitCode)-1} on error.
308
309You can only Wait() for joinable (not detached) threads.
310
311This function can only be called from another thread context.