include/wx/thread.h

   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__