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