Document SendMetaData.

[user/henk/code/inspircd.git] / include / threadengine.h

diff --git a/include/threadengine.h b/include/threadengine.h
index 9c87f83b267fadf58c442e7a06c97724b9f9b63e..a8b66ad98de5afb33c73f8695bb5a18e2b9a570e 100644 (file)
--- 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,54 +66,98 @@ 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().
+        */
+       void Lock() { this->Mutex(true); }
+
+       /** Unlock the system wide mutex. See the documentation for
+        * ThreadEngine::Mutex()
         */
-       virtual bool Mutex(bool enable) = 0;
+       void Unlock() { this->Mutex(false); }
 
-       /** Run the newly created thread
+       /** 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);
-       virtual void Enable(bool enable) = 0;
+
+       /** 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:
 
@@ -123,20 +181,27 @@ 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;