X-Git-Url: http://git.indexdata.com/?p=yaz-moved-to-github.git;a=blobdiff_plain;f=include%2Fyaz%2Fmutex.h;h=6ef4382bfc0d6db97419c18c11fd4144560c70ee;hp=814b3821ce82c92e24646ab4c853e938a2089579;hb=79c68f7855e83d0a9c641dadb8a0a378cf343c92;hpb=83bf5a83b9296d6fe16e55d2c54209c35d2fa20b

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