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