From 79c68f7855e83d0a9c641dadb8a0a378cf343c92 Mon Sep 17 00:00:00 2001 From: Adam Dickmeiss 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