X-Git-Url: http://git.indexdata.com/?a=blobdiff_plain;f=include%2Fyaz%2Fmutex.h;h=6ef4382bfc0d6db97419c18c11fd4144560c70ee;hb=11bd8b21620d78c0399387a501ec2277e85a2f47;hp=67c614512dcf9a73caae5b597f569c779d0fca47;hpb=0836f7a70cff4b7a8edc2c2a2fd1b3cb2c6588cc;p=yaz-moved-to-github.git

diff --git a/include/yaz/mutex.h b/include/yaz/mutex.h
index 67c6145..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, 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