| 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 | /* otherwise we get undefined references for non-thread case (KB)*/ |
| 25 | #ifdef __GNUG__ |
| 26 | #pragma interface "thread.h" |
| 27 | #endif |
| 28 | |
| 29 | // Windows headers define it |
| 30 | #ifdef Yield |
| 31 | #undef Yield |
| 32 | #endif |
| 33 | |
| 34 | #include "wx/module.h" |
| 35 | |
| 36 | // ---------------------------------------------------------------------------- |
| 37 | // constants |
| 38 | // ---------------------------------------------------------------------------- |
| 39 | |
| 40 | typedef enum |
| 41 | { |
| 42 | wxMUTEX_NO_ERROR = 0, |
| 43 | wxMUTEX_DEAD_LOCK, // Mutex has been already locked by THE CALLING thread |
| 44 | wxMUTEX_BUSY, // Mutex has been already locked by ONE thread |
| 45 | wxMUTEX_UNLOCKED, |
| 46 | wxMUTEX_MISC_ERROR |
| 47 | } wxMutexError; |
| 48 | |
| 49 | typedef enum |
| 50 | { |
| 51 | wxTHREAD_NO_ERROR = 0, // No error |
| 52 | wxTHREAD_NO_RESOURCE, // No resource left to create a new thread |
| 53 | wxTHREAD_RUNNING, // The thread is already running |
| 54 | wxTHREAD_NOT_RUNNING, // The thread isn't running |
| 55 | wxTHREAD_MISC_ERROR // Some other error |
| 56 | } wxThreadError; |
| 57 | |
| 58 | // defines the interval of priority |
| 59 | #define WXTHREAD_MIN_PRIORITY 0u |
| 60 | #define WXTHREAD_DEFAULT_PRIORITY 50u |
| 61 | #define WXTHREAD_MAX_PRIORITY 100u |
| 62 | |
| 63 | // ---------------------------------------------------------------------------- |
| 64 | // A mutex object is a synchronization object whose state is set to signaled |
| 65 | // when it is not owned by any thread, and nonsignaled when it is owned. Its |
| 66 | // name comes from its usefulness in coordinating mutually-exclusive access to |
| 67 | // a shared resource. Only one thread at a time can own a mutex object. |
| 68 | // ---------------------------------------------------------------------------- |
| 69 | |
| 70 | // you should consider wxMutexLocker whenever possible instead of directly |
| 71 | // working with wxMutex class - it is safer |
| 72 | class WXDLLEXPORT wxMutexInternal; |
| 73 | class WXDLLEXPORT wxMutex |
| 74 | { |
| 75 | public: |
| 76 | // constructor & destructor |
| 77 | wxMutex(); |
| 78 | ~wxMutex(); |
| 79 | |
| 80 | // Lock the mutex. |
| 81 | wxMutexError Lock(); |
| 82 | // Try to lock the mutex: if it can't, returns immediately with an error. |
| 83 | wxMutexError TryLock(); |
| 84 | // Unlock the mutex. |
| 85 | wxMutexError Unlock(); |
| 86 | |
| 87 | // Returns true if the mutex is locked. |
| 88 | bool IsLocked() const { return (m_locked > 0); } |
| 89 | |
| 90 | protected: |
| 91 | friend class wxCondition; |
| 92 | |
| 93 | // no assignment operator nor copy ctor |
| 94 | wxMutex(const wxMutex&); |
| 95 | wxMutex& operator=(const wxMutex&); |
| 96 | |
| 97 | int m_locked; |
| 98 | wxMutexInternal *p_internal; |
| 99 | }; |
| 100 | |
| 101 | // a helper class which locks the mutex in the ctor and unlocks it in the dtor: |
| 102 | // this ensures that mutex is always unlocked, even if the function returns or |
| 103 | // throws an exception before it reaches the end |
| 104 | class WXDLLEXPORT wxMutexLocker |
| 105 | { |
| 106 | public: |
| 107 | // lock the mutex in the ctor |
| 108 | wxMutexLocker(wxMutex& mutex) : m_mutex(mutex) |
| 109 | { m_isOk = m_mutex.Lock() == wxMUTEX_NO_ERROR; } |
| 110 | |
| 111 | // returns TRUE if mutex was successfully locked in ctor |
| 112 | bool IsOk() const |
| 113 | { return m_isOk; } |
| 114 | |
| 115 | // unlock the mutex in dtor |
| 116 | ~wxMutexLocker() |
| 117 | { if ( IsOk() ) m_mutex.Unlock(); } |
| 118 | |
| 119 | private: |
| 120 | // no assignment operator nor copy ctor |
| 121 | wxMutexLocker(const wxMutexLocker&); |
| 122 | wxMutexLocker& operator=(const wxMutexLocker&); |
| 123 | |
| 124 | bool m_isOk; |
| 125 | wxMutex& m_mutex; |
| 126 | }; |
| 127 | |
| 128 | // ---------------------------------------------------------------------------- |
| 129 | // Critical section: this is the same as mutex but is only visible to the |
| 130 | // threads of the same process. For the platforms which don't have native |
| 131 | // support for critical sections, they're implemented entirely in terms of |
| 132 | // mutexes |
| 133 | // ---------------------------------------------------------------------------- |
| 134 | |
| 135 | // in order to avoid any overhead under !MSW make all wxCriticalSection class |
| 136 | // functions inline - but this can't be done under MSW |
| 137 | #if defined(__WXMSW__) || defined(__WXPM__) |
| 138 | class WXDLLEXPORT wxCriticalSectionInternal; |
| 139 | #define WXCRITICAL_INLINE |
| 140 | #elif defined(__WXMAC__) |
| 141 | class WXDLLEXPORT wxCriticalSectionInternal; |
| 142 | #define WXCRITICAL_INLINE |
| 143 | #else // !MSW && !PM |
| 144 | #define WXCRITICAL_INLINE inline |
| 145 | #endif // MSW/!MSW |
| 146 | |
| 147 | // you should consider wxCriticalSectionLocker whenever possible instead of |
| 148 | // directly working with wxCriticalSection class - it is safer |
| 149 | class WXDLLEXPORT wxCriticalSection |
| 150 | { |
| 151 | public: |
| 152 | // ctor & dtor |
| 153 | WXCRITICAL_INLINE wxCriticalSection(); |
| 154 | WXCRITICAL_INLINE ~wxCriticalSection(); |
| 155 | |
| 156 | // enter the section (the same as locking a mutex) |
| 157 | WXCRITICAL_INLINE void Enter(); |
| 158 | // leave the critical section (same as unlocking a mutex) |
| 159 | WXCRITICAL_INLINE void Leave(); |
| 160 | |
| 161 | private: |
| 162 | // no assignment operator nor copy ctor |
| 163 | wxCriticalSection(const wxCriticalSection&); |
| 164 | wxCriticalSection& operator=(const wxCriticalSection&); |
| 165 | |
| 166 | #if defined(__WXMSW__) || defined(__WXPM__) || defined(__WXMAC__) |
| 167 | wxCriticalSectionInternal *m_critsect; |
| 168 | #else // !MSW |
| 169 | wxMutex m_mutex; |
| 170 | #endif // MSW/!MSW |
| 171 | }; |
| 172 | |
| 173 | // keep your preprocessor name space clean |
| 174 | #undef WXCRITICAL_INLINE |
| 175 | |
| 176 | // wxCriticalSectionLocker is the same to critical sections as wxMutexLocker is |
| 177 | // to th mutexes |
| 178 | class WXDLLEXPORT wxCriticalSectionLocker |
| 179 | { |
| 180 | public: |
| 181 | inline wxCriticalSectionLocker(wxCriticalSection& critsect); |
| 182 | inline ~wxCriticalSectionLocker(); |
| 183 | |
| 184 | private: |
| 185 | // no assignment operator nor copy ctor |
| 186 | wxCriticalSectionLocker(const wxCriticalSectionLocker&); |
| 187 | wxCriticalSectionLocker& operator=(const wxCriticalSectionLocker&); |
| 188 | |
| 189 | wxCriticalSection& m_critsect; |
| 190 | }; |
| 191 | |
| 192 | // ---------------------------------------------------------------------------- |
| 193 | // Condition handler. |
| 194 | // ---------------------------------------------------------------------------- |
| 195 | |
| 196 | class wxConditionInternal; |
| 197 | class WXDLLEXPORT wxCondition |
| 198 | { |
| 199 | public: |
| 200 | // constructor & destructor |
| 201 | wxCondition(); |
| 202 | ~wxCondition(); |
| 203 | |
| 204 | // Waits indefinitely. |
| 205 | void Wait(wxMutex& mutex); |
| 206 | // Waits until a signal is raised or the timeout is elapsed. |
| 207 | bool Wait(wxMutex& mutex, unsigned long sec, unsigned long nsec); |
| 208 | // Raises a signal: only one "Waiter" is released. |
| 209 | void Signal(); |
| 210 | // Broadcasts to all "Waiters". |
| 211 | void Broadcast(); |
| 212 | |
| 213 | private: |
| 214 | wxConditionInternal *p_internal; |
| 215 | }; |
| 216 | |
| 217 | // ---------------------------------------------------------------------------- |
| 218 | // Thread management class |
| 219 | // ---------------------------------------------------------------------------- |
| 220 | |
| 221 | // FIXME Thread termination model is still unclear. Delete() should probably |
| 222 | // have a timeout after which the thread must be Kill()ed. |
| 223 | |
| 224 | // NB: in the function descriptions the words "this thread" mean the thread |
| 225 | // created by the wxThread object while "main thread" is the thread created |
| 226 | // during the process initialization (a.k.a. the GUI thread) |
| 227 | class wxThreadInternal; |
| 228 | class WXDLLEXPORT wxThread |
| 229 | { |
| 230 | public: |
| 231 | // the return type for the thread function |
| 232 | typedef void *ExitCode; |
| 233 | |
| 234 | // static functions |
| 235 | // Returns the wxThread object for the calling thread. NULL is returned |
| 236 | // if the caller is the main thread (but it's recommended to use |
| 237 | // IsMain() and only call This() for threads other than the main one |
| 238 | // because NULL is also returned on error). If the thread wasn't |
| 239 | // created with wxThread class, the returned value is undefined. |
| 240 | static wxThread *This(); |
| 241 | |
| 242 | // Returns true if current thread is the main thread. |
| 243 | static bool IsMain(); |
| 244 | |
| 245 | // Release the rest of our time slice leting the other threads run |
| 246 | static void Yield(); |
| 247 | |
| 248 | // Sleep during the specified period of time in milliseconds |
| 249 | // |
| 250 | // NB: at least under MSW worker threads can not call ::wxSleep()! |
| 251 | static void Sleep(unsigned long milliseconds); |
| 252 | |
| 253 | // default constructor |
| 254 | wxThread(); |
| 255 | |
| 256 | // function that change the thread state |
| 257 | // create a new thread - call Run() to start it |
| 258 | wxThreadError Create(); |
| 259 | |
| 260 | // starts execution of the thread - from the moment Run() is called the |
| 261 | // execution of wxThread::Entry() may start at any moment, caller |
| 262 | // shouldn't suppose that it starts after (or before) Run() returns. |
| 263 | wxThreadError Run(); |
| 264 | |
| 265 | // stops the thread if it's running and deletes the wxThread object |
| 266 | // freeing its memory. This function should also be called if the |
| 267 | // Create() or Run() fails to free memory (otherwise it will be done by |
| 268 | // the thread itself when it terminates). The return value is the |
| 269 | // thread exit code if the thread was gracefully terminated, 0 if it |
| 270 | // wasn't running and -1 if an error occured. |
| 271 | ExitCode Delete(); |
| 272 | |
| 273 | // kills the thread without giving it any chance to clean up - should |
| 274 | // not be used in normal circumstances, use Delete() instead. It is a |
| 275 | // dangerous function that should only be used in the most extreme |
| 276 | // cases! The wxThread object is deleted by Kill() if thread was |
| 277 | // killed (i.e. no errors occured). |
| 278 | wxThreadError Kill(); |
| 279 | |
| 280 | // pause a running thread |
| 281 | wxThreadError Pause(); |
| 282 | |
| 283 | // resume a paused thread |
| 284 | wxThreadError Resume(); |
| 285 | |
| 286 | // priority |
| 287 | // Sets the priority to "prio": see WXTHREAD_XXX_PRIORITY constants |
| 288 | // |
| 289 | // NB: the priority can only be set before the thread is created |
| 290 | void SetPriority(unsigned int prio); |
| 291 | |
| 292 | // Get the current priority. |
| 293 | unsigned int GetPriority() const; |
| 294 | |
| 295 | // Get the thread ID - a platform dependent number which uniquely |
| 296 | // identifies a thread inside a process |
| 297 | unsigned long GetID() const; |
| 298 | |
| 299 | // thread status inquiries |
| 300 | // Returns true if the thread is alive: i.e. running or suspended |
| 301 | bool IsAlive() const; |
| 302 | // Returns true if the thread is running (not paused, not killed). |
| 303 | bool IsRunning() const; |
| 304 | // Returns true if the thread is suspended |
| 305 | bool IsPaused() const; |
| 306 | |
| 307 | // called when the thread exits - in the context of this thread |
| 308 | // |
| 309 | // NB: this function will not be called if the thread is Kill()ed |
| 310 | virtual void OnExit() { } |
| 311 | |
| 312 | protected: |
| 313 | // Returns TRUE if the thread was asked to terminate: this function should |
| 314 | // be called by the thread from time to time, otherwise the main thread |
| 315 | // will be left forever in Delete()! |
| 316 | bool TestDestroy(); |
| 317 | |
| 318 | // exits from the current thread - can be called only from this thread |
| 319 | void Exit(void *exitcode = 0); |
| 320 | |
| 321 | // destructor is private - user code can't delete thread objects, they will |
| 322 | // auto-delete themselves (and thus must be always allocated on the heap). |
| 323 | // Use Delete() or Kill() instead. |
| 324 | // |
| 325 | // NB: derived classes dtors shouldn't be public neither! |
| 326 | virtual ~wxThread(); |
| 327 | |
| 328 | // entry point for the thread - called by Run() and executes in the context |
| 329 | // of this thread. |
| 330 | virtual void *Entry() = 0; |
| 331 | |
| 332 | private: |
| 333 | // no copy ctor/assignment operator |
| 334 | wxThread(const wxThread&); |
| 335 | wxThread& operator=(const wxThread&); |
| 336 | |
| 337 | friend class wxThreadInternal; |
| 338 | |
| 339 | // the (platform-dependent) thread class implementation |
| 340 | wxThreadInternal *p_internal; |
| 341 | |
| 342 | // protects access to any methods of wxThreadInternal object |
| 343 | wxCriticalSection m_critsect; |
| 344 | }; |
| 345 | |
| 346 | // ---------------------------------------------------------------------------- |
| 347 | // Automatic initialization |
| 348 | // ---------------------------------------------------------------------------- |
| 349 | |
| 350 | // GUI mutex handling. |
| 351 | void WXDLLEXPORT wxMutexGuiEnter(); |
| 352 | void WXDLLEXPORT wxMutexGuiLeave(); |
| 353 | |
| 354 | // macros for entering/leaving critical sections which may be used without |
| 355 | // having to take them inside "#if wxUSE_THREADS" |
| 356 | #define wxENTER_CRIT_SECT(cs) (cs)->Enter() |
| 357 | #define wxLEAVE_CRIT_SECT(cs) (cs)->Leave() |
| 358 | #define wxCRIT_SECT_LOCKER(name, cs) wxCriticalSectionLocker name(*cs) |
| 359 | |
| 360 | #else // !wxUSE_THREADS |
| 361 | |
| 362 | #include "wx/defs.h" // for WXDLLEXPORT |
| 363 | |
| 364 | // no thread support |
| 365 | inline void WXDLLEXPORT wxMutexGuiEnter() { } |
| 366 | inline void WXDLLEXPORT wxMutexGuiLeave() { } |
| 367 | |
| 368 | // macros for entering/leaving critical sections which may be used without |
| 369 | // having to take them inside "#if wxUSE_THREADS" |
| 370 | #define wxENTER_CRIT_SECT(cs) |
| 371 | #define wxLEAVE_CRIT_SECT(cs) |
| 372 | #define wxCRIT_SECT_LOCKER(name, cs) |
| 373 | |
| 374 | #endif // wxUSE_THREADS |
| 375 | |
| 376 | // automatically unlock GUI mutex in dtor |
| 377 | class WXDLLEXPORT wxMutexGuiLocker |
| 378 | { |
| 379 | public: |
| 380 | wxMutexGuiLocker() { wxMutexGuiEnter(); } |
| 381 | ~wxMutexGuiLocker() { wxMutexGuiLeave(); } |
| 382 | }; |
| 383 | |
| 384 | // ----------------------------------------------------------------------------- |
| 385 | // implementation only until the end of file |
| 386 | // ----------------------------------------------------------------------------- |
| 387 | |
| 388 | #if wxUSE_THREADS |
| 389 | |
| 390 | #if defined(__WXMSW__) |
| 391 | // unlock GUI if there are threads waiting for and lock it back when |
| 392 | // there are no more of them - should be called periodically by the main |
| 393 | // thread |
| 394 | extern void WXDLLEXPORT wxMutexGuiLeaveOrEnter(); |
| 395 | |
| 396 | // returns TRUE if the main thread has GUI lock |
| 397 | extern bool WXDLLEXPORT wxGuiOwnedByMainThread(); |
| 398 | |
| 399 | // wakes up the main thread if it's sleeping inside ::GetMessage() |
| 400 | extern void WXDLLEXPORT wxWakeUpMainThread(); |
| 401 | |
| 402 | // return TRUE if the main thread is waiting for some other to terminate: |
| 403 | // wxApp then should block all "dangerous" messages |
| 404 | extern bool WXDLLEXPORT wxIsWaitingForThread(); |
| 405 | #elif defined(__WXMAC__) |
| 406 | extern void WXDLLEXPORT wxMutexGuiLeaveOrEnter(); |
| 407 | |
| 408 | // returns TRUE if the main thread has GUI lock |
| 409 | extern bool WXDLLEXPORT wxGuiOwnedByMainThread(); |
| 410 | |
| 411 | // wakes up the main thread if it's sleeping inside ::GetMessage() |
| 412 | extern void WXDLLEXPORT wxWakeUpMainThread(); |
| 413 | |
| 414 | // return TRUE if the main thread is waiting for some other to terminate: |
| 415 | // wxApp then should block all "dangerous" messages |
| 416 | extern bool WXDLLEXPORT wxIsWaitingForThread(); |
| 417 | #elif defined(__WXPM__) |
| 418 | // unlock GUI if there are threads waiting for and lock it back when |
| 419 | // there are no more of them - should be called periodically by the main |
| 420 | // thread |
| 421 | extern void WXDLLEXPORT wxMutexGuiLeaveOrEnter(); |
| 422 | |
| 423 | // returns TRUE if the main thread has GUI lock |
| 424 | extern bool WXDLLEXPORT wxGuiOwnedByMainThread(); |
| 425 | // return TRUE if the main thread is waiting for some other to terminate: |
| 426 | // wxApp then should block all "dangerous" messages |
| 427 | extern bool WXDLLEXPORT wxIsWaitingForThread(); |
| 428 | #else // !MSW && !PM |
| 429 | // implement wxCriticalSection using mutexes |
| 430 | inline wxCriticalSection::wxCriticalSection() { } |
| 431 | inline wxCriticalSection::~wxCriticalSection() { } |
| 432 | |
| 433 | inline void wxCriticalSection::Enter() { (void)m_mutex.Lock(); } |
| 434 | inline void wxCriticalSection::Leave() { (void)m_mutex.Unlock(); } |
| 435 | #endif // MSW/!MSW |
| 436 | |
| 437 | // we can define these inline functions now (they should be defined after |
| 438 | // wxCriticalSection::Enter/Leave) |
| 439 | inline |
| 440 | wxCriticalSectionLocker:: wxCriticalSectionLocker(wxCriticalSection& cs) |
| 441 | : m_critsect(cs) { m_critsect.Enter(); } |
| 442 | inline |
| 443 | wxCriticalSectionLocker::~wxCriticalSectionLocker() { m_critsect.Leave(); } |
| 444 | #endif // wxUSE_THREADS |
| 445 | |
| 446 | #endif // __THREADH__ |