include/wx/thread.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        thread.h
   3 // Purpose:     Thread API
   4 // Author:      Guilhem Lavaux
   5 // Modified by:
   6 // Created:     04/13/98
   7 // RCS-ID:      $Id$
   8 // Copyright:   (c) Guilhem Lavaux
   9 // Licence:     wxWindows licence
  10 /////////////////////////////////////////////////////////////////////////////
  11
  12 #ifndef __THREADH__
  13 #define __THREADH__
  14
  15 #ifdef __GNUG__
  16 #pragma interface "thread.h"
  17 #endif
  18
  19 // ----------------------------------------------------------------------------
  20 // headers
  21 // ----------------------------------------------------------------------------
  22 #include "wx/setup.h"
  23
  24 #if wxUSE_THREADS
  25 #include "wx/module.h"
  26
  27 // ----------------------------------------------------------------------------
  28 // constants
  29 // ----------------------------------------------------------------------------
  30
  31 typedef enum
  32 {
  33   wxMUTEX_NO_ERROR = 0,
  34   wxMUTEX_DEAD_LOCK,      // Mutex has been already locked by THE CALLING thread
  35   wxMUTEX_BUSY,           // Mutex has been already locked by ONE thread
  36   wxMUTEX_UNLOCKED,
  37   wxMUTEX_MISC_ERROR
  38 } wxMutexError;
  39
  40 typedef enum
  41 {
  42   wxTHREAD_NO_ERROR = 0,      // No error
  43   wxTHREAD_NO_RESOURCE,       // No resource left to create a new thread
  44   wxTHREAD_RUNNING,           // The thread is already running
  45   wxTHREAD_NOT_RUNNING,       // The thread isn't running
  46   wxTHREAD_MISC_ERROR         // Some other error
  47 } wxThreadError;
  48
  49 /* defines the interval of priority. */
  50 #define WXTHREAD_MIN_PRIORITY     0
  51 #define WXTHREAD_DEFAULT_PRIORITY 50
  52 #define WXTHREAD_MAX_PRIORITY     100
  53
  54 // ----------------------------------------------------------------------------
  55 // A mutex object is a synchronization object whose state is set to signaled
  56 // when it is not owned by any thread, and nonsignaled when it is owned. Its
  57 // name comes from its usefulness in coordinating mutually-exclusive access to
  58 // a shared resource. Only one thread at a time can own a mutex object.
  59 // ----------------------------------------------------------------------------
  60
  61 // you should consider wxMutexLocker whenever possible instead of directly
  62 // working with wxMutex class - it is safer
  63 class WXDLLEXPORT wxMutexInternal;
  64 class WXDLLEXPORT wxMutex
  65 {
  66 public:
  67     // constructor & destructor
  68     wxMutex();
  69     ~wxMutex();
  70
  71     // Lock the mutex.
  72     wxMutexError Lock();
  73     // Try to lock the mutex: if it can't, returns immediately with an error.
  74     wxMutexError TryLock();
  75     // Unlock the mutex.
  76     wxMutexError Unlock();
  77
  78     // Returns true if the mutex is locked.
  79     bool IsLocked() const { return (m_locked > 0); }
  80
  81 protected:
  82     friend class wxCondition;
  83
  84     // no assignment operator nor copy ctor
  85     wxMutex(const wxMutex&);
  86     wxMutex& operator=(const wxMutex&);
  87
  88     int m_locked;
  89     wxMutexInternal *p_internal;
  90 };
  91
  92 // a helper class which locks the mutex in the ctor and unlocks it in the dtor:
  93 // this ensures that mutex is always unlocked, even if the function returns or
  94 // throws an exception before it reaches the end
  95 class WXDLLEXPORT wxMutexLocker
  96 {
  97 public:
  98     // lock the mutex in the ctor
  99     wxMutexLocker(wxMutex *mutex)
 100         { m_isOk = mutex && ((m_mutex = mutex)->Lock() == wxMUTEX_NO_ERROR); }
 101
 102     // returns TRUE if mutex was successfully locked in ctor
 103     bool IsOk() const { return m_isOk; }
 104
 105     // unlock the mutex in dtor
 106     ~wxMutexLocker() { if ( IsOk() ) m_mutex->Unlock(); }
 107
 108 private:
 109     // no assignment operator nor copy ctor
 110     wxMutexLocker(const wxMutexLocker&);
 111     wxMutexLocker& operator=(const wxMutexLocker&);
 112
 113     bool     m_isOk;
 114     wxMutex *m_mutex;
 115 };
 116
 117 // ----------------------------------------------------------------------------
 118 // Critical section: this is the same as mutex but is only visible to the
 119 // threads of the same process. For the platforms which don't have native
 120 // support for critical sections, they're implemented entirely in terms of
 121 // mutexes
 122 // ----------------------------------------------------------------------------
 123
 124 // you should consider wxCriticalSectionLocker whenever possible instead of
 125 // directly working with wxCriticalSection class - it is safer
 126 #ifdef __WXMSW__
 127     class WXDLLEXPORT wxCriticalSectionInternal;
 128     #define WXCRITICAL_INLINE
 129 #else // !MSW
 130     #define WXCRITICAL_INLINE   inline
 131 #endif // MSW/!MSW
 132 class WXDLLEXPORT wxCriticalSection
 133 {
 134 public:
 135     // ctor & dtor
 136     WXCRITICAL_INLINE wxCriticalSection();
 137     WXCRITICAL_INLINE ~wxCriticalSection();
 138
 139     // enter the section (the same as locking a mutex)
 140     void WXCRITICAL_INLINE Enter();
 141     // leave the critical section (same as unlocking a mutex)
 142     void WXCRITICAL_INLINE Leave();
 143
 144 private:
 145     // no assignment operator nor copy ctor
 146     wxCriticalSection(const wxCriticalSection&);
 147     wxCriticalSection& operator=(const wxCriticalSection&);
 148
 149 #ifdef __WXMSW__
 150     wxCriticalSectionInternal *m_critsect;
 151 #else // !MSW
 152     wxMutex m_mutex;
 153 #endif // MSW/!MSW
 154 };
 155
 156 // wxCriticalSectionLocker is the same to critical sections as wxMutexLocker is
 157 // to th mutexes
 158 class WXDLLEXPORT wxCriticalSectionLocker
 159 {
 160 public:
 161     wxCriticalSectionLocker(wxCriticalSection& critsect) : m_critsect(critsect)
 162         { m_critsect.Enter(); }
 163     ~wxCriticalSectionLocker()
 164         { m_critsect.Leave(); }
 165
 166 private:
 167     // no assignment operator nor copy ctor
 168     wxCriticalSectionLocker(const wxCriticalSectionLocker&);
 169     wxCriticalSectionLocker& operator=(const wxCriticalSectionLocker&);
 170
 171     wxCriticalSection& m_critsect;
 172 };
 173
 174 // ----------------------------------------------------------------------------
 175 // Condition handler.
 176 // ----------------------------------------------------------------------------
 177
 178 class wxConditionInternal;
 179 class WXDLLEXPORT wxCondition
 180 {
 181 public:
 182   // constructor & destructor
 183   wxCondition();
 184   ~wxCondition();
 185
 186   // Waits indefinitely.
 187   void Wait(wxMutex& mutex);
 188   // Waits until a signal is raised or the timeout is elapsed.
 189   bool Wait(wxMutex& mutex, unsigned long sec, unsigned long nsec);
 190   // Raises a signal: only one "Waiter" is released.
 191   void Signal();
 192   // Broadcasts to all "Waiters".
 193   void Broadcast();
 194
 195 private:
 196   wxConditionInternal *p_internal;
 197 };
 198
 199 // ----------------------------------------------------------------------------
 200 // Thread management class
 201 // ----------------------------------------------------------------------------
 202
 203 class wxThreadInternal;
 204 class WXDLLEXPORT wxThread
 205 {
 206 public:
 207   // constructor & destructor.
 208   wxThread();
 209   virtual ~wxThread();
 210
 211   // Create a new thread, this method should check there is only one thread
 212   // running by object.
 213   wxThreadError Create();
 214
 215   // Destroys the thread immediately if the defer flag isn't true.
 216   wxThreadError Destroy();
 217
 218   // Pause a running thread
 219   wxThreadError Pause();
 220
 221   // Resume a paused thread
 222   wxThreadError Resume();
 223
 224   // Switches on the defer flag.
 225   void DeferDestroy(bool on);
 226
 227   // Waits for the termination of the thread.
 228   void *Join();
 229
 230   // Sets the priority to "prio". (Warning: The priority can only be set before
 231   // the thread is created)
 232   void SetPriority(int prio);
 233   // Get the current priority.
 234   int GetPriority() const;
 235
 236   // Get the thread ID
 237   unsigned long GetID() const;
 238
 239   // Returns true if the thread is alive.
 240   bool IsAlive() const;
 241   // Returns true if the thread is running (not paused, not killed).
 242   bool IsRunning() const;
 243   // Returns true if the thread is suspended
 244   bool IsPaused() const { return IsAlive() && !IsRunning(); }
 245
 246   // Returns true if current thread is the main thread (aka the GUI thread)
 247   static bool IsMain();
 248
 249   // Called when thread exits.
 250   virtual void OnExit();
 251
 252 protected:
 253   // Returns TRUE if the thread was asked to terminate
 254   bool TestDestroy();
 255
 256   // Exits from the current thread.
 257   void Exit(void *status = NULL);
 258
 259 private:
 260   // Entry point for the thread.
 261   virtual void *Entry() = 0;
 262
 263 private:
 264   friend class wxThreadInternal;
 265
 266   wxThreadInternal *p_internal;
 267 };
 268
 269 // ----------------------------------------------------------------------------
 270 // Automatic initialization
 271 // ----------------------------------------------------------------------------
 272
 273 // GUI mutex handling.
 274 void WXDLLEXPORT wxMutexGuiEnter();
 275 void WXDLLEXPORT wxMutexGuiLeave();
 276
 277 #else // !wxUSE_THREADS
 278
 279 // no thread support
 280 inline void WXDLLEXPORT wxMutexGuiEnter() { }
 281 inline void WXDLLEXPORT wxMutexGuiLeave() { }
 282
 283 #endif // wxUSE_THREADS
 284
 285 // automatically unlock GUI mutex in dtor
 286 class WXDLLEXPORT wxMutexGuiLocker
 287 {
 288 public:
 289     wxMutexGuiLocker() { wxMutexGuiEnter(); }
 290    ~wxMutexGuiLocker() { wxMutexGuiLeave(); }
 291 };
 292
 293 // -----------------------------------------------------------------------------
 294 // implementation only until the end of file
 295 // -----------------------------------------------------------------------------
 296 #ifdef wxUSE_THREADS
 297 #ifdef __WXMSW__
 298     // unlock GUI if there are threads waiting for and lock it back when
 299     // there are no more of them - should be called periodically by the main
 300     // thread
 301     void WXDLLEXPORT wxMutexGuiLeaveOrEnter();
 302
 303     // returns TRUE if the main thread has GUI lock
 304     inline bool WXDLLEXPORT wxGuiOwnedByMainThread();
 305
 306     // wakes up the main thread if it's sleeping inside ::GetMessage()
 307     inline void WXDLLEXPORT wxWakeUpMainThread();
 308 #else // !MSW
 309     // implement wxCriticalSection using mutexes
 310     inline wxCriticalSection::wxCriticalSection() { }
 311     inline wxCriticalSection::~wxCriticalSection() { }
 312
 313     inline void wxCriticalSection::Enter() { (void)m_mutex.Lock(); }
 314     inline void wxCriticalSection::Leave() { (void)m_mutex.Unlock(); }
 315 #endif // MSW/!MSW
 316 #endif // wxUSE_THREADS
 317
 318 #endif // __THREADH__