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