Add new mutex create where mutex attribute can be set

[yaz-moved-to-github.git] / include / yaz / mutex.h

diff --git a/include/yaz/mutex.h b/include/yaz/mutex.h
index 814b382..ff8babb 100644 (file)
--- a/include/yaz/mutex.h
+++ b/include/yaz/mutex.h
@@ -33,22 +33,110 @@
 #define YAZ_MUTEX_H
 
 #include <stddef.h>
+#include <time.h>
 #include <yaz/yconfig.h>
 
 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 YAZ condition opaque pointer */
+typedef struct yaz_cond *YAZ_COND;
+
+/** \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 create MUTEX with custom MUTEX flags
+    \param mutexp is pointer to MUTEX handle (*mutexp must be NULL)
+    \param attr is flags defined by PTHREAD_MUTEX_xxx
+
+    It is important that *mutexp is NULL. If not, yaz_mutex_create will
+    not modify the handle (assumes it is already created!)
+
+    This calls yax_mutex_create_attr(mutexp, PTHREAD_MUTEX_NORMAL)
+ */
+YAZ_EXPORT void yaz_mutex_create_attr(YAZ_MUTEX *mutexp, int flags);
+
+/** \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.
+ */
+YAZ_EXPORT
+void yaz_mutex_set_name(YAZ_MUTEX mutex, int log_level, const char *name);
+
+/** \brief creates condition variable
+    \param p reference to condition handle
+    
+    Upon successful completion *p holds the condition handle; *p = 0
+    on error.
+*/
+YAZ_EXPORT void yaz_cond_create(YAZ_COND *p);
+
+/** \brief destroys condition variable
+    \param p reference to condition handle
+    
+    Upon completion *p holds 0.
+*/
+YAZ_EXPORT
+void yaz_cond_destroy(YAZ_COND *p);
+
+struct timeval;
+
+/** \brief waits for condition
+    \param p condition variable handle
+    \param m mutex
+    \param abstime wait until this time; 0 for indefinite wait
+
+    Semantics like pthread_cond_wait.
+*/
+YAZ_EXPORT
+int yaz_cond_wait(YAZ_COND p, YAZ_MUTEX m, const struct timeval *abstime);
+
+/** \brief unblock one thread waiting for block
+    \param p condition variable handle
+*/
+YAZ_EXPORT
+int yaz_cond_signal(YAZ_COND p);
+
+/** \brief unblock all threads waiting for block
+    \param p condition variable handle
+*/
+YAZ_EXPORT
+int yaz_cond_broadcast(YAZ_COND p);
 
 YAZ_END_CDECL