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__) && !defined(__WXMAC__)
 154     #define WXCRITICAL_INLINE   inline
 155
 156     #define wxCRITSECT_IS_MUTEX 1
 157 #else // MSW || Mac || 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     // constructor only creates the C++ thread object and doesn't create (or
 284     // start) the real thread
 285     wxThread(wxThreadKind kind = wxTHREAD_DETACHED);
 286
 287     // functions that change the thread state: all these can only be called
 288     // from _another_ thread (typically the thread that created this one, e.g.
 289     // the main thread), not from the thread itself
 290
 291         // create a new thread - call Run() to start it
 292     wxThreadError Create();
 293
 294         // starts execution of the thread - from the moment Run() is called
 295         // the execution of wxThread::Entry() may start at any moment, caller
 296         // shouldn't suppose that it starts after (or before) Run() returns.
 297     wxThreadError Run();
 298
 299         // stops the thread if it's running and deletes the wxThread object if
 300         // this is a detached thread freeing its memory - otherwise (for
 301         // joinable threads) you still need to delete wxThread object
 302         // yourself.
 303         //
 304         // this function only works if the thread calls TestDestroy()
 305         // periodically - the thread will only be deleted the next time it
 306         // does it!
 307         //
 308         // will fill the rc pointer with the thread exit code if it's !NULL
 309     wxThreadError Delete(ExitCode *rc = (ExitCode *)NULL);
 310
 311         // waits for a joinable thread to finish and returns its exit code
 312         //
 313         // Returns (ExitCode)-1 on error (for example, if the thread is not
 314         // joinable)
 315     ExitCode Wait();
 316
 317         // kills the thread without giving it any chance to clean up - should
 318         // not be used in normal circumstances, use Delete() instead. It is a
 319         // dangerous function that should only be used in the most extreme
 320         // cases!
 321         //
 322         // The wxThread object is deleted by Kill() if the thread is
 323         // detachable, but you still have to delete it manually for joinable
 324         // threads.
 325     wxThreadError Kill();
 326
 327         // pause a running thread: as Delete(), this only works if the thread
 328         // calls TestDestroy() regularly
 329     wxThreadError Pause();
 330
 331         // resume a paused thread
 332     wxThreadError Resume();
 333
 334     // priority
 335         // Sets the priority to "prio": see WXTHREAD_XXX_PRIORITY constants
 336         //
 337         // NB: the priority can only be set before the thread is created
 338     void SetPriority(unsigned int prio);
 339
 340         // Get the current priority.
 341     unsigned int GetPriority() const;
 342
 343     // thread status inquiries
 344         // Returns true if the thread is alive: i.e. running or suspended
 345     bool IsAlive() const;
 346         // Returns true if the thread is running (not paused, not killed).
 347     bool IsRunning() const;
 348         // Returns true if the thread is suspended
 349     bool IsPaused() const;
 350
 351         // is the thread of detached kind?
 352     bool IsDetached() const { return m_isDetached; }
 353
 354     // Get the thread ID - a platform dependent number which uniquely
 355     // identifies a thread inside a process
 356     unsigned long GetId() const;
 357
 358     // called when the thread exits - in the context of this thread
 359     //
 360     // NB: this function will not be called if the thread is Kill()ed
 361     virtual void OnExit() { }
 362
 363     // dtor is public, but the detached threads should never be deleted - use
 364     // Delete() instead (or leave the thread terminate by itself)
 365     virtual ~wxThread();
 366
 367 protected:
 368     // Returns TRUE if the thread was asked to terminate: this function should
 369     // be called by the thread from time to time, otherwise the main thread
 370     // will be left forever in Delete()!
 371     bool TestDestroy();
 372
 373     // exits from the current thread - can be called only from this thread
 374     void Exit(ExitCode exitcode = 0);
 375
 376     // entry point for the thread - called by Run() and executes in the context
 377     // of this thread.
 378     virtual void *Entry() = 0;
 379
 380 private:
 381     // no copy ctor/assignment operator
 382     wxThread(const wxThread&);
 383     wxThread& operator=(const wxThread&);
 384
 385     friend class wxThreadInternal;
 386
 387     // the (platform-dependent) thread class implementation
 388     wxThreadInternal *m_internal;
 389
 390     // protects access to any methods of wxThreadInternal object
 391     wxCriticalSection m_critsect;
 392
 393     // true if the thread is detached, false if it is joinable
 394     bool m_isDetached;
 395 };
 396
 397 // ----------------------------------------------------------------------------
 398 // Automatic initialization
 399 // ----------------------------------------------------------------------------
 400
 401 // GUI mutex handling.
 402 void WXDLLEXPORT wxMutexGuiEnter();
 403 void WXDLLEXPORT wxMutexGuiLeave();
 404
 405 // macros for entering/leaving critical sections which may be used without
 406 // having to take them inside "#if wxUSE_THREADS"
 407 #define wxENTER_CRIT_SECT(cs)   (cs).Enter()
 408 #define wxLEAVE_CRIT_SECT(cs)   (cs).Leave()
 409 #define wxCRIT_SECT_DECLARE(cs) static wxCriticalSection cs
 410 #define wxCRIT_SECT_LOCKER(name, cs)  wxCriticalSectionLocker name(cs)
 411
 412 #else // !wxUSE_THREADS
 413
 414 #include "wx/defs.h" // for WXDLLEXPORT
 415
 416 // no thread support
 417 inline void WXDLLEXPORT wxMutexGuiEnter() { }
 418 inline void WXDLLEXPORT wxMutexGuiLeave() { }
 419
 420 // macros for entering/leaving critical sections which may be used without
 421 // having to take them inside "#if wxUSE_THREADS"
 422 #define wxENTER_CRIT_SECT(cs)
 423 #define wxLEAVE_CRIT_SECT(cs)
 424 #define wxCRIT_SECT_DECLARE(cs)
 425 #define wxCRIT_SECT_LOCKER(name, cs)
 426
 427 #endif // wxUSE_THREADS
 428
 429 // automatically unlock GUI mutex in dtor
 430 class WXDLLEXPORT wxMutexGuiLocker
 431 {
 432 public:
 433     wxMutexGuiLocker() { wxMutexGuiEnter(); }
 434    ~wxMutexGuiLocker() { wxMutexGuiLeave(); }
 435 };
 436
 437 // -----------------------------------------------------------------------------
 438 // implementation only until the end of file
 439 // -----------------------------------------------------------------------------
 440
 441 #if wxUSE_THREADS
 442
 443 #if defined(__WXMSW__)
 444     // unlock GUI if there are threads waiting for and lock it back when
 445     // there are no more of them - should be called periodically by the main
 446     // thread
 447     extern void WXDLLEXPORT wxMutexGuiLeaveOrEnter();
 448
 449     // returns TRUE if the main thread has GUI lock
 450     extern bool WXDLLEXPORT wxGuiOwnedByMainThread();
 451
 452     // wakes up the main thread if it's sleeping inside ::GetMessage()
 453     extern void WXDLLEXPORT wxWakeUpMainThread();
 454
 455     // return TRUE if the main thread is waiting for some other to terminate:
 456     // wxApp then should block all "dangerous" messages
 457     extern bool WXDLLEXPORT wxIsWaitingForThread();
 458 #elif defined(__WXMAC__)
 459     extern void WXDLLEXPORT wxMutexGuiLeaveOrEnter();
 460
 461     // returns TRUE if the main thread has GUI lock
 462     extern bool WXDLLEXPORT wxGuiOwnedByMainThread();
 463
 464     // wakes up the main thread if it's sleeping inside ::GetMessage()
 465     extern void WXDLLEXPORT wxWakeUpMainThread();
 466
 467     // return TRUE if the main thread is waiting for some other to terminate:
 468     // wxApp then should block all "dangerous" messages
 469     extern bool WXDLLEXPORT wxIsWaitingForThread();
 470 #elif defined(__WXPM__)
 471     // unlock GUI if there are threads waiting for and lock it back when
 472     // there are no more of them - should be called periodically by the main
 473     // thread
 474     extern void WXDLLEXPORT wxMutexGuiLeaveOrEnter();
 475
 476     // returns TRUE if the main thread has GUI lock
 477     extern bool WXDLLEXPORT wxGuiOwnedByMainThread();
 478
 479     // return TRUE if the main thread is waiting for some other to terminate:
 480     // wxApp then should block all "dangerous" messages
 481     extern bool WXDLLEXPORT wxIsWaitingForThread();
 482
 483 #else // !MSW && !PM
 484     // implement wxCriticalSection using mutexes
 485     inline wxCriticalSection::wxCriticalSection() { }
 486     inline wxCriticalSection::~wxCriticalSection() { }
 487
 488     inline void wxCriticalSection::Enter() { (void)m_mutex.Lock(); }
 489     inline void wxCriticalSection::Leave() { (void)m_mutex.Unlock(); }
 490 #endif // MSW/!MSW
 491
 492     // we can define these inline functions now (they should be defined after
 493     // wxCriticalSection::Enter/Leave)
 494     inline
 495     wxCriticalSectionLocker:: wxCriticalSectionLocker(wxCriticalSection& cs)
 496         : m_critsect(cs) { m_critsect.Enter(); }
 497     inline
 498     wxCriticalSectionLocker::~wxCriticalSectionLocker() { m_critsect.Leave(); }
 499 #endif // wxUSE_THREADS
 500
 501 #endif // __THREADH__