From 79c68f7855e83d0a9c641dadb8a0a378cf343c92 Mon Sep 17 00:00:00 2001
From: Adam Dickmeiss <adam@indexdata.dk>
Date: Tue, 23 Mar 2010 11:28:38 +0100
Subject: [PATCH] Documentation for mutex util

---
 include/yaz/mutex.h    |   54 ++++++++++++++++++++++++++++++++++++++----------
 include/yaz/yaz-util.h |    2 ++
 2 files changed, 45 insertions(+), 11 deletions(-)

diff --git a/include/yaz/mutex.h b/include/yaz/mutex.h
index 814b382..6ef4382 100644
--- a/include/yaz/mutex.h
+++ b/include/yaz/mutex.h
@@ -37,18 +37,50 @@
 
 YAZ_BEGIN_CDECL
 
-/** \brief NMEM/YAZ MUTEX opaque pointer */
+/** \brief YAZ MUTEX opaque pointer */
 typedef struct yaz_mutex *YAZ_MUTEX;
-/** \brief create Mutex */
-YAZ_EXPORT void yaz_mutex_create(YAZ_MUTEX *);
-/** \brief enter critical section / AKA lock */
-YAZ_EXPORT void yaz_mutex_enter(YAZ_MUTEX);
-/** \brief leave critical section / AKA unlock */
-YAZ_EXPORT void yaz_mutex_leave(YAZ_MUTEX);
-/** \brief destroy MUTEX */
-YAZ_EXPORT void yaz_mutex_destroy(YAZ_MUTEX *);
-/** \brief sets name of MUTEX for debugging purposes */
-void yaz_mutex_set_name(YAZ_MUTEX p, int log_level, const char *name);
+
+/** \brief create MUTEX
+    \param mutexp is pointer to MUTEX handle (*mutexp must be NULL)
+    
+    It is important that *mutexp is NULL. If not, yaz_mutex_create will
+    not modify the handle (assumes it is already created!)
+ */
+YAZ_EXPORT void yaz_mutex_create(YAZ_MUTEX *mutexp);
+
+/** \brief enter critical section / AKA lock
+    \param mutex MUTEX handle
+ */
+YAZ_EXPORT void yaz_mutex_enter(YAZ_MUTEX mutex);
+
+
+/** \brief leave critical section / AKA unlock
+    \param mutex MUTEX handle
+ */
+YAZ_EXPORT void yaz_mutex_leave(YAZ_MUTEX mutex);
+
+
+/** \brief destroy MUTEX
+    \param mutexp pointer to MUTEX handle
+
+    If *mutexp is NULL, then this function does nothing.
+ */
+YAZ_EXPORT void yaz_mutex_destroy(YAZ_MUTEX *mutexp);
+
+
+/** \brief sets name of MUTEX for debugging purposes
+    \param mutex MUTEX handle
+    \param log_level YAZ log level
+    \param name user-given name associated with MUTEX
+
+    If log_level != 0 and name != 0 this function will make yaz_mutex_enter
+    and yaz_mutex_leave print information for each invocation using yaz_log
+    with the level given. In particular when YAZ is compiled with pthreads,
+    yaz_mutex_enter will inform if a lock is not immediately acquired.
+    This function should be called after a MUTEX is created but before
+    it is used for locking.
+ */
+void yaz_mutex_set_name(YAZ_MUTEX mutex, int log_level, const char *name);
 
 YAZ_END_CDECL
 
diff --git a/include/yaz/yaz-util.h b/include/yaz/yaz-util.h
index 3ddeec5..b0bc26d 100644
--- a/include/yaz/yaz-util.h
+++ b/include/yaz/yaz-util.h
@@ -80,6 +80,8 @@
 
     Timing : \ref timing.h .
 
+    Locking: \ref mutex.h .
+
     \section queryparsers Query parsers
 
     PQF parsing: \ref pquery.h .
-- 
1.7.10.4