include/threadengine.h

   1 /*       +------------------------------------+
   2  *       | Inspire Internet Relay Chat Daemon |
   3  *       +------------------------------------+
   4  *
   5  *  InspIRCd: (C) 2002-2009 InspIRCd Development Team
   6  * See: http://wiki.inspircd.org/Credits
   7  *
   8  * This program is free but copyrighted software; see
   9  *            the file COPYING for details.
  10  *
  11  * ---------------------------------------------------
  12  */
  13
  14 #ifndef __THREADENGINE__
  15 #define __THREADENGINE__
  16
  17 #include <vector>
  18 #include <string>
  19 #include <map>
  20 #include "inspircd_config.h"
  21 #include "base.h"
  22
  23 class InspIRCd;
  24 class Thread;
  25
  26 /** The ThreadEngine class has the responsibility of initialising
  27  * Thread derived classes. It does this by creating operating system
  28  * level threads which are then associated with the class transparently.
  29  * This allows Thread classes to be derived without needing to know how
  30  * the OS implements threads. You should ensure that any sections of code
  31  * that use threads are threadsafe and do not interact with any other
  32  * parts of the code which are NOT known threadsafe! If you really MUST
  33  * access non-threadsafe code from a Thread, use the Mutex class to wrap
  34  * access to the code carefully.
  35  */
  36 class CoreExport ThreadEngine : public Extensible
  37 {
  38  protected:
  39
  40          /** Creator instance
  41           */
  42          InspIRCd* ServerInstance;
  43
  44          /** New Thread being created.
  45           */
  46          Thread* NewThread;
  47
  48          /** Enable or disable system-wide mutex for threading.
  49           * Remember that if you toggle the mutex you MUST UNSET
  50           * IT LATER otherwise the program will DEADLOCK!
  51           * It is recommended that you AVOID USE OF THIS METHOD
  52           * and use your own Mutex class, this function is mainly
  53           * reserved for use by the core and by the Thread engine
  54           * itself.
  55           * @param enable True to lock the mutex.
  56           */
  57          virtual bool Mutex(bool enable) = 0;
  58  public:
  59
  60         /** Constructor.
  61          * @param Instance Creator object
  62          */
  63         ThreadEngine(InspIRCd* Instance);
  64
  65         /** Destructor
  66          */
  67         virtual ~ThreadEngine();
  68
  69         /** Lock the system wide mutex. See the documentation for
  70          * ThreadEngine::Mutex().
  71          */
  72         void Lock() { this->Mutex(true); }
  73
  74         /** Unlock the system wide mutex. See the documentation for
  75          * ThreadEngine::Mutex()
  76          */
  77         void Unlock() { this->Mutex(false); }
  78
  79         /** Run the newly created thread.
  80          */
  81         virtual void Run() = 0;
  82
  83         /** Create a new thread. This takes an already allocated
  84          * Thread* pointer and initializes it to use this threading
  85          * engine. On failure, this function may throw a CoreException.
  86          * @param thread_to_init Pointer to a newly allocated Thread
  87          * derived object.
  88          */
  89         virtual void Create(Thread* thread_to_init) = 0;
  90
  91         /** This is called by the default destructor of the Thread
  92          * class to ensure that the thread engine which created the thread
  93          * is responsible for destroying it.
  94          * @param thread Existing and active thread to delete.
  95          */
  96         virtual void FreeThread(Thread* thread) = 0;
  97
  98         /** Returns the thread engine's name for display purposes
  99          * @return The thread engine name
 100          */
 101         virtual const std::string GetName()
 102         {
 103                 return "<pure-virtual>";
 104         }
 105 };
 106
 107 /** The Mutex class represents a mutex, which can be used to keep threads
 108  * properly synchronised. Use mutexes sparingly, as they are a good source
 109  * of thread deadlocks etc, and should be avoided except where absolutely
 110  * neccessary. Note that the internal behaviour of the mutex varies from OS
 111  * to OS depending on the thread engine, for example in windows a Mutex
 112  * in InspIRCd uses critical sections, as they are faster and simpler to
 113  * manage.
 114  */
 115 class CoreExport Mutex : public Extensible
 116 {
 117  protected:
 118
 119         /** Creator object
 120          */
 121         InspIRCd* ServerInstance;
 122
 123         /** Enable or disable the Mutex. This method has somewhat confusing
 124          * wording (e.g. the function name and parameters) so it is protected
 125          * in preference of the Lock() and Unlock() methods which are user-
 126          * accessible.
 127          *
 128          * @param enable True to enable the mutex (enter it) and false to
 129          * disable the mutex (leave it).
 130          */
 131         virtual void Enable(bool enable) = 0;
 132  public:
 133
 134         /** Constructor.
 135          * @param Instance Creator object
 136          */
 137         Mutex(InspIRCd* Instance);
 138
 139         /** Enter/enable the mutex lock.
 140          */
 141         void Lock() { Enable(true); }
 142
 143         /** Leave/disable the mutex lock.
 144          */
 145         void Unlock() { Enable(false); }
 146
 147         /** Destructor
 148          */
 149         ~Mutex() { }
 150 };
 151
 152 /** Derive from this class to implement your own threaded sections of
 153  * code. Be sure to keep your code thread-safe and not prone to deadlocks
 154  * and race conditions if you MUST use threading!
 155  */
 156 class CoreExport Thread : public Extensible
 157 {
 158  private:
 159         /** Set to true when the thread is to exit
 160          */
 161         bool ExitFlag;
 162  public:
 163
 164         /** Creator thread engine
 165          */
 166         ThreadEngine* Creator;
 167
 168         /** Set Creator to NULL at this point
 169          */
 170         Thread() : ExitFlag(false), Creator(NULL)
 171         {
 172         }
 173
 174         /** If this thread has a Creator set, call it to
 175          * free the thread
 176          */
 177         virtual ~Thread()
 178         {
 179                 if (Creator)
 180                         Creator->FreeThread(this);
 181         }
 182
 183         /** Override this method to put your actual
 184          * threaded code here.
 185          */
 186         virtual void Run() = 0;
 187
 188         /** Signal the thread to exit gracefully.
 189          */
 190         void SetExitFlag()
 191         {
 192                 ExitFlag = true;
 193         }
 194
 195         /** Cancel an exit state.
 196          */
 197         void ClearExitFlag()
 198         {
 199                 ExitFlag = false;
 200         }
 201
 202         /** Get thread's current exit status.
 203          * (are we being asked to exit?)
 204          */
 205         bool GetExitFlag()
 206         {
 207                 return ExitFlag;
 208         }
 209 };
 210
 211
 212
 213 #endif
 214