1 /* +------------------------------------+
2 * | Inspire Internet Relay Chat Daemon |
3 * +------------------------------------+
5 * InspIRCd: (C) 2002-2009 InspIRCd Development Team
6 * See: http://www.inspircd.org/wiki/index.php/Credits
8 * This program is free but copyrighted software; see
9 * the file COPYING for details.
11 * ---------------------------------------------------
14 #ifndef __THREADENGINE__
15 #define __THREADENGINE__
20 #include "inspircd_config.h"
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.
36 class CoreExport ThreadEngine : public Extensible
42 InspIRCd* ServerInstance;
44 /** New Thread being created.
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
55 * @param enable True to lock the mutex.
57 virtual bool Mutex(bool enable) = 0;
61 * @param Instance Creator object
63 ThreadEngine(InspIRCd* Instance);
67 virtual ~ThreadEngine();
69 /** Lock the system wide mutex. See the documentation for
70 * ThreadEngine::Mutex().
72 void Lock() { this->Mutex(true); }
74 /** Unlock the system wide mutex. See the documentation for
75 * ThreadEngine::Mutex()
77 void Unlock() { this->Mutex(false); }
79 /** Run the newly created thread.
81 virtual void Run() = 0;
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
89 virtual void Create(Thread* thread_to_init) = 0;
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.
96 virtual void FreeThread(Thread* thread) = 0;
98 /** Returns the thread engine's name for display purposes
99 * @return The thread engine name
101 virtual const std::string GetName()
103 return "<pure-virtual>";
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
115 class CoreExport Mutex : public Extensible
121 InspIRCd* ServerInstance;
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-
128 * @param enable True to enable the mutex (enter it) and false to
129 * disable the mutex (leave it).
131 virtual void Enable(bool enable) = 0;
135 * @param Instance Creator object
137 Mutex(InspIRCd* Instance);
139 /** Enter/enable the mutex lock.
141 void Lock() { Enable(true); }
143 /** Leave/disable the mutex lock.
145 void Unlock() { Enable(false); }
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!
156 class CoreExport Thread : public Extensible
159 /** Set to true when the thread is to exit
164 /** Creator thread engine
166 ThreadEngine* Creator;
168 /** Set Creator to NULL at this point
170 Thread() : ExitFlag(false), Creator(NULL)
174 /** If this thread has a Creator set, call it to
180 Creator->FreeThread(this);
183 /** Override this method to put your actual
184 * threaded code here.
186 virtual void Run() = 0;
188 /** Signal the thread to exit gracefully.
195 /** Cancel an exit state.
202 /** Get thread's current exit status.
203 * (are we being asked to exit?)