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 #include "wx/object.h"
  20 #include "wx/setup.h"
  21 #include "wx/module.h"
  22
  23 // ----------------------------------------------------------------------------
  24 // constants
  25 // ----------------------------------------------------------------------------
  26
  27 typedef enum
  28 {
  29   wxMUTEX_NO_ERROR = 0,
  30   wxMUTEX_DEAD_LOCK,      // Mutex has been already locked by THE CALLING thread
  31   wxMUTEX_BUSY,           // Mutex has been already locked by ONE thread
  32   wxMUTEX_UNLOCKED,
  33   wxMUTEX_MISC_ERROR
  34 } wxMutexError;
  35
  36 typedef enum
  37 {
  38   wxTHREAD_NO_ERROR = 0,      // No error
  39   wxTHREAD_NO_RESOURCE,       // No resource left to create a new thread
  40   wxTHREAD_RUNNING,           // The thread is already running
  41   wxTHREAD_NOT_RUNNING,       // The thread isn't running
  42   wxTHREAD_MISC_ERROR         // Some other error
  43 } wxThreadError;
  44
  45 /* defines the interval of priority. */
  46 #define WXTHREAD_MIN_PRIORITY     0
  47 #define WXTHREAD_DEFAULT_PRIORITY 50
  48 #define WXTHREAD_MAX_PRIORITY     100
  49
  50 // ----------------------------------------------------------------------------
  51 // GUI mutex handling.
  52 // ----------------------------------------------------------------------------
  53
  54 void WXDLLEXPORT wxMutexGuiEnter();
  55 void WXDLLEXPORT wxMutexGuiLeave();
  56
  57 // ----------------------------------------------------------------------------
  58 // Mutex handler
  59 // ----------------------------------------------------------------------------
  60
  61 class WXDLLEXPORT wxMutexInternal;
  62 class WXDLLEXPORT wxMutex
  63 {
  64 public:
  65   // constructor & destructor
  66   wxMutex();
  67   ~wxMutex();
  68
  69   // Lock the mutex.
  70   wxMutexError Lock();
  71   // Try to lock the mutex: if it can't, returns immediately with an error.
  72   wxMutexError TryLock();
  73   // Unlock the mutex.
  74   wxMutexError Unlock();
  75
  76   // Returns true if the mutex is locked.
  77   bool IsLocked() const { return (m_locked > 0); }
  78
  79 protected:
  80   friend class wxCondition;
  81
  82   int m_locked;
  83   wxMutexInternal *p_internal;
  84 };
  85
  86 // ----------------------------------------------------------------------------
  87 // Condition handler.
  88 // ----------------------------------------------------------------------------
  89
  90 class wxConditionInternal;
  91 class WXDLLEXPORT wxCondition
  92 {
  93 public:
  94   // constructor & destructor
  95   wxCondition();
  96   ~wxCondition();
  97
  98   // Waits indefinitely.
  99   void Wait(wxMutex& mutex);
 100   // Waits until a signal is raised or the timeout is elapsed.
 101   bool Wait(wxMutex& mutex, unsigned long sec, unsigned long nsec);
 102   // Raises a signal: only one "Waiter" is released.
 103   void Signal();
 104   // Broadcasts to all "Waiters".
 105   void Broadcast();
 106
 107 private:
 108   wxConditionInternal *p_internal;
 109 };
 110
 111 // ----------------------------------------------------------------------------
 112 // Thread management class
 113 // ----------------------------------------------------------------------------
 114
 115 class wxThreadInternal;
 116 class WXDLLEXPORT wxThread
 117 {
 118 public:
 119   // constructor & destructor.
 120   wxThread();
 121   virtual ~wxThread();
 122
 123   // Create a new thread, this method should check there is only one thread
 124   // running by object.
 125   wxThreadError Create();
 126
 127   // Destroys the thread immediately if the defer flag isn't true.
 128   wxThreadError Destroy();
 129
 130   // Pause a running thread
 131   wxThreadError Pause();
 132
 133   // Resume a paused thread
 134   wxThreadError Resume();
 135
 136   // Switches on the defer flag.
 137   void DeferDestroy(bool on);
 138
 139   // Waits for the termination of the thread.
 140   void *Join();
 141
 142   // Sets the priority to "prio". (Warning: The priority can only be set before
 143   // the thread is created)
 144   void SetPriority(int prio);
 145   // Get the current priority.
 146   int GetPriority() const;
 147
 148   // Get the thread ID
 149   unsigned long GetID() const;
 150
 151   // Returns true if the thread is alive.
 152   bool IsAlive() const;
 153   // Returns true if the thread is running (not paused, not killed).
 154   bool IsRunning() const;
 155   // Returns true if the thread is suspended
 156   bool IsPaused() const { return IsAlive() && !IsRunning(); }
 157
 158   // Returns true if the thread is the main thread (aka the GUI thread).
 159   static bool IsMain();
 160
 161   // Called when thread exits.
 162   virtual void OnExit();
 163
 164 protected:
 165   // In case, the DIFFER flag is true, enables another thread to kill this one.
 166   void TestDestroy();
 167   // Exits from the current thread.
 168   void Exit(void *status = NULL);
 169
 170 private:
 171   // Entry point for the thread.
 172   virtual void *Entry() = 0;
 173
 174 private:
 175   friend class wxThreadInternal;
 176
 177   wxThreadInternal *p_internal;
 178 };
 179
 180 // ----------------------------------------------------------------------------
 181 // Automatic initialization
 182 // ----------------------------------------------------------------------------
 183
 184 class wxThreadModule : public wxModule
 185 {
 186   DECLARE_DYNAMIC_CLASS(wxThreadModule)
 187
 188 public:
 189   wxThreadModule() {}
 190
 191   virtual bool OnInit();
 192   virtual void OnExit();
 193 };
 194
 195
 196
 197 #endif // __THREADH__