include/threadengine.h

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