Documented the mutex API

libfreerdp-utils/mutex.c

@@ -1,4 +1,4 @@
-/**
+/*
  * FreeRDP: A Remote Desktop Protocol Client
  * Mutex Utils
  *
@@ -28,6 +28,22 @@
 #define freerdp_mutex_t pthread_mutex_t
 #endif
 
+/**
+ * Mutex are used to prevent concurrent accesses to specific portions of code.
+ * This funciton and the other freerdp_mutex_*() function are defining a portable API
+ * to get mutex for both Windows and Linux, where the lower level implementation is very different.
+ *
+ * This function creates a new freerdp_mutex object.
+ * Use freerdp_mutex_lock() to get exclusive ownership of the mutex, and lock a given (protected) portion of code.
+ * Use freerdp_mutex_unlock() to release your ownership on a mutex.
+ * Use freerdp_mutex_free() to release the resources associated with the mutex when it is no longer needed.
+ *
+ * @return a freerdp_mutex pointer. This should be considered opaque, as the implementation is platform dependent.
+ * NULL is returned if an allocation or initialization error occurred.
+ *
+ * @see pthread documentation for Linux implementation of mutexes
+ * @see MSDN http://msdn.microsoft.com/en-us/library/windows/desktop/ms682411%28v=vs.85%29.aspx for Windows implementation
+ */
 freerdp_mutex freerdp_mutex_new(void)
 {
 #ifdef _WIN32
@@ -37,11 +53,18 @@ freerdp_mutex freerdp_mutex_new(void)
 #else
 	freerdp_mutex_t* mutex;
 	mutex = xnew(freerdp_mutex_t);
-	pthread_mutex_init(mutex, 0);
+	if (mutex)
+		pthread_mutex_init(mutex, 0);
 	return mutex;
 #endif
 }
 
+/**
+ * This function is used to deallocate all resources associated with a freerdp_mutex object.
+ *
+ * @param mutex [in]	- Pointer to the mutex that needs to be deallocated.
+ * 						  On return, this object is not valid anymore.
+ */
 void freerdp_mutex_free(freerdp_mutex mutex)
 {
 #ifdef _WIN32
@@ -52,6 +75,15 @@ void freerdp_mutex_free(freerdp_mutex mutex)
 #endif
 }
 
+/**
+ * Use this function to get exclusive ownership of the mutex.
+ * This should be called before entering a portion of code that needs to be protected against concurrent accesses.
+ * Use the freerdp_mutex_unlock() call to release ownership when you leave this protected code.
+ *
+ * @param mutex [in]	- An initialized freerdp_mutex object, as returned from a call to freerdp_mutex_new().
+ *						  This function will suspend the running thread when called, until the mutex is available.
+ *						  Only one thread at a time will be allowed to continue execution.
+ */
 void freerdp_mutex_lock(freerdp_mutex mutex)
 {
 #ifdef _WIN32
@@ -61,6 +93,13 @@ void freerdp_mutex_lock(freerdp_mutex mutex)
 #endif
 }
 
+/**
+ * Use this function to release your ownership on a mutex.
+ * This should be called when leaving a portion of code that needs to be protected against concurrent accesses.
+ * DO NOT use this call on a mutex that you do not own. See freerdp_mutex_lock() for getting ownership on a mutex.
+ *
+ * @param mutex [in]	- Pointer to a mutex that was locked by a call to freerdp_mutex_lock().
+ */
 void freerdp_mutex_unlock(freerdp_mutex mutex)
 {
 #ifdef _WIN32