| 1 | ///////////////////////////////////////////////////////////////////////////// |
| 2 | // Name: thread.h |
| 3 | // Purpose: Thread API |
| 4 | // Author: Guilhem Lavaux |
| 5 | // Modified by: Vadim Zeitlin (modifications partly inspired by omnithreads |
| 6 | // package from Olivetti & Oracle Research Laboratory) |
| 7 | // Created: 04/13/98 |
| 8 | // RCS-ID: $Id$ |
| 9 | // Copyright: (c) Guilhem Lavaux |
| 10 | // Licence: wxWindows licence |
| 11 | ///////////////////////////////////////////////////////////////////////////// |
| 12 | |
| 13 | #ifndef __THREADH__ |
| 14 | #define __THREADH__ |
| 15 | |
| 16 | // ---------------------------------------------------------------------------- |
| 17 | // headers |
| 18 | // ---------------------------------------------------------------------------- |
| 19 | |
| 20 | // get the value of wxUSE_THREADS configuration flag |
| 21 | #include "wx/setup.h" |
| 22 | |
| 23 | #if wxUSE_THREADS |
| 24 | |
| 25 | // only for wxUSE_THREADS - otherwise we'd get undefined symbols |
| 26 | #ifdef __GNUG__ |
| 27 | #pragma interface "thread.h" |
| 28 | #endif |
| 29 | |
| 30 | // Windows headers define it |
| 31 | #ifdef Yield |
| 32 | #undef Yield |
| 33 | #endif |
| 34 | |
| 35 | #include "wx/module.h" |
| 36 | |
| 37 | // ---------------------------------------------------------------------------- |
| 38 | // constants |
| 39 | // ---------------------------------------------------------------------------- |
| 40 | |
| 41 | enum wxMutexError |
| 42 | { |
| 43 | wxMUTEX_NO_ERROR = 0, |
| 44 | wxMUTEX_DEAD_LOCK, // Mutex has been already locked by THE CALLING thread |
| 45 | wxMUTEX_BUSY, // Mutex has been already locked by ONE thread |
| 46 | wxMUTEX_UNLOCKED, |
| 47 | wxMUTEX_MISC_ERROR |
| 48 | }; |
| 49 | |
| 50 | enum wxThreadError |
| 51 | { |
| 52 | wxTHREAD_NO_ERROR = 0, // No error |
| 53 | wxTHREAD_NO_RESOURCE, // No resource left to create a new thread |
| 54 | wxTHREAD_RUNNING, // The thread is already running |
| 55 | wxTHREAD_NOT_RUNNING, // The thread isn't running |
| 56 | wxTHREAD_KILLED, // Thread we waited for had to be killed |
| 57 | wxTHREAD_MISC_ERROR // Some other error |
| 58 | }; |
| 59 | |
| 60 | enum wxThreadKind |
| 61 | { |
| 62 | wxTHREAD_DETACHED, |
| 63 | wxTHREAD_JOINABLE |
| 64 | }; |
| 65 | |
| 66 | // defines the interval of priority |
| 67 | enum |
| 68 | { |
| 69 | WXTHREAD_MIN_PRIORITY = 0u, |
| 70 | WXTHREAD_DEFAULT_PRIORITY = 50u, |
| 71 | WXTHREAD_MAX_PRIORITY = 100u |
| 72 | }; |
| 73 | |
| 74 | // ---------------------------------------------------------------------------- |
| 75 | // A mutex object is a synchronization object whose state is set to signaled |
| 76 | // when it is not owned by any thread, and nonsignaled when it is owned. Its |
| 77 | // name comes from its usefulness in coordinating mutually-exclusive access to |
| 78 | // a shared resource. Only one thread at a time can own a mutex object. |
| 79 | // ---------------------------------------------------------------------------- |
| 80 | |
| 81 | // you should consider wxMutexLocker whenever possible instead of directly |
| 82 | // working with wxMutex class - it is safer |
| 83 | class WXDLLEXPORT wxMutexInternal; |
| 84 | class WXDLLEXPORT wxMutex |
| 85 | { |
| 86 | public: |
| 87 | // constructor & destructor |
| 88 | wxMutex(); |
| 89 | ~wxMutex(); |
| 90 | |
| 91 | // Lock the mutex. |
| 92 | wxMutexError Lock(); |
| 93 | // Try to lock the mutex: if it can't, returns immediately with an error. |
| 94 | wxMutexError TryLock(); |
| 95 | // Unlock the mutex. |
| 96 | wxMutexError Unlock(); |
| 97 | |
| 98 | // Returns true if the mutex is locked. |
| 99 | bool IsLocked() const { return (m_locked > 0); } |
| 100 | |
| 101 | protected: |
| 102 | friend class wxCondition; |
| 103 | |
| 104 | // no assignment operator nor copy ctor |
| 105 | wxMutex(const wxMutex&); |
| 106 | wxMutex& operator=(const wxMutex&); |
| 107 | |
| 108 | int m_locked; |
| 109 | wxMutexInternal *m_internal; |
| 110 | }; |
| 111 | |
| 112 | // a helper class which locks the mutex in the ctor and unlocks it in the dtor: |
| 113 | // this ensures that mutex is always unlocked, even if the function returns or |
| 114 | // throws an exception before it reaches the end |
| 115 | class WXDLLEXPORT wxMutexLocker |
| 116 | { |
| 117 | public: |
| 118 | // lock the mutex in the ctor |
| 119 | wxMutexLocker(wxMutex& mutex) : m_mutex(mutex) |
| 120 | { m_isOk = m_mutex.Lock() == wxMUTEX_NO_ERROR; } |
| 121 | |
| 122 | // returns TRUE if mutex was successfully locked in ctor |
| 123 | bool IsOk() const |
| 124 | { return m_isOk; } |
| 125 | |
| 126 | // unlock the mutex in dtor |
| 127 | ~wxMutexLocker() |
| 128 | { if ( IsOk() ) m_mutex.Unlock(); } |
| 129 | |
| 130 | private: |
| 131 | // no assignment operator nor copy ctor |
| 132 | wxMutexLocker(const wxMutexLocker&); |
| 133 | wxMutexLocker& operator=(const wxMutexLocker&); |
| 134 | |
| 135 | bool m_isOk; |
| 136 | wxMutex& m_mutex; |
| 137 | }; |
| 138 | |
| 139 | // ---------------------------------------------------------------------------- |
| 140 | // Critical section: this is the same as mutex but is only visible to the |
| 141 | // threads of the same process. For the platforms which don't have native |
| 142 | // support for critical sections, they're implemented entirely in terms of |
| 143 | // mutexes. |
| 144 | // |
| 145 | // NB: wxCriticalSection object does not allocate any memory in its ctor |
| 146 | // which makes it possible to have static globals of this class |
| 147 | // ---------------------------------------------------------------------------- |
| 148 | |
| 149 | class WXDLLEXPORT wxCriticalSectionInternal; |
| 150 | |
| 151 | // in order to avoid any overhead under platforms where critical sections are |
| 152 | // just mutexes make all wxCriticalSection class functions inline |
| 153 | #if !defined(__WXMSW__) && !defined(__WXPM__) |
| 154 | #define WXCRITICAL_INLINE inline |
| 155 | |
| 156 | #define wxCRITSECT_IS_MUTEX 1 |
| 157 | #else // MSW || OS2 |
| 158 | #define WXCRITICAL_INLINE |
| 159 | |
| 160 | #define wxCRITSECT_IS_MUTEX 0 |
| 161 | #endif // MSW/!MSW |
| 162 | |
| 163 | // you should consider wxCriticalSectionLocker whenever possible instead of |
| 164 | // directly working with wxCriticalSection class - it is safer |
| 165 | class WXDLLEXPORT wxCriticalSection |
| 166 | { |
| 167 | public: |
| 168 | // ctor & dtor |
| 169 | WXCRITICAL_INLINE wxCriticalSection(); |
| 170 | WXCRITICAL_INLINE ~wxCriticalSection(); |
| 171 | |
| 172 | // enter the section (the same as locking a mutex) |
| 173 | WXCRITICAL_INLINE void Enter(); |
| 174 | // leave the critical section (same as unlocking a mutex) |
| 175 | WXCRITICAL_INLINE void Leave(); |
| 176 | |
| 177 | private: |
| 178 | // no assignment operator nor copy ctor |
| 179 | wxCriticalSection(const wxCriticalSection&); |
| 180 | wxCriticalSection& operator=(const wxCriticalSection&); |
| 181 | |
| 182 | #if wxCRITSECT_IS_MUTEX |
| 183 | wxMutex m_mutex; |
| 184 | #elif defined(__WXMSW__) |
| 185 | // we can't allocate any memory in the ctor, so use placement new - |
| 186 | // unfortunately, we have to hardcode the sizeof() here because we can't |
| 187 | // include windows.h from this public header |
| 188 | char m_buffer[24]; |
| 189 | #elif !defined(__WXPM__) |
| 190 | wxCriticalSectionInternal *m_critsect; |
| 191 | #else |
| 192 | // nothing for OS/2 |
| 193 | #endif // !Unix/Unix |
| 194 | }; |
| 195 | |
| 196 | // keep your preprocessor name space clean |
| 197 | #undef WXCRITICAL_INLINE |
| 198 | |
| 199 | // wxCriticalSectionLocker is the same to critical sections as wxMutexLocker is |
| 200 | // to th mutexes |
| 201 | class WXDLLEXPORT wxCriticalSectionLocker |
| 202 | { |
| 203 | public: |
| 204 | inline wxCriticalSectionLocker(wxCriticalSection& critsect); |
| 205 | inline ~wxCriticalSectionLocker(); |
| 206 | |
| 207 | private: |
| 208 | // no assignment operator nor copy ctor |
| 209 | wxCriticalSectionLocker(const wxCriticalSectionLocker&); |
| 210 | wxCriticalSectionLocker& operator=(const wxCriticalSectionLocker&); |
| 211 | |
| 212 | wxCriticalSection& m_critsect; |
| 213 | }; |
| 214 | |
| 215 | // ---------------------------------------------------------------------------- |
| 216 | // Condition variable: allows to block the thread execution until something |
| 217 | // happens (== condition is signaled) |
| 218 | // ---------------------------------------------------------------------------- |
| 219 | |
| 220 | class wxConditionInternal; |
| 221 | class WXDLLEXPORT wxCondition |
| 222 | { |
| 223 | public: |
| 224 | // constructor & destructor |
| 225 | wxCondition(); |
| 226 | ~wxCondition(); |
| 227 | |
| 228 | // wait until the condition is signaled |
| 229 | // waits indefinitely. |
| 230 | void Wait(); |
| 231 | // waits until a signal is raised or the timeout elapses |
| 232 | bool Wait(unsigned long sec, unsigned long nsec); |
| 233 | |
| 234 | // signal the condition |
| 235 | // wakes up one (and only one) of the waiting threads |
| 236 | void Signal(); |
| 237 | // wakes up all threads waiting onthis condition |
| 238 | void Broadcast(); |
| 239 | |
| 240 | private: |
| 241 | wxConditionInternal *m_internal; |
| 242 | }; |
| 243 | |
| 244 | // ---------------------------------------------------------------------------- |
| 245 | // Thread class |
| 246 | // ---------------------------------------------------------------------------- |
| 247 | |
| 248 | // there are two different kinds of threads: joinable and detached (default) |
| 249 | // ones. Only joinable threads can return a return code and only detached |
| 250 | // threads auto-delete themselves - the user should delete the joinable |
| 251 | // threads manually. |
| 252 | |
| 253 | // NB: in the function descriptions the words "this thread" mean the thread |
| 254 | // created by the wxThread object while "main thread" is the thread created |
| 255 | // during the process initialization (a.k.a. the GUI thread) |
| 256 | |
| 257 | class wxThreadInternal; |
| 258 | class WXDLLEXPORT wxThread |
| 259 | { |
| 260 | public: |
| 261 | // the return type for the thread function |
| 262 | typedef void *ExitCode; |
| 263 | |
| 264 | // static functions |
| 265 | // Returns the wxThread object for the calling thread. NULL is returned |
| 266 | // if the caller is the main thread (but it's recommended to use |
| 267 | // IsMain() and only call This() for threads other than the main one |
| 268 | // because NULL is also returned on error). If the thread wasn't |
| 269 | // created with wxThread class, the returned value is undefined. |
| 270 | static wxThread *This(); |
| 271 | |
| 272 | // Returns true if current thread is the main thread. |
| 273 | static bool IsMain(); |
| 274 | |
| 275 | // Release the rest of our time slice leting the other threads run |
| 276 | static void Yield(); |
| 277 | |
| 278 | // Sleep during the specified period of time in milliseconds |
| 279 | // |
| 280 | // NB: at least under MSW worker threads can not call ::wxSleep()! |
| 281 | static void Sleep(unsigned long milliseconds); |
| 282 | |
| 283 | // get the number of system CPUs - useful with SetConcurrency() |
| 284 | // (the "best" value for it is usually number of CPUs + 1) |
| 285 | // |
| 286 | // Returns -1 if unknown, number of CPUs otherwise |
| 287 | static int GetCPUCount(); |
| 288 | |
| 289 | // sets the concurrency level: this is, roughly, the number of threads |
| 290 | // the system tries to schedule to run in parallel. 0 means the |
| 291 | // default value (usually acceptable, but may not yield the best |
| 292 | // performance for this process) |
| 293 | // |
| 294 | // Returns TRUE on success, FALSE otherwise (if not implemented, for |
| 295 | // example) |
| 296 | static bool SetConcurrency(size_t level); |
| 297 | |
| 298 | // constructor only creates the C++ thread object and doesn't create (or |
| 299 | // start) the real thread |
| 300 | wxThread(wxThreadKind kind = wxTHREAD_DETACHED); |
| 301 | |
| 302 | // functions that change the thread state: all these can only be called |
| 303 | // from _another_ thread (typically the thread that created this one, e.g. |
| 304 | // the main thread), not from the thread itself |
| 305 | |
| 306 | // create a new thread - call Run() to start it |
| 307 | wxThreadError Create(); |
| 308 | |
| 309 | // starts execution of the thread - from the moment Run() is called |
| 310 | // the execution of wxThread::Entry() may start at any moment, caller |
| 311 | // shouldn't suppose that it starts after (or before) Run() returns. |
| 312 | wxThreadError Run(); |
| 313 | |
| 314 | // stops the thread if it's running and deletes the wxThread object if |
| 315 | // this is a detached thread freeing its memory - otherwise (for |
| 316 | // joinable threads) you still need to delete wxThread object |
| 317 | // yourself. |
| 318 | // |
| 319 | // this function only works if the thread calls TestDestroy() |
| 320 | // periodically - the thread will only be deleted the next time it |
| 321 | // does it! |
| 322 | // |
| 323 | // will fill the rc pointer with the thread exit code if it's !NULL |
| 324 | wxThreadError Delete(ExitCode *rc = (ExitCode *)NULL); |
| 325 | |
| 326 | // waits for a joinable thread to finish and returns its exit code |
| 327 | // |
| 328 | // Returns (ExitCode)-1 on error (for example, if the thread is not |
| 329 | // joinable) |
| 330 | ExitCode Wait(); |
| 331 | |
| 332 | // kills the thread without giving it any chance to clean up - should |
| 333 | // not be used in normal circumstances, use Delete() instead. It is a |
| 334 | // dangerous function that should only be used in the most extreme |
| 335 | // cases! |
| 336 | // |
| 337 | // The wxThread object is deleted by Kill() if the thread is |
| 338 | // detachable, but you still have to delete it manually for joinable |
| 339 | // threads. |
| 340 | wxThreadError Kill(); |
| 341 | |
| 342 | // pause a running thread: as Delete(), this only works if the thread |
| 343 | // calls TestDestroy() regularly |
| 344 | wxThreadError Pause(); |
| 345 | |
| 346 | // resume a paused thread |
| 347 | wxThreadError Resume(); |
| 348 | |
| 349 | // priority |
| 350 | // Sets the priority to "prio": see WXTHREAD_XXX_PRIORITY constants |
| 351 | // |
| 352 | // NB: the priority can only be set before the thread is created |
| 353 | void SetPriority(unsigned int prio); |
| 354 | |
| 355 | // Get the current priority. |
| 356 | unsigned int GetPriority() const; |
| 357 | |
| 358 | // thread status inquiries |
| 359 | // Returns true if the thread is alive: i.e. running or suspended |
| 360 | bool IsAlive() const; |
| 361 | // Returns true if the thread is running (not paused, not killed). |
| 362 | bool IsRunning() const; |
| 363 | // Returns true if the thread is suspended |
| 364 | bool IsPaused() const; |
| 365 | |
| 366 | // is the thread of detached kind? |
| 367 | bool IsDetached() const { return m_isDetached; } |
| 368 | |
| 369 | // Get the thread ID - a platform dependent number which uniquely |
| 370 | // identifies a thread inside a process |
| 371 | #ifdef __VMS |
| 372 | unsigned long long GetId() const; |
| 373 | #else |
| 374 | unsigned long GetId() const; |
| 375 | #endif |
| 376 | |
| 377 | // called when the thread exits - in the context of this thread |
| 378 | // |
| 379 | // NB: this function will not be called if the thread is Kill()ed |
| 380 | virtual void OnExit() { } |
| 381 | |
| 382 | // dtor is public, but the detached threads should never be deleted - use |
| 383 | // Delete() instead (or leave the thread terminate by itself) |
| 384 | virtual ~wxThread(); |
| 385 | |
| 386 | protected: |
| 387 | // Returns TRUE if the thread was asked to terminate: this function should |
| 388 | // be called by the thread from time to time, otherwise the main thread |
| 389 | // will be left forever in Delete()! |
| 390 | bool TestDestroy(); |
| 391 | |
| 392 | // exits from the current thread - can be called only from this thread |
| 393 | void Exit(ExitCode exitcode = 0); |
| 394 | |
| 395 | // entry point for the thread - called by Run() and executes in the context |
| 396 | // of this thread. |
| 397 | virtual void *Entry() = 0; |
| 398 | |
| 399 | private: |
| 400 | // no copy ctor/assignment operator |
| 401 | wxThread(const wxThread&); |
| 402 | wxThread& operator=(const wxThread&); |
| 403 | |
| 404 | friend class wxThreadInternal; |
| 405 | |
| 406 | // the (platform-dependent) thread class implementation |
| 407 | wxThreadInternal *m_internal; |
| 408 | |
| 409 | // protects access to any methods of wxThreadInternal object |
| 410 | wxCriticalSection m_critsect; |
| 411 | |
| 412 | // true if the thread is detached, false if it is joinable |
| 413 | bool m_isDetached; |
| 414 | }; |
| 415 | |
| 416 | // ---------------------------------------------------------------------------- |
| 417 | // Automatic initialization |
| 418 | // ---------------------------------------------------------------------------- |
| 419 | |
| 420 | // GUI mutex handling. |
| 421 | void WXDLLEXPORT wxMutexGuiEnter(); |
| 422 | void WXDLLEXPORT wxMutexGuiLeave(); |
| 423 | |
| 424 | // macros for entering/leaving critical sections which may be used without |
| 425 | // having to take them inside "#if wxUSE_THREADS" |
| 426 | #define wxENTER_CRIT_SECT(cs) (cs).Enter() |
| 427 | #define wxLEAVE_CRIT_SECT(cs) (cs).Leave() |
| 428 | #define wxCRIT_SECT_DECLARE(cs) static wxCriticalSection cs |
| 429 | #define wxCRIT_SECT_LOCKER(name, cs) wxCriticalSectionLocker name(cs) |
| 430 | |
| 431 | #else // !wxUSE_THREADS |
| 432 | |
| 433 | #include "wx/defs.h" // for WXDLLEXPORT |
| 434 | |
| 435 | // no thread support |
| 436 | inline void WXDLLEXPORT wxMutexGuiEnter() { } |
| 437 | inline void WXDLLEXPORT wxMutexGuiLeave() { } |
| 438 | |
| 439 | // macros for entering/leaving critical sections which may be used without |
| 440 | // having to take them inside "#if wxUSE_THREADS" |
| 441 | #define wxENTER_CRIT_SECT(cs) |
| 442 | #define wxLEAVE_CRIT_SECT(cs) |
| 443 | #define wxCRIT_SECT_DECLARE(cs) |
| 444 | #define wxCRIT_SECT_LOCKER(name, cs) |
| 445 | |
| 446 | #endif // wxUSE_THREADS |
| 447 | |
| 448 | // automatically unlock GUI mutex in dtor |
| 449 | class WXDLLEXPORT wxMutexGuiLocker |
| 450 | { |
| 451 | public: |
| 452 | wxMutexGuiLocker() { wxMutexGuiEnter(); } |
| 453 | ~wxMutexGuiLocker() { wxMutexGuiLeave(); } |
| 454 | }; |
| 455 | |
| 456 | // ----------------------------------------------------------------------------- |
| 457 | // implementation only until the end of file |
| 458 | // ----------------------------------------------------------------------------- |
| 459 | |
| 460 | #if wxUSE_THREADS |
| 461 | |
| 462 | #if defined(__WXMSW__) |
| 463 | // unlock GUI if there are threads waiting for and lock it back when |
| 464 | // there are no more of them - should be called periodically by the main |
| 465 | // thread |
| 466 | extern void WXDLLEXPORT wxMutexGuiLeaveOrEnter(); |
| 467 | |
| 468 | // returns TRUE if the main thread has GUI lock |
| 469 | extern bool WXDLLEXPORT wxGuiOwnedByMainThread(); |
| 470 | |
| 471 | // wakes up the main thread if it's sleeping inside ::GetMessage() |
| 472 | extern void WXDLLEXPORT wxWakeUpMainThread(); |
| 473 | |
| 474 | // return TRUE if the main thread is waiting for some other to terminate: |
| 475 | // wxApp then should block all "dangerous" messages |
| 476 | extern bool WXDLLEXPORT wxIsWaitingForThread(); |
| 477 | #elif defined(__WXMAC__) |
| 478 | extern void WXDLLEXPORT wxMutexGuiLeaveOrEnter(); |
| 479 | |
| 480 | // returns TRUE if the main thread has GUI lock |
| 481 | extern bool WXDLLEXPORT wxGuiOwnedByMainThread(); |
| 482 | |
| 483 | // wakes up the main thread if it's sleeping inside ::GetMessage() |
| 484 | extern void WXDLLEXPORT wxWakeUpMainThread(); |
| 485 | |
| 486 | // return TRUE if the main thread is waiting for some other to terminate: |
| 487 | // wxApp then should block all "dangerous" messages |
| 488 | extern bool WXDLLEXPORT wxIsWaitingForThread(); |
| 489 | |
| 490 | // implement wxCriticalSection using mutexes |
| 491 | inline wxCriticalSection::wxCriticalSection() { } |
| 492 | inline wxCriticalSection::~wxCriticalSection() { } |
| 493 | |
| 494 | inline void wxCriticalSection::Enter() { (void)m_mutex.Lock(); } |
| 495 | inline void wxCriticalSection::Leave() { (void)m_mutex.Unlock(); } |
| 496 | #elif defined(__WXPM__) |
| 497 | // unlock GUI if there are threads waiting for and lock it back when |
| 498 | // there are no more of them - should be called periodically by the main |
| 499 | // thread |
| 500 | extern void WXDLLEXPORT wxMutexGuiLeaveOrEnter(); |
| 501 | |
| 502 | // returns TRUE if the main thread has GUI lock |
| 503 | extern bool WXDLLEXPORT wxGuiOwnedByMainThread(); |
| 504 | |
| 505 | // return TRUE if the main thread is waiting for some other to terminate: |
| 506 | // wxApp then should block all "dangerous" messages |
| 507 | extern bool WXDLLEXPORT wxIsWaitingForThread(); |
| 508 | |
| 509 | #else // !MSW && !PM |
| 510 | // implement wxCriticalSection using mutexes |
| 511 | inline wxCriticalSection::wxCriticalSection() { } |
| 512 | inline wxCriticalSection::~wxCriticalSection() { } |
| 513 | |
| 514 | inline void wxCriticalSection::Enter() { (void)m_mutex.Lock(); } |
| 515 | inline void wxCriticalSection::Leave() { (void)m_mutex.Unlock(); } |
| 516 | #endif // MSW/!MSW |
| 517 | |
| 518 | // we can define these inline functions now (they should be defined after |
| 519 | // wxCriticalSection::Enter/Leave) |
| 520 | inline |
| 521 | wxCriticalSectionLocker:: wxCriticalSectionLocker(wxCriticalSection& cs) |
| 522 | : m_critsect(cs) { m_critsect.Enter(); } |
| 523 | inline |
| 524 | wxCriticalSectionLocker::~wxCriticalSectionLocker() { m_critsect.Leave(); } |
| 525 | #endif // wxUSE_THREADS |
| 526 | |
| 527 | #endif // __THREADH__ |