More doxygen fun.

git-svn-id: http://svn.freeswitch.org/svn/freeswitch/trunk@257 d0543943-73ff-0310-b7d9-9358b9ac24b2

src/include/switch_mutex.h

@@ -29,9 +29,10 @@
  * switch_mutex.h -- Mutex Locking
  *
  */
-/*! \file switch_mutex.h
-    \brief Mutex Locking
+/*! \file switch_mutex.h
+    \brief Mutex Locking
 */
+
 #ifndef SWITCH_MUTEX_H
 #define SWITCH_MUTEX_H
 
@@ -41,16 +42,70 @@ extern "C" {
 
 #include <switch.h>
 
-SWITCH_DECLARE(switch_status) switch_mutex_init(switch_mutex_t **lock,
-								  switch_lock_flag flags,
-								  switch_memory_pool *pool);
+/**
+ * @defgroup switch_thread_mutex Thread Mutex Routines
+ * @ingroup FREESWITCH 
+ * @{
+ */
 
+/** Opaque thread-local mutex structure */
+typedef apr_thread_mutex_t switch_mutex_t;
+
+/** Lock Flags */
+typedef enum {
+	SWITCH_MUTEX_DEFAULT = APR_THREAD_MUTEX_DEFAULT	/**< platform-optimal lock behavior */,
+	SWITCH_MUTEX_NESTED = APR_THREAD_MUTEX_NESTED	/**< enable nested (recursive) locks */,
+	SWITCH_MUTEX_UNNESTED = APR_THREAD_MUTEX_UNNESTED	/**< disable nested locks */
+} switch_lock_flag;
+
+/**
+ * Create and initialize a mutex that can be used to synchronize threads.
+ * @param lock the memory address where the newly created mutex will be
+ *        stored.
+ * @param flags Or'ed value of:
+ * <PRE>
+ *           SWITCH_THREAD_MUTEX_DEFAULT   platform-optimal lock behavior.
+ *           SWITCH_THREAD_MUTEX_NESTED    enable nested (recursive) locks.
+ *           SWITCH_THREAD_MUTEX_UNNESTED  disable nested locks (non-recursive).
+ * </PRE>
+ * @param pool the pool from which to allocate the mutex.
+ * @warning Be cautious in using SWITCH_THREAD_MUTEX_DEFAULT.  While this is the
+ * most optimial mutex based on a given platform's performance charateristics,
+ * it will behave as either a nested or an unnested lock.
+ */
+SWITCH_DECLARE(switch_status) switch_mutex_init(switch_mutex_t **lock,
+												switch_lock_flag flags,
+												switch_memory_pool *pool);
+
+/**
+ * Destroy the mutex and free the memory associated with the lock.
+ * @param lock the mutex to destroy.
+ */
 SWITCH_DECLARE(switch_status) switch_mutex_destroy(switch_mutex_t *lock);
+
+/**
+ * Acquire the lock for the given mutex. If the mutex is already locked,
+ * the current thread will be put to sleep until the lock becomes available.
+ * @param lock the mutex on which to acquire the lock.
+ */
 SWITCH_DECLARE(switch_status) switch_mutex_lock(switch_mutex_t *lock);
+
+/**
+ * Release the lock for the given mutex.
+ * @param lock the mutex from which to release the lock.
+ */
 SWITCH_DECLARE(switch_status) switch_mutex_unlock(switch_mutex_t *lock);
+
+/**
+ * Attempt to acquire the lock for the given mutex. If the mutex has already
+ * been acquired, the call returns immediately with APR_EBUSY. Note: it
+ * is important that the APR_STATUS_IS_EBUSY(s) macro be used to determine
+ * if the return value was APR_EBUSY, for portability reasons.
+ * @param lock the mutex on which to attempt the lock acquiring.
+ */
 SWITCH_DECLARE(switch_status) switch_mutex_trylock(switch_mutex_t *lock);
 
-
+/** @} */
 #ifdef __cplusplus
 }
 #endif