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   int m_locked;
  85   wxMutexInternal *p_internal;
  86 };
  87
  88 // a helper class which locks the mutex in the ctor and unlocks it in the dtor:
  89 // this ensures that mutex is always unlocked, even if the function returns or
  90 // throws an exception before it reaches the end
  91 class WXDLLEXPORT wxMutexLocker
  92 {
  93 public:
  94     // lock the mutex in the ctor
  95     wxMutexLocker(wxMutex *mutex)
  96         { m_isOk = mutex && ((m_mutex = mutex)->Lock() == wxMUTEX_NO_ERROR); }
  97
  98     // returns TRUE if mutex was successfully locked in ctor
  99     bool IsOk() const { return m_isOk; }
 100
 101     // unlock the mutex in dtor
 102     ~wxMutexLocker() { if ( IsOk() ) m_mutex->Unlock(); }
 103
 104 private:
 105     bool     m_isOk;
 106     wxMutex *m_mutex;
 107 };
 108
 109 #ifdef __WXMSW__
 110
 111 // ----------------------------------------------------------------------------
 112 // Critical section: this is the same as mutex but is only visible to the
 113 // threads of the same process. For the platforms which don't have native
 114 // support for critical sections, they're implemented entirely in terms of
 115 // mutexes
 116 // ----------------------------------------------------------------------------
 117
 118 // you should consider wxCriticalSectionLocker whenever possible instead of
 119 // directly working with wxCriticalSection class - it is safer
 120 class WXDLLEXPORT wxCriticalSectionInternal;
 121 class WXDLLEXPORT wxCriticalSection
 122 {
 123 public:
 124     // ctor & dtor
 125     wxCriticalSection();
 126     ~wxCriticalSection();
 127
 128     // enter the section (the same as locking a mutex)
 129     void Enter();
 130     // leave the critical section (same as unlocking a mutex)
 131     void Leave();
 132
 133 private:
 134     wxCriticalSectionInternal *m_critsect;
 135 };
 136
 137 // wxCriticalSectionLocker is the same to critical sections as wxMutexLocker is
 138 // to th mutexes
 139 class WXDLLEXPORT wxCriticalSectionLocker
 140 {
 141 public:
 142     wxCriticalSectionLocker(wxCriticalSection& critsect) : m_critsect(critsect)
 143         { m_critsect.Enter(); }
 144     ~wxCriticalSectionLocker()
 145         { m_critsect.Leave(); }
 146
 147 private:
 148     wxCriticalSection& m_critsect;
 149 };
 150
 151 #endif
 152
 153 // ----------------------------------------------------------------------------
 154 // Condition handler.
 155 // ----------------------------------------------------------------------------
 156
 157 class wxConditionInternal;
 158 class WXDLLEXPORT wxCondition
 159 {
 160 public:
 161   // constructor & destructor
 162   wxCondition();
 163   ~wxCondition();
 164
 165   // Waits indefinitely.
 166   void Wait(wxMutex& mutex);
 167   // Waits until a signal is raised or the timeout is elapsed.
 168   bool Wait(wxMutex& mutex, unsigned long sec, unsigned long nsec);
 169   // Raises a signal: only one "Waiter" is released.
 170   void Signal();
 171   // Broadcasts to all "Waiters".
 172   void Broadcast();
 173
 174 private:
 175   wxConditionInternal *p_internal;
 176 };
 177
 178 // ----------------------------------------------------------------------------
 179 // Thread management class
 180 // ----------------------------------------------------------------------------
 181
 182 class wxThreadInternal;
 183 class WXDLLEXPORT wxThread
 184 {
 185 public:
 186   // constructor & destructor.
 187   wxThread();
 188   virtual ~wxThread();
 189
 190   // Create a new thread, this method should check there is only one thread
 191   // running by object.
 192   wxThreadError Create();
 193
 194   // Destroys the thread immediately if the defer flag isn't true.
 195   wxThreadError Destroy();
 196
 197   // Pause a running thread
 198   wxThreadError Pause();
 199
 200   // Resume a paused thread
 201   wxThreadError Resume();
 202
 203   // Switches on the defer flag.
 204   void DeferDestroy(bool on);
 205
 206   // Waits for the termination of the thread.
 207   void *Join();
 208
 209   // Sets the priority to "prio". (Warning: The priority can only be set before
 210   // the thread is created)
 211   void SetPriority(int prio);
 212   // Get the current priority.
 213   int GetPriority() const;
 214
 215   // Get the thread ID
 216   unsigned long GetID() const;
 217
 218   // Returns true if the thread is alive.
 219   bool IsAlive() const;
 220   // Returns true if the thread is running (not paused, not killed).
 221   bool IsRunning() const;
 222   // Returns true if the thread is suspended
 223   bool IsPaused() const { return IsAlive() && !IsRunning(); }
 224
 225   // Returns true if current thread is the main thread (aka the GUI thread)
 226   static bool IsMain();
 227
 228   // Called when thread exits.
 229   virtual void OnExit();
 230
 231 protected:
 232   // Returns TRUE if the thread was asked to terminate
 233   bool TestDestroy();
 234
 235   // Exits from the current thread.
 236   void Exit(void *status = NULL);
 237
 238 private:
 239   // Entry point for the thread.
 240   virtual void *Entry() = 0;
 241
 242 private:
 243   friend class wxThreadInternal;
 244
 245   wxThreadInternal *p_internal;
 246 };
 247
 248 // ----------------------------------------------------------------------------
 249 // Automatic initialization
 250 // ----------------------------------------------------------------------------
 251
 252 // GUI mutex handling.
 253 void WXDLLEXPORT wxMutexGuiEnter();
 254 void WXDLLEXPORT wxMutexGuiLeave();
 255
 256 // implementation only
 257 #ifdef __WXMSW__
 258     // unlock GUI if there are threads waiting for and lock it back when
 259     // there are no more of them - should be called periodically by the main
 260     // thread
 261     void WXDLLEXPORT wxMutexGuiLeaveOrEnter();
 262
 263     // returns TRUE if the main thread has GUI lock
 264     inline bool WXDLLEXPORT wxGuiOwnedByMainThread();
 265
 266     // wakes up the main thread if it's sleeping inside ::GetMessage()
 267     inline void WXDLLEXPORT wxWakeUpMainThread();
 268 #endif // MSW
 269
 270 #else // !wxUSE_THREADS
 271
 272 // no thread support
 273 inline void WXDLLEXPORT wxMutexGuiEnter() { }
 274 inline void WXDLLEXPORT wxMutexGuiLeave() { }
 275
 276 #endif // wxUSE_THREADS
 277
 278 // automatically unlock GUI mutex in dtor
 279 class WXDLLEXPORT wxMutexGuiLocker
 280 {
 281 public:
 282     wxMutexGuiLocker() { wxMutexGuiEnter(); }
 283    ~wxMutexGuiLocker() { wxMutexGuiLeave(); }
 284 };
 285
 286 #endif // __THREADH__