[Wesnoth-cvs-commits] wesnoth/src thread.cpp thread.hpp (December 05, 2004 - 20:16)

 

CVSROOT:	/cvsroot/wesnoth
Module name:	wesnoth
Branch: 	
Changes by:	Guillaume Melquiond <guillaume.melquiond@xxxxxxxxx>	04/12/05 19:09:48

Modified files:
	src            : thread.cpp thread.hpp 

Log message:
	Apply patch #3480 which documents thread.hpp. Also comment the wait_timeout function since its use can really lead to problem on some systems.

CVSWeb URLs:
http://savannah.gnu.org/cgi-bin/viewcvs/wesnoth/wesnoth/src/thread.cpp.diff?tr1=1.3&tr2=1.4&r1=text&r2=text
http://savannah.gnu.org/cgi-bin/viewcvs/wesnoth/wesnoth/src/thread.hpp.diff?tr1=1.1&tr2=1.2&r1=text&r2=text

Patches:
Index: wesnoth/src/thread.cpp
diff -u wesnoth/src/thread.cpp:1.3 wesnoth/src/thread.cpp:1.4
--- wesnoth/src/thread.cpp:1.3	Thu Nov 18 04:08:32 2004
+++ wesnoth/src/thread.cpp	Sun Dec  5 19:09:47 2004
@@ -59,10 +59,12 @@
 	return SDL_CondWait(cond_,m.m_) == 0;
 }
 
+#if 0
 bool condition::wait_timeout(const mutex& m, unsigned int timeout)
 {
 	return SDL_CondWaitTimeout(cond_,m.m_,timeout) == 0;
 }
+#endif
 
 void condition::notify_one()
 {
Index: wesnoth/src/thread.hpp
diff -u wesnoth/src/thread.hpp:1.1 wesnoth/src/thread.hpp:1.2
--- wesnoth/src/thread.hpp:1.1	Mon Oct 11 23:46:40 2004
+++ wesnoth/src/thread.hpp	Sun Dec  5 19:09:47 2004
@@ -4,16 +4,44 @@
 #include "SDL.h"
 #include "SDL_thread.h"
 
+// Threading primitives wrapper for SDL_Thread.
+//
+// This module defines primitives for wrapping C++ around SDL's threading
+// interface
 namespace threading
 {
 
+// Threading object.
+//
+// This class defines threading objects. One such object represents a 
+// thread and admits killing and joining on threads. Intended to be
+// used for manipulating threads instead of poking around with SDL_Thread
+// calls.
 class thread
 {
 public:
+	// Construct a new thread to start executing the function 
+     	// pointed to by f. The void* data will be passed to f, to
+   	// facilitate passing of parameters to f.
+	//
+	// \param f the function at which the thread should start executing
+	// \param data passed to f
+	// 
+	// \pre f != NULL
 	explicit thread(int (*f)(void*), void* data=NULL);
+
+	// Destroy the thread object. This is done by waiting on the
+	// thread with the join() operation, thus blocking until the
+	// thread object has finished its operation.
 	~thread();
 
+	// Kill the thread. If the thread has already been killed, this
+	// is a no-op.
 	void kill();
+
+	// Join (wait) on the thread to finish. When the thread finishes,
+	// the function will return. calling wait() on an already killed
+	// thread is a no-op.
 	void join();
 private:
 	thread(const thread&);
@@ -22,6 +50,12 @@
 	SDL_Thread* thread_;
 };
 
+// Binary mutexes.
+//
+// Implements an interface to binary mutexes. This class only defines the
+// mutex itself. Locking is handled through the friend class lock,
+// and monitor interfacing through condition variables is handled through
+// the friend class condition.
 class mutex
 {
 public:
@@ -38,10 +72,24 @@
 	SDL_mutex* const m_;
 };
 
+// Binary mutex locking.
+//
+// Implements a locking object for mutexes. The creation of a lock
+// object on a mutex will lock the mutex as long as this object is
+// not deleted.
 class lock
 {
 public:
-	explicit lock(mutex&);
+	// Create a lock object on the mutex given as a parameter to
+	// the constructor. The lock will be held for the duration
+	// of the object existence. 
+	// If the mutex is already locked, the constructor will 
+	// block until the mutex lock can be acquired. 
+	//
+	// \param m the mutex on which we should try to lock.
+	explicit lock(mutex& m);
+	// Delete the lock object, thus releasing the lock aquired
+	// on the mutex which the lock object was created with.
 	~lock();
 private:
 	lock(const lock&);
@@ -50,15 +98,61 @@
 	mutex& m_;
 };
 
+// Condition variable locking.
+//
+// Implements condition variables for mutexes. A condition variable
+// allows you to free up a lock inside a critical section
+// of the code and regain it later. Condition classes only make
+// sense to do operations on, if one already aquired a mutex.
 class condition
 {
 public:
 	condition();
 	~condition();
 
+	// Wait on the condition. When the condition is met, you
+	// have a lock on the mutex and can do work in the critical
+	// section. When the condition is not met, wait blocks until
+	// the condition is met and atomically frees up the lock on
+	// the mutex. One will automatically regain the lock when the
+	// thread unblocks. 
+	//
+	// If wait returns false we have an error. In this case one cannot
+	// assume that he has a lock on the mutex anymore. 
+	// 
+	// \param m the mutex you wish to free the lock for
+	// \returns true: the wait was successful, false: an error occurred
+	//
+	// \pre You have already aquired a lock on mutex m
+	// 
 	bool wait(const mutex& m);
+	// wait on the condition with a timeout. Basically the same as the
+	// wait() function, but if the lock is not aquired before the 
+	// timeout, the function returns with an error.
+	//
+	// \param m the mutex you wish free the lock for. 
+	// \param timeout the allowed timeout in milliseconds (ms)
+	// \returns true: success, false: an error occurred
+	//
+	// \todo This function cannot check for timeout, which is to
+	// check on the SDL constant SDL_MUTEX_TIMEDOUT. Thus this 
+	// function cannot check if the error was due to something malformed
+	// or if the time ran out.
 	bool wait_timeout(const mutex& m, unsigned int timeout);
+	// signal the condition and wake up one thread waiting on the 
+	// condition. If no thread is waiting, notify_one() is a no-op.
+	// Does not unlock the mutex.
+	//
+	// \todo SDL_CondSignal can return an error. This is never checked
 	void notify_one();
+
+	// signal all threads waiting on the condition and let them contend
+	// for the lock. This is often used when varying resource amounts are
+	// involved and you do not know how many processes might continue.
+	// The function should be used with care, especially if many threads are
+	// waiting on the condition variable.
+	//	
+	// \todo SDL_CondBroadcast can return an error. This is never checked
 	void notify_all();
 
 private:



You are on the gna.org mail server.

Generated by mhonarc, Tue Sep 20 16:45:15 2005