]>
Commit | Line | Data |
---|---|---|
10b959e3 | 1 | ///////////////////////////////////////////////////////////////////////////// |
9e84b847 | 2 | // Name: wx/thread.h |
10b959e3 JS |
3 | // Purpose: Thread API |
4 | // Author: Guilhem Lavaux | |
bf1852e1 VZ |
5 | // Modified by: Vadim Zeitlin (modifications partly inspired by omnithreads |
6 | // package from Olivetti & Oracle Research Laboratory) | |
10b959e3 JS |
7 | // Created: 04/13/98 |
8 | // RCS-ID: $Id$ | |
9 | // Copyright: (c) Guilhem Lavaux | |
65571936 | 10 | // Licence: wxWindows licence |
10b959e3 JS |
11 | ///////////////////////////////////////////////////////////////////////////// |
12 | ||
9e84b847 VZ |
13 | #ifndef _WX_THREAD_H_ |
14 | #define _WX_THREAD_H_ | |
10b959e3 | 15 | |
9d133d87 VZ |
16 | // ---------------------------------------------------------------------------- |
17 | // headers | |
18 | // ---------------------------------------------------------------------------- | |
bf1852e1 VZ |
19 | |
20 | // get the value of wxUSE_THREADS configuration flag | |
9e84b847 | 21 | #include "wx/defs.h" |
9d133d87 VZ |
22 | |
23 | #if wxUSE_THREADS | |
6d167489 | 24 | |
a6b0bd49 VZ |
25 | // ---------------------------------------------------------------------------- |
26 | // constants | |
27 | // ---------------------------------------------------------------------------- | |
28 | ||
6d167489 | 29 | enum wxMutexError |
d524867f | 30 | { |
9e84b847 VZ |
31 | wxMUTEX_NO_ERROR = 0, // operation completed successfully |
32 | wxMUTEX_INVALID, // mutex hasn't been initialized | |
33 | wxMUTEX_DEAD_LOCK, // mutex is already locked by the calling thread | |
34 | wxMUTEX_BUSY, // mutex is already locked by another thread | |
35 | wxMUTEX_UNLOCKED, // attempt to unlock a mutex which is not locked | |
696d13ee | 36 | wxMUTEX_TIMEOUT, // LockTimeout() has timed out |
9e84b847 VZ |
37 | wxMUTEX_MISC_ERROR // any other error |
38 | }; | |
39 | ||
40 | enum wxCondError | |
41 | { | |
42 | wxCOND_NO_ERROR = 0, | |
43 | wxCOND_INVALID, | |
44 | wxCOND_TIMEOUT, // WaitTimeout() has timed out | |
45 | wxCOND_MISC_ERROR | |
46 | }; | |
47 | ||
48 | enum wxSemaError | |
49 | { | |
50 | wxSEMA_NO_ERROR = 0, | |
51 | wxSEMA_INVALID, // semaphore hasn't been initialized successfully | |
52 | wxSEMA_BUSY, // returned by TryWait() if Wait() would block | |
53 | wxSEMA_TIMEOUT, // returned by WaitTimeout() | |
54 | wxSEMA_OVERFLOW, // Post() would increase counter past the max | |
55 | wxSEMA_MISC_ERROR | |
6d167489 | 56 | }; |
10b959e3 | 57 | |
6d167489 | 58 | enum wxThreadError |
d524867f | 59 | { |
9fc3ad34 VZ |
60 | wxTHREAD_NO_ERROR = 0, // No error |
61 | wxTHREAD_NO_RESOURCE, // No resource left to create a new thread | |
62 | wxTHREAD_RUNNING, // The thread is already running | |
63 | wxTHREAD_NOT_RUNNING, // The thread isn't running | |
64 | wxTHREAD_KILLED, // Thread we waited for had to be killed | |
65 | wxTHREAD_MISC_ERROR // Some other error | |
6d167489 | 66 | }; |
10b959e3 | 67 | |
b568d04f VZ |
68 | enum wxThreadKind |
69 | { | |
70 | wxTHREAD_DETACHED, | |
71 | wxTHREAD_JOINABLE | |
72 | }; | |
73 | ||
bf1852e1 | 74 | // defines the interval of priority |
6d167489 VZ |
75 | enum |
76 | { | |
77 | WXTHREAD_MIN_PRIORITY = 0u, | |
78 | WXTHREAD_DEFAULT_PRIORITY = 50u, | |
79 | WXTHREAD_MAX_PRIORITY = 100u | |
80 | }; | |
10b959e3 | 81 | |
9e84b847 VZ |
82 | // There are 2 types of mutexes: normal mutexes and recursive ones. The attempt |
83 | // to lock a normal mutex by a thread which already owns it results in | |
84 | // undefined behaviour (it always works under Windows, it will almost always | |
85 | // result in a deadlock under Unix). Locking a recursive mutex in such | |
86 | // situation always succeeds and it must be unlocked as many times as it has | |
87 | // been locked. | |
88 | // | |
89 | // However recursive mutexes have several important drawbacks: first, in the | |
90 | // POSIX implementation, they're less efficient. Second, and more importantly, | |
91 | // they CAN NOT BE USED WITH CONDITION VARIABLES under Unix! Using them with | |
92 | // wxCondition will work under Windows and some Unices (notably Linux) but will | |
93 | // deadlock under other Unix versions (e.g. Solaris). As it might be difficult | |
94 | // to ensure that a recursive mutex is not used with wxCondition, it is a good | |
95 | // idea to avoid using recursive mutexes at all. Also, the last problem with | |
96 | // them is that some (older) Unix versions don't support this at all -- which | |
97 | // results in a configure warning when building and a deadlock when using them. | |
98 | enum wxMutexType | |
99 | { | |
100 | // normal mutex: try to always use this one | |
101 | wxMUTEX_DEFAULT, | |
102 | ||
103 | // recursive mutex: don't use these ones with wxCondition | |
104 | wxMUTEX_RECURSIVE | |
105 | }; | |
106 | ||
107 | // forward declarations | |
b5dbe15d VS |
108 | class WXDLLIMPEXP_FWD_BASE wxThreadHelper; |
109 | class WXDLLIMPEXP_FWD_BASE wxConditionInternal; | |
110 | class WXDLLIMPEXP_FWD_BASE wxMutexInternal; | |
111 | class WXDLLIMPEXP_FWD_BASE wxSemaphoreInternal; | |
112 | class WXDLLIMPEXP_FWD_BASE wxThreadInternal; | |
9e84b847 | 113 | |
d524867f | 114 | // ---------------------------------------------------------------------------- |
9d133d87 VZ |
115 | // A mutex object is a synchronization object whose state is set to signaled |
116 | // when it is not owned by any thread, and nonsignaled when it is owned. Its | |
117 | // name comes from its usefulness in coordinating mutually-exclusive access to | |
118 | // a shared resource. Only one thread at a time can own a mutex object. | |
a6b0bd49 | 119 | // ---------------------------------------------------------------------------- |
d524867f | 120 | |
9d133d87 VZ |
121 | // you should consider wxMutexLocker whenever possible instead of directly |
122 | // working with wxMutex class - it is safer | |
bb24c68f | 123 | class WXDLLIMPEXP_BASE wxMutex |
d524867f | 124 | { |
10b959e3 | 125 | public: |
bf1852e1 | 126 | // constructor & destructor |
9e84b847 VZ |
127 | // ------------------------ |
128 | ||
129 | // create either default (always safe) or recursive mutex | |
130 | wxMutex(wxMutexType mutexType = wxMUTEX_DEFAULT); | |
131 | ||
132 | // destroys the mutex kernel object | |
cb4f1ca4 | 133 | ~wxMutex(); |
10b959e3 | 134 | |
9e84b847 VZ |
135 | // test if the mutex has been created successfully |
136 | bool IsOk() const; | |
137 | ||
138 | // mutex operations | |
139 | // ---------------- | |
140 | ||
141 | // Lock the mutex, blocking on it until it is unlocked by the other thread. | |
142 | // The result of locking a mutex already locked by the current thread | |
143 | // depend on the mutex type. | |
144 | // | |
145 | // The caller must call Unlock() later if Lock() returned wxMUTEX_NO_ERROR. | |
cb4f1ca4 | 146 | wxMutexError Lock(); |
9e84b847 | 147 | |
696d13ee VZ |
148 | // Same as Lock() but return wxMUTEX_TIMEOUT if the mutex can't be locked |
149 | // during the given number of milliseconds | |
150 | wxMutexError LockTimeout(unsigned long ms); | |
151 | ||
9e84b847 VZ |
152 | // Try to lock the mutex: if it is currently locked, return immediately |
153 | // with an error. Otherwise the caller must call Unlock(). | |
cb4f1ca4 | 154 | wxMutexError TryLock(); |
10b959e3 | 155 | |
9e84b847 VZ |
156 | // Unlock the mutex. It is an error to unlock an already unlocked mutex |
157 | wxMutexError Unlock(); | |
a6b0bd49 | 158 | |
10b959e3 | 159 | protected: |
9fc3ad34 | 160 | wxMutexInternal *m_internal; |
be809868 VZ |
161 | |
162 | friend class wxConditionInternal; | |
9e84b847 VZ |
163 | |
164 | DECLARE_NO_COPY_CLASS(wxMutex) | |
10b959e3 JS |
165 | }; |
166 | ||
9d133d87 VZ |
167 | // a helper class which locks the mutex in the ctor and unlocks it in the dtor: |
168 | // this ensures that mutex is always unlocked, even if the function returns or | |
169 | // throws an exception before it reaches the end | |
bb24c68f | 170 | class WXDLLIMPEXP_BASE wxMutexLocker |
9d133d87 VZ |
171 | { |
172 | public: | |
173 | // lock the mutex in the ctor | |
be52b341 | 174 | wxMutexLocker(wxMutex& mutex) |
c096f614 | 175 | : m_isOk(false), m_mutex(mutex) |
be52b341 | 176 | { m_isOk = ( m_mutex.Lock() == wxMUTEX_NO_ERROR ); } |
9d133d87 | 177 | |
c096f614 | 178 | // returns true if mutex was successfully locked in ctor |
7c3d7e2d VZ |
179 | bool IsOk() const |
180 | { return m_isOk; } | |
9d133d87 VZ |
181 | |
182 | // unlock the mutex in dtor | |
7c3d7e2d VZ |
183 | ~wxMutexLocker() |
184 | { if ( IsOk() ) m_mutex.Unlock(); } | |
9d133d87 VZ |
185 | |
186 | private: | |
cb4f1ca4 VZ |
187 | // no assignment operator nor copy ctor |
188 | wxMutexLocker(const wxMutexLocker&); | |
189 | wxMutexLocker& operator=(const wxMutexLocker&); | |
190 | ||
9d133d87 | 191 | bool m_isOk; |
7c3d7e2d | 192 | wxMutex& m_mutex; |
9d133d87 VZ |
193 | }; |
194 | ||
195 | // ---------------------------------------------------------------------------- | |
196 | // Critical section: this is the same as mutex but is only visible to the | |
197 | // threads of the same process. For the platforms which don't have native | |
198 | // support for critical sections, they're implemented entirely in terms of | |
6d167489 VZ |
199 | // mutexes. |
200 | // | |
201 | // NB: wxCriticalSection object does not allocate any memory in its ctor | |
202 | // which makes it possible to have static globals of this class | |
9d133d87 VZ |
203 | // ---------------------------------------------------------------------------- |
204 | ||
6d167489 VZ |
205 | // in order to avoid any overhead under platforms where critical sections are |
206 | // just mutexes make all wxCriticalSection class functions inline | |
420b39aa | 207 | #if !defined(__WXMSW__) |
6d167489 | 208 | #define wxCRITSECT_IS_MUTEX 1 |
d42e3d59 | 209 | |
ca9e2173 SC |
210 | #ifdef __WXMAC__ |
211 | #define wxCRITSECT_INLINE | |
212 | #else | |
d42e3d59 | 213 | #define wxCRITSECT_INLINE inline |
ca9e2173 | 214 | #endif |
d1bab566 | 215 | #else // MSW |
6d167489 | 216 | #define wxCRITSECT_IS_MUTEX 0 |
d42e3d59 VZ |
217 | |
218 | #define wxCRITSECT_INLINE | |
f6ddc54a | 219 | #endif // MSW/!MSW |
bf1852e1 | 220 | |
3ad41c28 RR |
221 | enum wxCriticalSectionType |
222 | { | |
223 | // recursive critical section | |
224 | wxCRITSEC_DEFAULT, | |
225 | ||
226 | // non-recursive critical section | |
227 | wxCRITSEC_NON_RECURSIVE | |
228 | }; | |
229 | ||
bf1852e1 VZ |
230 | // you should consider wxCriticalSectionLocker whenever possible instead of |
231 | // directly working with wxCriticalSection class - it is safer | |
bb24c68f | 232 | class WXDLLIMPEXP_BASE wxCriticalSection |
9d133d87 VZ |
233 | { |
234 | public: | |
235 | // ctor & dtor | |
3ad41c28 | 236 | wxCRITSECT_INLINE wxCriticalSection( wxCriticalSectionType critSecType = wxCRITSEC_DEFAULT ); |
d42e3d59 | 237 | wxCRITSECT_INLINE ~wxCriticalSection(); |
9d133d87 | 238 | // enter the section (the same as locking a mutex) |
d42e3d59 | 239 | wxCRITSECT_INLINE void Enter(); |
9e84b847 | 240 | |
9d133d87 | 241 | // leave the critical section (same as unlocking a mutex) |
d42e3d59 | 242 | wxCRITSECT_INLINE void Leave(); |
9d133d87 VZ |
243 | |
244 | private: | |
6d167489 | 245 | #if wxCRITSECT_IS_MUTEX |
f6ddc54a | 246 | wxMutex m_mutex; |
6d167489 VZ |
247 | #elif defined(__WXMSW__) |
248 | // we can't allocate any memory in the ctor, so use placement new - | |
249 | // unfortunately, we have to hardcode the sizeof() here because we can't | |
dac348b9 VZ |
250 | // include windows.h from this public header and we also have to use the |
251 | // union to force the correct (i.e. maximal) alignment | |
9e84b847 | 252 | // |
1c6f2414 WS |
253 | // if CRITICAL_SECTION size changes in Windows, you'll get an assert from |
254 | // thread.cpp and will need to increase the buffer size | |
dac348b9 VZ |
255 | // |
256 | // finally, we need this typedef instead of declaring m_buffer directly | |
257 | // because otherwise the assert mentioned above wouldn't compile with some | |
258 | // compilers (notably CodeWarrior 8) | |
975b6bcf VZ |
259 | #ifdef __WIN64__ |
260 | typedef char wxCritSectBuffer[40]; | |
261 | #else // __WIN32__ | |
dac348b9 | 262 | typedef char wxCritSectBuffer[24]; |
975b6bcf | 263 | #endif |
dac348b9 VZ |
264 | union |
265 | { | |
266 | unsigned long m_dummy1; | |
267 | void *m_dummy2; | |
268 | ||
269 | wxCritSectBuffer m_buffer; | |
270 | }; | |
d1bab566 | 271 | #endif // Unix&OS2/Win32 |
9e84b847 VZ |
272 | |
273 | DECLARE_NO_COPY_CLASS(wxCriticalSection) | |
9d133d87 VZ |
274 | }; |
275 | ||
ca9e2173 | 276 | #if wxCRITSECT_IS_MUTEX && !defined(__WXMAC__) |
9e84b847 | 277 | // implement wxCriticalSection using mutexes |
3ad41c28 RR |
278 | inline wxCriticalSection::wxCriticalSection( wxCriticalSectionType critSecType ) |
279 | : m_mutex( critSecType == wxCRITSEC_DEFAULT ? wxMUTEX_RECURSIVE : wxMUTEX_DEFAULT ) { } | |
d42e3d59 | 280 | inline wxCriticalSection::~wxCriticalSection() { } |
9e84b847 | 281 | |
d42e3d59 VZ |
282 | inline void wxCriticalSection::Enter() { (void)m_mutex.Lock(); } |
283 | inline void wxCriticalSection::Leave() { (void)m_mutex.Unlock(); } | |
9e84b847 | 284 | #endif // wxCRITSECT_IS_MUTEX |
bf1852e1 | 285 | |
d42e3d59 VZ |
286 | #undef wxCRITSECT_INLINE |
287 | #undef wxCRITSECT_IS_MUTEX | |
288 | ||
9d133d87 | 289 | // wxCriticalSectionLocker is the same to critical sections as wxMutexLocker is |
87b6002d | 290 | // to mutexes |
bb24c68f | 291 | class WXDLLIMPEXP_BASE wxCriticalSectionLocker |
9d133d87 VZ |
292 | { |
293 | public: | |
9e84b847 VZ |
294 | wxCriticalSectionLocker(wxCriticalSection& cs) |
295 | : m_critsect(cs) | |
296 | { | |
297 | m_critsect.Enter(); | |
298 | } | |
9d133d87 | 299 | |
9e84b847 VZ |
300 | ~wxCriticalSectionLocker() |
301 | { | |
302 | m_critsect.Leave(); | |
303 | } | |
cb4f1ca4 | 304 | |
9e84b847 | 305 | private: |
bee503b0 | 306 | wxCriticalSection& m_critsect; |
9e84b847 VZ |
307 | |
308 | DECLARE_NO_COPY_CLASS(wxCriticalSectionLocker) | |
9d133d87 VZ |
309 | }; |
310 | ||
a6b0bd49 | 311 | // ---------------------------------------------------------------------------- |
be809868 VZ |
312 | // wxCondition models a POSIX condition variable which allows one (or more) |
313 | // thread(s) to wait until some condition is fulfilled | |
a6b0bd49 | 314 | // ---------------------------------------------------------------------------- |
d524867f | 315 | |
bb24c68f | 316 | class WXDLLIMPEXP_BASE wxCondition |
d524867f | 317 | { |
10b959e3 | 318 | public: |
9e84b847 VZ |
319 | // Each wxCondition object is associated with a (single) wxMutex object. |
320 | // The mutex object MUST be locked before calling Wait() | |
c112e100 | 321 | wxCondition(wxMutex& mutex); |
be809868 VZ |
322 | |
323 | // dtor is not virtual, don't use this class polymorphically | |
9fc3ad34 VZ |
324 | ~wxCondition(); |
325 | ||
c096f614 | 326 | // return true if the condition has been created successfully |
9e84b847 VZ |
327 | bool IsOk() const; |
328 | ||
be809868 | 329 | // NB: the associated mutex MUST be locked beforehand by the calling thread |
cb719f2e | 330 | // |
be809868 VZ |
331 | // it atomically releases the lock on the associated mutex |
332 | // and starts waiting to be woken up by a Signal()/Broadcast() | |
333 | // once its signaled, then it will wait until it can reacquire | |
334 | // the lock on the associated mutex object, before returning. | |
9e84b847 | 335 | wxCondError Wait(); |
9fc3ad34 | 336 | |
be809868 | 337 | // exactly as Wait() except that it may also return if the specified |
90e572f1 | 338 | // timeout elapses even if the condition hasn't been signalled: in this |
c096f614 VZ |
339 | // case, the return value is false, otherwise (i.e. in case of a normal |
340 | // return) it is true | |
cb719f2e | 341 | // |
90e572f1 MR |
342 | // the timeout parameter specifies an interval that needs to be waited for |
343 | // in milliseconds | |
9e84b847 | 344 | wxCondError WaitTimeout(unsigned long milliseconds); |
be809868 VZ |
345 | |
346 | // NB: the associated mutex may or may not be locked by the calling thread | |
347 | // | |
348 | // this method unblocks one thread if any are blocking on the condition. | |
349 | // if no thread is blocking in Wait(), then the signal is NOT remembered | |
90e572f1 | 350 | // The thread which was blocking on Wait() will then reacquire the lock |
be809868 | 351 | // on the associated mutex object before returning |
9e84b847 | 352 | wxCondError Signal(); |
a6b0bd49 | 353 | |
be809868 VZ |
354 | // NB: the associated mutex may or may not be locked by the calling thread |
355 | // | |
356 | // this method unblocks all threads if any are blocking on the condition. | |
357 | // if no thread is blocking in Wait(), then the signal is NOT remembered | |
90e572f1 | 358 | // The threads which were blocking on Wait() will then reacquire the lock |
be809868 | 359 | // on the associated mutex object before returning. |
9e84b847 VZ |
360 | wxCondError Broadcast(); |
361 | ||
362 | ||
40ff126a | 363 | #if WXWIN_COMPATIBILITY_2_6 |
9e84b847 | 364 | // deprecated version, don't use |
40ff126a WS |
365 | wxDEPRECATED( bool Wait(unsigned long milliseconds) ); |
366 | #endif // WXWIN_COMPATIBILITY_2_6 | |
8d5eff60 | 367 | |
10b959e3 | 368 | private: |
9fc3ad34 | 369 | wxConditionInternal *m_internal; |
9e84b847 VZ |
370 | |
371 | DECLARE_NO_COPY_CLASS(wxCondition) | |
10b959e3 JS |
372 | }; |
373 | ||
40ff126a WS |
374 | #if WXWIN_COMPATIBILITY_2_6 |
375 | inline bool wxCondition::Wait(unsigned long milliseconds) | |
376 | { return WaitTimeout(milliseconds) == wxCOND_NO_ERROR; } | |
377 | #endif // WXWIN_COMPATIBILITY_2_6 | |
378 | ||
a6b0bd49 | 379 | // ---------------------------------------------------------------------------- |
be809868 VZ |
380 | // wxSemaphore: a counter limiting the number of threads concurrently accessing |
381 | // a shared resource | |
382 | // ---------------------------------------------------------------------------- | |
383 | ||
bb24c68f | 384 | class WXDLLIMPEXP_BASE wxSemaphore |
be809868 VZ |
385 | { |
386 | public: | |
387 | // specifying a maxcount of 0 actually makes wxSemaphore behave as if there | |
388 | // is no upper limit, if maxcount is 1 the semaphore behaves as a mutex | |
389 | wxSemaphore( int initialcount = 0, int maxcount = 0 ); | |
390 | ||
391 | // dtor is not virtual, don't use this class polymorphically | |
392 | ~wxSemaphore(); | |
393 | ||
c096f614 | 394 | // return true if the semaphore has been created successfully |
9e84b847 VZ |
395 | bool IsOk() const; |
396 | ||
be809868 VZ |
397 | // wait indefinitely, until the semaphore count goes beyond 0 |
398 | // and then decrement it and return (this method might have been called | |
399 | // Acquire()) | |
9e84b847 | 400 | wxSemaError Wait(); |
be809868 | 401 | |
9e84b847 VZ |
402 | // same as Wait(), but does not block, returns wxSEMA_NO_ERROR if |
403 | // successful and wxSEMA_BUSY if the count is currently zero | |
404 | wxSemaError TryWait(); | |
be809868 | 405 | |
9e84b847 | 406 | // same as Wait(), but as a timeout limit, returns wxSEMA_NO_ERROR if the |
90e572f1 | 407 | // semaphore was acquired and wxSEMA_TIMEOUT if the timeout has elapsed |
9e84b847 | 408 | wxSemaError WaitTimeout(unsigned long milliseconds); |
be809868 VZ |
409 | |
410 | // increments the semaphore count and signals one of the waiting threads | |
9e84b847 | 411 | wxSemaError Post(); |
be809868 VZ |
412 | |
413 | private: | |
414 | wxSemaphoreInternal *m_internal; | |
9e84b847 VZ |
415 | |
416 | DECLARE_NO_COPY_CLASS(wxSemaphore) | |
be809868 VZ |
417 | }; |
418 | ||
419 | // ---------------------------------------------------------------------------- | |
87b6002d | 420 | // wxThread: class encapsulating a thread of execution |
a6b0bd49 | 421 | // ---------------------------------------------------------------------------- |
d524867f | 422 | |
b568d04f VZ |
423 | // there are two different kinds of threads: joinable and detached (default) |
424 | // ones. Only joinable threads can return a return code and only detached | |
425 | // threads auto-delete themselves - the user should delete the joinable | |
426 | // threads manually. | |
bf1852e1 VZ |
427 | |
428 | // NB: in the function descriptions the words "this thread" mean the thread | |
429 | // created by the wxThread object while "main thread" is the thread created | |
430 | // during the process initialization (a.k.a. the GUI thread) | |
b568d04f | 431 | |
547b93ab VZ |
432 | // On VMS thread pointers are 64 bits (also needed for other systems??? |
433 | #ifdef __VMS | |
434 | typedef unsigned long long wxThreadIdType; | |
435 | #else | |
436 | typedef unsigned long wxThreadIdType; | |
437 | #endif | |
438 | ||
bb24c68f | 439 | class WXDLLIMPEXP_BASE wxThread |
d524867f | 440 | { |
10b959e3 | 441 | public: |
bf1852e1 VZ |
442 | // the return type for the thread function |
443 | typedef void *ExitCode; | |
444 | ||
445 | // static functions | |
446 | // Returns the wxThread object for the calling thread. NULL is returned | |
447 | // if the caller is the main thread (but it's recommended to use | |
448 | // IsMain() and only call This() for threads other than the main one | |
449 | // because NULL is also returned on error). If the thread wasn't | |
450 | // created with wxThread class, the returned value is undefined. | |
451 | static wxThread *This(); | |
452 | ||
453 | // Returns true if current thread is the main thread. | |
454 | static bool IsMain(); | |
455 | ||
90e572f1 | 456 | // Release the rest of our time slice letting the other threads run |
bf1852e1 VZ |
457 | static void Yield(); |
458 | ||
459 | // Sleep during the specified period of time in milliseconds | |
460 | // | |
8cd8a7fe | 461 | // This is the same as wxMilliSleep(). |
bf1852e1 VZ |
462 | static void Sleep(unsigned long milliseconds); |
463 | ||
ef8d96c2 VZ |
464 | // get the number of system CPUs - useful with SetConcurrency() |
465 | // (the "best" value for it is usually number of CPUs + 1) | |
466 | // | |
467 | // Returns -1 if unknown, number of CPUs otherwise | |
468 | static int GetCPUCount(); | |
469 | ||
4958ea8f RD |
470 | // Get the platform specific thread ID and return as a long. This |
471 | // can be used to uniquely identify threads, even if they are not | |
472 | // wxThreads. This is used by wxPython. | |
547b93ab VZ |
473 | static wxThreadIdType GetCurrentId(); |
474 | ||
ef8d96c2 VZ |
475 | // sets the concurrency level: this is, roughly, the number of threads |
476 | // the system tries to schedule to run in parallel. 0 means the | |
477 | // default value (usually acceptable, but may not yield the best | |
478 | // performance for this process) | |
479 | // | |
c096f614 | 480 | // Returns true on success, false otherwise (if not implemented, for |
ef8d96c2 VZ |
481 | // example) |
482 | static bool SetConcurrency(size_t level); | |
483 | ||
b568d04f VZ |
484 | // constructor only creates the C++ thread object and doesn't create (or |
485 | // start) the real thread | |
486 | wxThread(wxThreadKind kind = wxTHREAD_DETACHED); | |
487 | ||
488 | // functions that change the thread state: all these can only be called | |
489 | // from _another_ thread (typically the thread that created this one, e.g. | |
490 | // the main thread), not from the thread itself | |
bf1852e1 | 491 | |
6fe73788 RL |
492 | // create a new thread and optionally set the stack size on |
493 | // platforms that support that - call Run() to start it | |
494 | // (special cased for watcom which won't accept 0 default) | |
495 | ||
6fe73788 | 496 | wxThreadError Create(unsigned int stackSize = 0); |
bf1852e1 | 497 | |
b568d04f VZ |
498 | // starts execution of the thread - from the moment Run() is called |
499 | // the execution of wxThread::Entry() may start at any moment, caller | |
bf1852e1 VZ |
500 | // shouldn't suppose that it starts after (or before) Run() returns. |
501 | wxThreadError Run(); | |
502 | ||
b568d04f VZ |
503 | // stops the thread if it's running and deletes the wxThread object if |
504 | // this is a detached thread freeing its memory - otherwise (for | |
505 | // joinable threads) you still need to delete wxThread object | |
506 | // yourself. | |
507 | // | |
508 | // this function only works if the thread calls TestDestroy() | |
509 | // periodically - the thread will only be deleted the next time it | |
510 | // does it! | |
511 | // | |
512 | // will fill the rc pointer with the thread exit code if it's !NULL | |
513 | wxThreadError Delete(ExitCode *rc = (ExitCode *)NULL); | |
514 | ||
515 | // waits for a joinable thread to finish and returns its exit code | |
516 | // | |
517 | // Returns (ExitCode)-1 on error (for example, if the thread is not | |
518 | // joinable) | |
519 | ExitCode Wait(); | |
bf1852e1 VZ |
520 | |
521 | // kills the thread without giving it any chance to clean up - should | |
90e572f1 MR |
522 | // not be used under normal circumstances, use Delete() instead. |
523 | // It is a dangerous function that should only be used in the most | |
524 | // extreme cases! | |
b568d04f VZ |
525 | // |
526 | // The wxThread object is deleted by Kill() if the thread is | |
527 | // detachable, but you still have to delete it manually for joinable | |
528 | // threads. | |
bf1852e1 VZ |
529 | wxThreadError Kill(); |
530 | ||
b568d04f VZ |
531 | // pause a running thread: as Delete(), this only works if the thread |
532 | // calls TestDestroy() regularly | |
bf1852e1 VZ |
533 | wxThreadError Pause(); |
534 | ||
535 | // resume a paused thread | |
536 | wxThreadError Resume(); | |
537 | ||
538 | // priority | |
539 | // Sets the priority to "prio": see WXTHREAD_XXX_PRIORITY constants | |
540 | // | |
541 | // NB: the priority can only be set before the thread is created | |
542 | void SetPriority(unsigned int prio); | |
543 | ||
544 | // Get the current priority. | |
545 | unsigned int GetPriority() const; | |
546 | ||
bf1852e1 VZ |
547 | // thread status inquiries |
548 | // Returns true if the thread is alive: i.e. running or suspended | |
549 | bool IsAlive() const; | |
550 | // Returns true if the thread is running (not paused, not killed). | |
551 | bool IsRunning() const; | |
552 | // Returns true if the thread is suspended | |
a737331d | 553 | bool IsPaused() const; |
bf1852e1 | 554 | |
b568d04f VZ |
555 | // is the thread of detached kind? |
556 | bool IsDetached() const { return m_isDetached; } | |
557 | ||
558 | // Get the thread ID - a platform dependent number which uniquely | |
559 | // identifies a thread inside a process | |
547b93ab | 560 | wxThreadIdType GetId() const; |
4958ea8f | 561 | |
bf1852e1 VZ |
562 | // called when the thread exits - in the context of this thread |
563 | // | |
564 | // NB: this function will not be called if the thread is Kill()ed | |
565 | virtual void OnExit() { } | |
10b959e3 | 566 | |
c096f614 VZ |
567 | // Returns true if the thread was asked to terminate: this function should |
568 | // be called by the thread from time to time, otherwise the main thread | |
569 | // will be left forever in Delete()! | |
570 | virtual bool TestDestroy(); | |
571 | ||
b568d04f VZ |
572 | // dtor is public, but the detached threads should never be deleted - use |
573 | // Delete() instead (or leave the thread terminate by itself) | |
574 | virtual ~wxThread(); | |
575 | ||
bf1852e1 | 576 | protected: |
bf1852e1 | 577 | // exits from the current thread - can be called only from this thread |
b568d04f | 578 | void Exit(ExitCode exitcode = 0); |
9d133d87 | 579 | |
bf1852e1 VZ |
580 | // entry point for the thread - called by Run() and executes in the context |
581 | // of this thread. | |
582 | virtual void *Entry() = 0; | |
a6b0bd49 | 583 | |
10b959e3 | 584 | private: |
bf1852e1 VZ |
585 | // no copy ctor/assignment operator |
586 | wxThread(const wxThread&); | |
587 | wxThread& operator=(const wxThread&); | |
10b959e3 | 588 | |
bf1852e1 VZ |
589 | friend class wxThreadInternal; |
590 | ||
591 | // the (platform-dependent) thread class implementation | |
9fc3ad34 | 592 | wxThreadInternal *m_internal; |
10b959e3 | 593 | |
bf1852e1 VZ |
594 | // protects access to any methods of wxThreadInternal object |
595 | wxCriticalSection m_critsect; | |
b568d04f VZ |
596 | |
597 | // true if the thread is detached, false if it is joinable | |
598 | bool m_isDetached; | |
10b959e3 JS |
599 | }; |
600 | ||
78ee6a47 VZ |
601 | // wxThreadHelperThread class |
602 | // -------------------------- | |
603 | ||
604 | class WXDLLIMPEXP_BASE wxThreadHelperThread : public wxThread | |
605 | { | |
606 | public: | |
607 | // constructor only creates the C++ thread object and doesn't create (or | |
608 | // start) the real thread | |
c4b64a94 VZ |
609 | wxThreadHelperThread(wxThreadHelper& owner, wxThreadKind kind) |
610 | : wxThread(kind), m_owner(owner) | |
78ee6a47 VZ |
611 | { } |
612 | ||
613 | protected: | |
614 | // entry point for the thread -- calls Entry() in owner. | |
615 | virtual void *Entry(); | |
616 | ||
617 | private: | |
618 | // the owner of the thread | |
619 | wxThreadHelper& m_owner; | |
620 | ||
621 | // no copy ctor/assignment operator | |
622 | wxThreadHelperThread(const wxThreadHelperThread&); | |
623 | wxThreadHelperThread& operator=(const wxThreadHelperThread&); | |
624 | }; | |
625 | ||
626 | // ---------------------------------------------------------------------------- | |
627 | // wxThreadHelper: this class implements the threading logic to run a | |
628 | // background task in another object (such as a window). It is a mix-in: just | |
629 | // derive from it to implement a threading background task in your class. | |
630 | // ---------------------------------------------------------------------------- | |
631 | ||
632 | class WXDLLIMPEXP_BASE wxThreadHelper | |
633 | { | |
634 | private: | |
635 | void KillThread() | |
636 | { | |
c4b64a94 VZ |
637 | // If detached thread is about to finish, it will set |
638 | // m_thread to NULL so don't delete it then | |
639 | // But if KillThread is called before detached thread | |
640 | // sets it to NULL, then the thread object still | |
641 | // exists and can be killed | |
642 | wxCriticalSectionLocker locker(m_critSection); | |
643 | ||
78ee6a47 VZ |
644 | if ( m_thread ) |
645 | { | |
646 | m_thread->Kill(); | |
c4b64a94 VZ |
647 | |
648 | if ( m_kind == wxTHREAD_JOINABLE ) | |
649 | delete m_thread; | |
650 | ||
651 | m_thread = NULL; | |
78ee6a47 VZ |
652 | } |
653 | } | |
654 | ||
655 | public: | |
656 | // constructor only initializes m_thread to NULL | |
c4b64a94 VZ |
657 | wxThreadHelper(wxThreadKind kind = wxTHREAD_JOINABLE) |
658 | : m_thread(NULL), m_kind(kind) { } | |
78ee6a47 VZ |
659 | |
660 | // destructor deletes m_thread | |
661 | virtual ~wxThreadHelper() { KillThread(); } | |
662 | ||
663 | // create a new thread (and optionally set the stack size on platforms that | |
664 | // support/need that), call Run() to start it | |
665 | wxThreadError Create(unsigned int stackSize = 0) | |
666 | { | |
667 | KillThread(); | |
668 | ||
c4b64a94 | 669 | m_thread = new wxThreadHelperThread(*this, m_kind); |
78ee6a47 VZ |
670 | |
671 | return m_thread->Create(stackSize); | |
672 | } | |
673 | ||
674 | // entry point for the thread - called by Run() and executes in the context | |
675 | // of this thread. | |
676 | virtual void *Entry() = 0; | |
677 | ||
678 | // returns a pointer to the thread which can be used to call Run() | |
c4b64a94 VZ |
679 | wxThread *GetThread() const |
680 | { | |
681 | wxCriticalSectionLocker locker((wxCriticalSection&)m_critSection); | |
682 | ||
683 | wxThread* thread = m_thread; | |
684 | ||
685 | return thread; | |
686 | } | |
78ee6a47 VZ |
687 | |
688 | protected: | |
689 | wxThread *m_thread; | |
c4b64a94 VZ |
690 | wxThreadKind m_kind; |
691 | wxCriticalSection m_critSection; // To guard the m_thread variable | |
692 | ||
693 | friend class wxThreadHelperThread; | |
78ee6a47 VZ |
694 | }; |
695 | ||
696 | // call Entry() in owner, put it down here to avoid circular declarations | |
697 | inline void *wxThreadHelperThread::Entry() | |
698 | { | |
c4b64a94 VZ |
699 | void * const result = m_owner.Entry(); |
700 | ||
701 | wxCriticalSectionLocker locker(m_owner.m_critSection); | |
702 | ||
703 | // Detached thread will be deleted after returning, so make sure | |
704 | // wxThreadHelper::GetThread will not return an invalid pointer. | |
705 | // And that wxThreadHelper::KillThread will not try to kill | |
706 | // an already deleted thread | |
707 | if ( m_owner.m_kind == wxTHREAD_DETACHED ) | |
708 | m_owner.m_thread = NULL; | |
709 | ||
710 | return result; | |
78ee6a47 VZ |
711 | } |
712 | ||
a6b0bd49 | 713 | // ---------------------------------------------------------------------------- |
d524867f | 714 | // Automatic initialization |
a6b0bd49 | 715 | // ---------------------------------------------------------------------------- |
10b959e3 | 716 | |
9d133d87 | 717 | // GUI mutex handling. |
bb24c68f VS |
718 | void WXDLLIMPEXP_BASE wxMutexGuiEnter(); |
719 | void WXDLLIMPEXP_BASE wxMutexGuiLeave(); | |
d524867f | 720 | |
72cdf4c9 VZ |
721 | // macros for entering/leaving critical sections which may be used without |
722 | // having to take them inside "#if wxUSE_THREADS" | |
b568d04f VZ |
723 | #define wxENTER_CRIT_SECT(cs) (cs).Enter() |
724 | #define wxLEAVE_CRIT_SECT(cs) (cs).Leave() | |
bdc72a22 | 725 | #define wxCRIT_SECT_DECLARE(cs) static wxCriticalSection cs |
db882c54 | 726 | #define wxCRIT_SECT_DECLARE_MEMBER(cs) wxCriticalSection cs |
b568d04f | 727 | #define wxCRIT_SECT_LOCKER(name, cs) wxCriticalSectionLocker name(cs) |
72cdf4c9 | 728 | |
17dbd230 VZ |
729 | // function for checking if we're in the main thread which may be used whether |
730 | // wxUSE_THREADS is 0 or 1 | |
731 | inline bool wxIsMainThread() { return wxThread::IsMain(); } | |
732 | ||
9d133d87 | 733 | #else // !wxUSE_THREADS |
d524867f | 734 | |
9d133d87 | 735 | // no thread support |
76de6a6e VZ |
736 | inline void wxMutexGuiEnter() { } |
737 | inline void wxMutexGuiLeave() { } | |
d524867f | 738 | |
72cdf4c9 VZ |
739 | // macros for entering/leaving critical sections which may be used without |
740 | // having to take them inside "#if wxUSE_THREADS" | |
e8ec9749 VS |
741 | // (the implementation uses dummy structs to force semicolon after the macro) |
742 | #define wxENTER_CRIT_SECT(cs) do {} while (0) | |
743 | #define wxLEAVE_CRIT_SECT(cs) do {} while (0) | |
744 | #define wxCRIT_SECT_DECLARE(cs) struct wxDummyCS##cs | |
745 | #define wxCRIT_SECT_DECLARE_MEMBER(cs) struct wxDummyCSMember##cs | |
746 | #define wxCRIT_SECT_LOCKER(name, cs) struct wxDummyCSLocker##name | |
72cdf4c9 | 747 | |
17dbd230 VZ |
748 | // if there is only one thread, it is always the main one |
749 | inline bool wxIsMainThread() { return true; } | |
750 | ||
9e84b847 | 751 | #endif // wxUSE_THREADS/!wxUSE_THREADS |
10b959e3 | 752 | |
4562f685 VZ |
753 | // mark part of code as being a critical section: this macro declares a |
754 | // critical section with the given name and enters it immediately and leaves | |
755 | // it at the end of the current scope | |
756 | // | |
757 | // example: | |
758 | // | |
759 | // int Count() | |
760 | // { | |
761 | // static int s_counter = 0; | |
762 | // | |
763 | // wxCRITICAL_SECTION(counter); | |
764 | // | |
765 | // return ++s_counter; | |
766 | // } | |
767 | // | |
768 | // this function is MT-safe in presence of the threads but there is no | |
769 | // overhead when the library is compiled without threads | |
770 | #define wxCRITICAL_SECTION(name) \ | |
771 | wxCRIT_SECT_DECLARE(s_cs##name); \ | |
772 | wxCRIT_SECT_LOCKER(cs##name##Locker, s_cs##name) | |
773 | ||
9e84b847 | 774 | // automatically lock GUI mutex in ctor and unlock it in dtor |
bb24c68f | 775 | class WXDLLIMPEXP_BASE wxMutexGuiLocker |
bee503b0 VZ |
776 | { |
777 | public: | |
778 | wxMutexGuiLocker() { wxMutexGuiEnter(); } | |
779 | ~wxMutexGuiLocker() { wxMutexGuiLeave(); } | |
780 | }; | |
781 | ||
f6ddc54a VZ |
782 | // ----------------------------------------------------------------------------- |
783 | // implementation only until the end of file | |
784 | // ----------------------------------------------------------------------------- | |
dcda1c71 | 785 | |
9838df2c | 786 | #if wxUSE_THREADS |
dcda1c71 | 787 | |
420b39aa | 788 | #if defined(__WXMSW__) || defined(__OS2__) || defined(__EMX__) |
f6ddc54a VZ |
789 | // unlock GUI if there are threads waiting for and lock it back when |
790 | // there are no more of them - should be called periodically by the main | |
791 | // thread | |
bb24c68f | 792 | extern void WXDLLIMPEXP_BASE wxMutexGuiLeaveOrEnter(); |
f6ddc54a | 793 | |
c096f614 | 794 | // returns true if the main thread has GUI lock |
bb24c68f | 795 | extern bool WXDLLIMPEXP_BASE wxGuiOwnedByMainThread(); |
f6ddc54a VZ |
796 | |
797 | // wakes up the main thread if it's sleeping inside ::GetMessage() | |
bb24c68f | 798 | extern void WXDLLIMPEXP_BASE wxWakeUpMainThread(); |
bf1852e1 | 799 | |
c096f614 | 800 | // return true if the main thread is waiting for some other to terminate: |
e7549107 | 801 | // wxApp then should block all "dangerous" messages |
bb24c68f | 802 | extern bool WXDLLIMPEXP_BASE wxIsWaitingForThread(); |
420b39aa | 803 | #endif // MSW, OS/2 |
dcda1c71 | 804 | |
f6ddc54a VZ |
805 | #endif // wxUSE_THREADS |
806 | ||
9e84b847 | 807 | #endif // _WX_THREAD_H_ |