X-Git-Url: https://git.netwichtig.de/gitweb/?a=blobdiff_plain;f=include%2Fthreadengine.h;h=a8b66ad98de5afb33c73f8695bb5a18e2b9a570e;hb=4d03a38661cb7fa6a0880b66bbebf1d892ba5013;hp=56ccce4239f44a0fbbddef9c3fac4a89199c69e1;hpb=2cc6856e8709c9a5c339ab4af1c0d0b9a01ed917;p=user%2Fhenk%2Fcode%2Finspircd.git

diff --git a/include/threadengine.h b/include/threadengine.h
index 56ccce423..a8b66ad98 100644
--- a/include/threadengine.h
+++ b/include/threadengine.h
@@ -29,7 +29,9 @@ class Thread;
  * This allows Thread classes to be derived without needing to know how
  * the OS implements threads. You should ensure that any sections of code
  * that use threads are threadsafe and do not interact with any other
- * parts of the code which are NOT known threadsafe!
+ * parts of the code which are NOT known threadsafe! If you really MUST
+ * access non-threadsafe code from a Thread, use the Mutex class to wrap
+ * access to the code carefully.
  */
 class CoreExport ThreadEngine : public Extensible
 {
@@ -38,13 +40,25 @@ class CoreExport ThreadEngine : public Extensible
 	 /** Creator instance
 	  */
 	 InspIRCd* ServerInstance;
+
 	 /** New Thread being created.
 	  */
 	 Thread* NewThread;
 
+	 /** Enable or disable system-wide mutex for threading.
+	  * Remember that if you toggle the mutex you MUST UNSET
+	  * IT LATER otherwise the program will DEADLOCK!
+	  * It is recommended that you AVOID USE OF THIS METHOD
+	  * and use your own Mutex class, this function is mainly
+	  * reserved for use by the core and by the Thread engine
+	  * itself.
+	  * @param enable True to lock the mutex.
+	  */
+	 virtual bool Mutex(bool enable) = 0;
  public:
 
-	/** Constructor
+	/** Constructor.
+	 * @param Instance Creator object
 	 */
 	ThreadEngine(InspIRCd* Instance);
 
@@ -52,36 +66,99 @@ class CoreExport ThreadEngine : public Extensible
 	 */
 	virtual ~ThreadEngine();
 
-	/** Enable or disable system-wide mutex for threading.
-	 * This MUST be called when you deal with ANYTHING that
-	 * isnt known thread-safe, this INCLUDES STL!
-	 * Remember that if you toggle the mutex you MUST UNSET
-	 * IT LATER otherwise the program will DEADLOCK!
+	/** Lock the system wide mutex. See the documentation for
+	 * ThreadEngine::Mutex().
 	 */
-	virtual bool Mutex(bool enable) = 0;
+	void Lock() { this->Mutex(true); }
 
-	/** Run the newly created thread
+	/** Unlock the system wide mutex. See the documentation for
+	 * ThreadEngine::Mutex()
+	 */
+	void Unlock() { this->Mutex(false); }
+
+	/** Run the newly created thread.
 	 */
 	virtual void Run() = 0;
 
 	/** Create a new thread. This takes an already allocated
 	 * Thread* pointer and initializes it to use this threading
 	 * engine. On failure, this function may throw a CoreException.
+	 * @param thread_to_init Pointer to a newly allocated Thread
+	 * derived object.
 	 */
 	virtual void Create(Thread* thread_to_init) = 0;
 
 	/** This is called by the default destructor of the Thread
 	 * class to ensure that the thread engine which created the thread
 	 * is responsible for destroying it.
+	 * @param thread Existing and active thread to delete.
 	 */
 	virtual void FreeThread(Thread* thread) = 0;
+
+	/** Returns the thread engine's name for display purposes
+	 * @return The thread engine name
+	 */
+	virtual const std::string GetName()
+	{
+		return "<pure-virtual>";
+	}
+};
+
+/** The Mutex class represents a mutex, which can be used to keep threads
+ * properly synchronised. Use mutexes sparingly, as they are a good source
+ * of thread deadlocks etc, and should be avoided except where absolutely
+ * neccessary. Note that the internal behaviour of the mutex varies from OS
+ * to OS depending on the thread engine, for example in windows a Mutex
+ * in InspIRCd uses critical sections, as they are faster and simpler to
+ * manage.
+ */
+class CoreExport Mutex : public Extensible
+{
+ protected:
+
+	/** Creator object
+	 */
+	InspIRCd* ServerInstance;
+
+	/** Enable or disable the Mutex. This method has somewhat confusing
+	 * wording (e.g. the function name and parameters) so it is protected
+	 * in preference of the Lock() and Unlock() methods which are user-
+	 * accessible.
+	 *
+	 * @param enable True to enable the mutex (enter it) and false to
+	 * disable the mutex (leave it).
+	 */
+	virtual void Enable(bool enable) = 0;
+ public:
+
+	/** Constructor.
+	 * @param Instance Creator object
+	 */
+	Mutex(InspIRCd* Instance);
+
+	/** Enter/enable the mutex lock.
+	 */
+	void Lock() { Enable(true); }
+
+	/** Leave/disable the mutex lock.
+	 */
+	void Unlock() { Enable(false); }
+
+	/** Destructor
+	 */
+	~Mutex() { }
 };
 
 /** Derive from this class to implement your own threaded sections of
- * code.
+ * code. Be sure to keep your code thread-safe and not prone to deadlocks
+ * and race conditions if you MUST use threading!
  */
 class CoreExport Thread : public Extensible
 {
+ private:
+	/** Set to true when the thread is to exit
+	 */
+	bool ExitFlag;
  public:
 
 	/** Creator thread engine
@@ -90,7 +167,7 @@ class CoreExport Thread : public Extensible
 
 	/** Set Creator to NULL at this point
 	 */
-	Thread() : Creator(NULL)
+	Thread() : ExitFlag(false), Creator(NULL)
 	{
 	}
 
@@ -104,9 +181,31 @@ class CoreExport Thread : public Extensible
 	}
 
 	/** Override this method to put your actual
-	 * threaded code here
+	 * threaded code here.
 	 */
 	virtual void Run() = 0;
+
+	/** Signal the thread to exit gracefully.
+	 */
+	void SetExitFlag()
+	{
+		ExitFlag = true;
+	}
+
+	/** Cancel an exit state.
+	 */
+	void ClearExitFlag()
+	{
+		ExitFlag = false;
+	}
+
+	/** Get thread's current exit status.
+	 * (are we being asked to exit?)
+	 */
+	bool GetExitFlag()
+	{
+		return ExitFlag;
+	}
 };