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 // ----------------------------------------------------------------------------
 110 // Critical section: this is the same as mutex but is only visible to the
 111 // threads of the same process. For the platforms which don't have native
 112 // support for critical sections, they're implemented entirely in terms of
 113 // mutexes
 114 // ----------------------------------------------------------------------------
 115
 116 // you should consider wxCriticalSectionLocker whenever possible instead of
 117 // directly working with wxCriticalSection class - it is safer
 118 class WXDLLEXPORT wxCriticalSectionInternal;
 119 class WXDLLEXPORT wxCriticalSection
 120 {
 121 public:
 122     // ctor & dtor
 123     wxCriticalSection();
 124     ~wxCriticalSection();
 125
 126     // enter the section (the same as locking a mutex)
 127     void Enter();
 128     // leave the critical section (same as unlocking a mutex)
 129     void Leave();
 130
 131 private:
 132     wxCriticalSectionInternal *m_critsect;
 133 };
 134
 135 // wxCriticalSectionLocker is the same to critical sections as wxMutexLocker is
 136 // to th mutexes
 137 class WXDLLEXPORT wxCriticalSectionLocker
 138 {
 139 public:
 140     wxCriticalSectionLocker(wxCriticalSection *critsect)
 141         { (m_critsect = critsect)->Enter(); }
 142     ~wxCriticalSectionLocker()
 143         { m_critsect->Leave(); }
 144
 145 private:
 146     wxCriticalSection *m_critsect;
 147 };
 148
 149 // ----------------------------------------------------------------------------
 150 // Condition handler.
 151 // ----------------------------------------------------------------------------
 152
 153 class wxConditionInternal;
 154 class WXDLLEXPORT wxCondition
 155 {
 156 public:
 157   // constructor & destructor
 158   wxCondition();
 159   ~wxCondition();
 160
 161   // Waits indefinitely.
 162   void Wait(wxMutex& mutex);
 163   // Waits until a signal is raised or the timeout is elapsed.
 164   bool Wait(wxMutex& mutex, unsigned long sec, unsigned long nsec);
 165   // Raises a signal: only one "Waiter" is released.
 166   void Signal();
 167   // Broadcasts to all "Waiters".
 168   void Broadcast();
 169
 170 private:
 171   wxConditionInternal *p_internal;
 172 };
 173
 174 // ----------------------------------------------------------------------------
 175 // Thread management class
 176 // ----------------------------------------------------------------------------
 177
 178 class wxThreadInternal;
 179 class WXDLLEXPORT wxThread
 180 {
 181 public:
 182   // constructor & destructor.
 183   wxThread();
 184   virtual ~wxThread();
 185
 186   // Create a new thread, this method should check there is only one thread
 187   // running by object.
 188   wxThreadError Create();
 189
 190   // Destroys the thread immediately if the defer flag isn't true.
 191   wxThreadError Destroy();
 192
 193   // Pause a running thread
 194   wxThreadError Pause();
 195
 196   // Resume a paused thread
 197   wxThreadError Resume();
 198
 199   // Switches on the defer flag.
 200   void DeferDestroy(bool on);
 201
 202   // Waits for the termination of the thread.
 203   void *Join();
 204
 205   // Sets the priority to "prio". (Warning: The priority can only be set before
 206   // the thread is created)
 207   void SetPriority(int prio);
 208   // Get the current priority.
 209   int GetPriority() const;
 210
 211   // Get the thread ID
 212   unsigned long GetID() const;
 213
 214   // Returns true if the thread is alive.
 215   bool IsAlive() const;
 216   // Returns true if the thread is running (not paused, not killed).
 217   bool IsRunning() const;
 218   // Returns true if the thread is suspended
 219   bool IsPaused() const { return IsAlive() && !IsRunning(); }
 220
 221   // Returns true if current thread is the main thread (aka the GUI thread)
 222   static bool IsMain();
 223
 224   // Called when thread exits.
 225   virtual void OnExit();
 226
 227 protected:
 228   // Returns TRUE if the thread was asked to terminate
 229   bool TestDestroy();
 230
 231   // Exits from the current thread.
 232   void Exit(void *status = NULL);
 233
 234 private:
 235   // Entry point for the thread.
 236   virtual void *Entry() = 0;
 237
 238 private:
 239   friend class wxThreadInternal;
 240
 241   wxThreadInternal *p_internal;
 242 };
 243
 244 // ----------------------------------------------------------------------------
 245 // Automatic initialization
 246 // ----------------------------------------------------------------------------
 247
 248 // GUI mutex handling.
 249 void WXDLLEXPORT wxMutexGuiEnter();
 250 void WXDLLEXPORT wxMutexGuiLeave();
 251
 252 #else // !wxUSE_THREADS
 253
 254 // no thread support
 255 inline void WXDLLEXPORT wxMutexGuiEnter() { }
 256 inline void WXDLLEXPORT wxMutexGuiLeave() { }
 257
 258 #endif // wxUSE_THREADS
 259
 260 #endif // __THREADH__