Commit | Line | Data |
---|---|---|
eaaa6a06 JS |
1 | \section{\class{wxThread}}\label{wxthread} |
2 | ||
6e6110ee | 3 | A thread is basically a path of execution through a program. Threads are also |
631f1bfe | 4 | sometimes called {\it light-weight processes}, but the fundamental difference |
6e6110ee VZ |
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 | |
631f1bfe | 8 | easier to shoot oneself in the foot, so careful use of synchronization objects |
28d9589a | 9 | such as \helpref{mutexes}{wxmutex} and/or \helpref{critical sections}{wxcriticalsection} is recommended. |
eaaa6a06 | 10 | |
9fc3ad34 VZ |
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 | ||
eaaa6a06 JS |
30 | \wxheading{Derived from} |
31 | ||
32 | None. | |
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 |
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. | |
eaaa6a06 JS |
51 | |
52 | \membersection{wxThread::\destruct{wxThread}} | |
53 | ||
54 | \func{}{\destruct{wxThread}}{\void} | |
55 | ||
9063ea8e VZ |
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. | |
eaaa6a06 JS |
66 | |
67 | \membersection{wxThread::Create}\label{wxthreadcreate} | |
68 | ||
69 | \func{wxThreadError}{Create}{\void} | |
70 | ||
28d9589a VZ |
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. | |
eaaa6a06 JS |
73 | |
74 | \wxheading{Return value} | |
75 | ||
76 | One 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 |
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 | ||
9fc3ad34 VZ |
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. | |
109 | ||
9063ea8e VZ |
110 | For detached threads Delete() will also delete the C++ thread object, but it |
111 | will not do this for joinable ones. | |
eaaa6a06 | 112 | |
9063ea8e | 113 | This 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 | |
119 | This is the entry point of the thread. This function is pure virtual and must | |
120 | be implemented by any derived class. The thread execution will start here. | |
121 | ||
9063ea8e VZ |
122 | The returned value is the thread exit code which is only useful for the |
123 | joinable threads and is the value returned by \helpref{Wait}{wxthreadwait}. | |
43191e0c | 124 | |
9063ea8e VZ |
125 | This function is called by wxWindows itself and should never be called |
126 | directly. | |
eaaa6a06 | 127 | |
9063ea8e VZ |
128 | \membersection{wxThread::GetId}\label{wxthreadgetid} |
129 | ||
130 | \constfunc{unsigned long}{GetId}{\void} | |
eaaa6a06 | 131 | |
28d9589a VZ |
132 | Gets the thread identifier: this is a platform dependent number which uniquely identifies the |
133 | thread 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 | ||
139 | Gets the priority of the thread, between zero and 100. | |
140 | ||
9063ea8e | 141 | The 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 | 154 | Returns 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 | ||
160 | Returns 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 | 166 | Returns 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 | ||
172 | Returns 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 |
178 | Returns TRUE if the thread is running. |
179 | ||
180 | \membersection{wxThread::Kill}\label{wxthreadkill} | |
181 | ||
182 | \func{wxThreadError}{Kill}{\void} | |
183 | ||
184 | Immediately terminates the target thread. {\bf This function is dangerous and should | |
185 | be used with extreme care (and not used at all whenever possible)!} The resources | |
186 | allocated to the thread will not be freed and the state of the C runtime library | |
187 | may become inconsistent. Use \helpref{Delete()}{wxthreaddelete} instead. | |
eaaa6a06 | 188 | |
9063ea8e VZ |
189 | For detached threads Kill() will also delete the associated C++ object. |
190 | ||
191 | This 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 |
197 | Called when the thread exits. This function is called in the context of the thread |
198 | associated with the wxThread object, not in the context of the main thread. | |
eaaa6a06 | 199 | |
9063ea8e VZ |
200 | This function should never be called directly. |
201 | ||
202 | \membersection{wxThread::Pause}\label{wxthreadpause} | |
203 | ||
204 | \func{wxThreadError}{Pause}{\void} | |
205 | ||
206 | Suspends the thread. Under some implementations (Win32), the thread is | |
207 | suspended immediately, under others it will only be suspended when it calls | |
208 | \helpref{TestDestroy}{wxthreadtestdestroy} for the next time (hence, if the | |
209 | thread doesn't call it at all, it won't be suspended). | |
210 | ||
211 | This 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 |
217 | Starts the thread execution. Should be called after |
218 | \helpref{Create}{wxthreadcreate}. | |
219 | ||
220 | This 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 | ||
226 | Sets the priority of the thread, between zero and 100. This must be set before the thread is created. | |
227 | ||
228 | The 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 | |
241 | Pauses the thread execution for the given amount of time. | |
242 | ||
243 | This 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 | ||
250 | Resumes a thread suspended by the call to \helpref{Pause}{wxthreadpause}. | |
251 | ||
252 | This function can only be called from another thread context. | |
253 | ||
254 | \membersection{wxThread::TestDestroy}\label{wxthreadtestdestroy} | |
255 | ||
256 | \func{bool}{TestDestroy}{\void} | |
257 | ||
258 | This function should be periodically called by the thread to ensure that calls | |
259 | to \helpref{Pause}{wxthreadpause} and \helpref{Delete}{wxthreaddelete} will | |
260 | work. 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 | |
266 | Return the thread object for the calling thread. NULL is returned if the calling thread | |
267 | is the main (GUI) thread, but \helpref{IsMain}{wxthreadismain} should be used to test | |
268 | whether the thread is really the main one because NULL may also be returned for the thread | |
269 | not created with wxThread class. Generally speaking, the return value for such thread | |
270 | is undefined. | |
271 | ||
272 | \membersection{wxThread::Yield}\label{wxthreadyield} | |
273 | ||
9063ea8e | 274 | \func{void}{Yield}{\void} |
28d9589a VZ |
275 | |
276 | Give the rest of the thread time slice to the system allowing the other threads to run. | |
277 | See also \helpref{Sleep()}{wxthreadsleep}. | |
e2a6f233 | 278 | |
9063ea8e VZ |
279 | \membersection{wxThread::Wait}\label{wxthreadwait} |
280 | ||
281 | \constfunc{ExitCode}{Wait}{\void} | |
282 | ||
283 | Waits until the thread terminates and returns its exit code or {\tt | |
284 | (ExitCode)-1} on error. | |
285 | ||
286 | You can only Wait() for joinable (not detached) threads. | |
287 | ||
288 | This function can only be called from another thread context. |