Add comments

git-svn-id: http://svn.inspircd.org/repository/trunk/inspircd@8883 e03df62e-2008-0410-955e-edbf42e46eb7

diff --git a/include/threadengine.h b/include/threadengine.h
index 0f729a962e16a1d394583f896c5da7892f03d3b9..56ccce4239f44a0fbbddef9c3fac4a89199c69e1 100644 (file)
--- a/include/threadengine.h
+++ b/include/threadengine.h
@@ -23,45 +23,89 @@
 class InspIRCd;
 class Thread;
 
-
+/** The ThreadEngine class has the responsibility of initialising
+ * Thread derived classes. It does this by creating operating system
+ * level threads which are then associated with the class transparently.
+ * 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!
+ */
 class CoreExport ThreadEngine : public Extensible
 {
  protected:
 
+        /** Creator instance
+         */
         InspIRCd* ServerInstance;
+        /** New Thread being created.
+         */
         Thread* NewThread;
 
  public:
 
+       /** Constructor
+        */
        ThreadEngine(InspIRCd* Instance);
 
+       /** Destructor
+        */
        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!
+        */
        virtual bool Mutex(bool enable) = 0;
 
+       /** 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.
+        */
        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.
+        */
        virtual void FreeThread(Thread* thread) = 0;
 };
 
+/** Derive from this class to implement your own threaded sections of
+ * code.
+ */
 class CoreExport Thread : public Extensible
 {
  public:
 
+       /** Creator thread engine
+        */
        ThreadEngine* Creator;
 
+       /** Set Creator to NULL at this point
+        */
        Thread() : Creator(NULL)
        {
        }
 
+       /** If this thread has a Creator set, call it to
+        * free the thread
+        */
        virtual ~Thread()
        {
                if (Creator)
                        Creator->FreeThread(this);
        }
 
+       /** Override this method to put your actual
+        * threaded code here
+        */
        virtual void Run() = 0;
 };