# HG changeset patch
# User Sam Lantinga <slouken@libsdl.org>
# Date 1296153617 28800
# Node ID 0846f18eb62516a2228371d96c4b62c917824419
# Parent  5df0c142db9bf79af994cb67a640d440a676d705
Improved condition variable documentation

diff -r 5df0c142db9b -r 0846f18eb625 include/SDL_mutex.h
--- a/include/SDL_mutex.h	Thu Jan 27 10:07:14 2011 -0800
+++ b/include/SDL_mutex.h	Thu Jan 27 10:40:17 2011 -0800
@@ -164,6 +164,31 @@
 
 /**
  *  Create a condition variable.
+ *
+ *  Typical use of condition variables:
+ *
+ *  Thread A:
+ *    SDL_LockMutex(lock);
+ *    while ( ! condition ) {
+ *        SDL_CondWait(cond, lock);
+ *    }
+ *    SDL_UnlockMutex(lock);
+ *
+ *  Thread B:
+ *    SDL_LockMutex(lock);
+ *    ...
+ *    condition = true;
+ *    ...
+ *    SDL_CondSignal(cond);
+ *    SDL_UnlockMutex(lock);
+ *
+ *  There is some discussion whether to signal the condition variable
+ *  with the mutex locked or not.  There is some potential performance
+ *  benefit to unlocking first on some platforms, but there are some
+ *  potential race conditions depending on how your code is structured.
+ *
+ *  In general it's safer to signal the condition variable while the
+ *  mutex is locked.
  */
 extern DECLSPEC SDL_cond *SDLCALL SDL_CreateCond(void);
 
@@ -181,6 +206,7 @@
 
 /**
  *  Restart all threads that are waiting on the condition variable.
+ *
  *  \return 0 or -1 on error.
  */
 extern DECLSPEC int SDLCALL SDL_CondBroadcast(SDL_cond * cond);
diff -r 5df0c142db9b -r 0846f18eb625 src/thread/generic/SDL_syscond.c
--- a/src/thread/generic/SDL_syscond.c	Thu Jan 27 10:07:14 2011 -0800
+++ b/src/thread/generic/SDL_syscond.c	Thu Jan 27 10:40:17 2011 -0800
@@ -145,18 +145,19 @@
 Typical use:
 
 Thread A:
-	SDL_LockMutex(lock);
-	while ( ! condition ) {
-		SDL_CondWait(cond);
-	}
-	SDL_UnlockMutex(lock);
+    SDL_LockMutex(lock);
+    while ( ! condition ) {
+        SDL_CondWait(cond, lock);
+    }
+    SDL_UnlockMutex(lock);
 
 Thread B:
-	SDL_LockMutex(lock);
-	...
-	condition = true;
-	...
-	SDL_UnlockMutex(lock);
+    SDL_LockMutex(lock);
+    ...
+    condition = true;
+    ...
+    SDL_CondSignal(cond);
+    SDL_UnlockMutex(lock);
  */
 int
 SDL_CondWaitTimeout(SDL_cond * cond, SDL_mutex * mutex, Uint32 ms)