[Scummvm-cvs-logs] SF.net SVN: scummvm: [29952] scummvm/trunk/common/system.h

[fingolfin at users.sourceforge.net]

Revision: 29952
          http://scummvm.svn.sourceforge.net/scummvm/?rev=29952&view=rev
Author:   fingolfin
Date:     2007-12-22 05:16:01 -0800 (Sat, 22 Dec 2007)

Log Message:
-----------
Document that we expect recursive mutex locking behavior

Modified Paths:
--------------
    scummvm/trunk/common/system.h

Modified: scummvm/trunk/common/system.h
===================================================================
--- scummvm/trunk/common/system.h	2007-12-22 11:53:04 UTC (rev 29951)
+++ scummvm/trunk/common/system.h	2007-12-22 13:16:01 UTC (rev 29952)
@@ -750,6 +750,8 @@
 	 * But since those may be implemented using threads (and in fact, that's
 	 * how our primary backend, the SDL one, does it on many systems), we
 	 * still have to do mutex syncing in our timer callbacks.
+	 * In addition, the sound mixer uses a mutex in case the backend runs it
+	 * from a dedicated thread (as e.g. the SDL backend does).
 	 *
 	 * Hence backends which do not use threads to implement the timers simply
 	 * can use dummy implementations for these methods.
@@ -766,6 +768,12 @@
 
 	/**
 	 * Lock the given mutex.
+	 *
+	 * @note ScummVM code assumes that the mutex implementation supports
+	 * recursive locking. That is, a thread may lock a mutex twice w/o
+	 * deadlocking. In case of a multilock, the mutex has to be unlocked
+	 * as many times as it was locked befored it really becomes unlocked.
+	 *
 	 * @param mutex	the mutex to lock.
 	 */
 	virtual void lockMutex(MutexRef mutex) = 0;


This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.