[pclasses-cvs] pclasses2/include/pclasses/Util ManagedThread.h,1.2,1.3 WorkQueue.h,1.2,1.3

[Christian P. <cp...@us...>]

Update of /cvsroot/pclasses/pclasses2/include/pclasses/Util
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv17285/include/pclasses/Util

Modified Files:
	ManagedThread.h WorkQueue.h 
Log Message:
Added inline docs.
Fixes for changes in Thread.


Index: WorkQueue.h
===================================================================
RCS file: /cvsroot/pclasses/pclasses2/include/pclasses/Util/WorkQueue.h,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -d -r1.2 -r1.3
--- WorkQueue.h	23 Jan 2005 13:51:38 -0000	1.2
+++ WorkQueue.h	28 Jan 2005 11:39:36 -0000	1.3
@@ -80,7 +80,7 @@
 		~WorkerThread() throw();
 
 	private:
-		virtual int main();
+		virtual int mainLoop();
 
 		WorkQueue&  _queue;
 };

Index: ManagedThread.h
===================================================================
RCS file: /cvsroot/pclasses/pclasses2/include/pclasses/Util/ManagedThread.h,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -d -r1.2 -r1.3
--- ManagedThread.h	26 Dec 2004 15:22:42 -0000	1.2
+++ ManagedThread.h	28 Jan 2005 11:39:36 -0000	1.3
@@ -29,15 +29,26 @@
 
 namespace Util {
 
-class ManagedThread: private System::Thread {
+//! Managed thread
+/*!
+	An advanced threading class that allows to suspend, resume
+	and exit the thread from the outside (that is other thread
+	contexts). 
+*/
+class ManagedThread: public System::Thread {
 	public:
+
+		//! Thread states
 		enum State {
-			Stopped   = 0x01,
-			Startup   = 0x02,
-			Running   = 0x04,
-			Suspended = 0x08,
-			Finished  = 0x10,
-			Failed    = 0x20
+			Stopped   = 0x01,  /*<! Initial thread state 
+			                        (or after joining the Thread) */
+			Startup   = 0x02,  /*<! Thread is starting (in init(), 
+			                        before mainLoop()) */
+			Running   = 0x04,  /*<! Thread is running (in mainLoop()) */
+			Suspended = 0x08,  /*<! Thread is suspended */
+			Finished  = 0x10,  /*<! Thread is finished */
+			Failed    = 0x20,  /*<! Thread has failed (init() returned != 0) */
+			AnyState  = 0xff
 		};
 	
 		ManagedThread() throw();
@@ -46,31 +57,95 @@
 		//! Returns the current thread-state
 		State state() const throw(System::SystemError);
 
+		//! Start the thread
 		void start() throw(LogicError, System::SystemError);
+
+		//! Signal the thread to exit
 		void stop() throw();
+
+		//! Signal the thread to suspend
 		void suspend() throw();
+
+		//! Signal the thread to resume
 		void resume() throw(System::SystemError);
 
+		//! Wait for thread termination and cleanup
+		/*!
+			Wait for thread termination and cleanup all used
+			resources. You should signal the thread to stop before
+			waiting for it's termination.
+		*/
 		int join() throw(System::SystemError);
-		
+
+		//! Wait for state-change
 		State wait(int stateMask);
+
+		//! Wait for state-change with timeout
 		State tryWait(int stateMask, unsigned int timeout = 0);
 
 	protected:
+
+		//! Test for exit/suspend
+		/*!
+			This method should be frequently called to allow suspend, 
+			resume and exit notifies. If the thread should exit the 
+			method returns false. If suspend was requested the method 
+			calls suspended() and waits until the thread has been 
+			resumed. Before returning control to the caller, resumed() 
+			will be called.
+			\return true if the main-loop should continue, 
+				false otherwise.
+		*/
 		bool shouldRun() throw(System::SystemError);
-		
+
+		//! Thread initialization
+		/*!
+			The method is called before the mainLoop() is executed.
+			When returning with an non-zero error-code the thread will
+			terminate and set the status to Failed. When successfull the
+			status will be set to Running.
+			\return zero if the initialization was the successfull,
+				non-zero exit-code otherwise.
+		*/
 		virtual int init();
-		virtual int main() = 0;
+
+		//! Threads main-loop
+		/*!
+			The method should implement the threads main-loop and is 
+			called after successfully returning from the init() method.
+			The implementation of this method should frequently call 
+			shouldRun() to allow suspend, resume and exit notifies.
+		*/
+		virtual int mainLoop() = 0;
+
+		//! Cleanup method
+		/*!
+			The method is called when the thread is about to exit,
+			after returning from the main() method. When returning
+			from this method the status of the thread will be set
+			to Finished.
+		*/
 		virtual void cleanup();
-	virtual void suspended() {};
-	virtual void resumed() {};
-	//  ^^^^^ACHTUNG: no-op impls of suspended()/resumed() added by
-	// stephan to work around a link error. i have no clue what
-	// they SHOULD do.
+
+		//! Called when the thread has been suspended
+		/*!
+			The method is called when the thread is about to suspend
+			its execution.
+		*/
+		virtual void suspended();
+
+		//! Called when the thread has been resumed
+		/*!
+			The method is called when the thread is about to resume
+			its execution.
+		*/
+		virtual void resumed();
 
 	private:
-		virtual int main(void* arg);
+		//! Implements the Threads main-method
+		virtual int main();
 
+		//! Changes state and notifies the Condition
 		void changeState(State newState);
 
 		State                 _state;