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