lock.h

Go to the documentation of this file.
00001 /*
00002  * Asterisk -- An open source telephony toolkit.
00003  *
00004  * Copyright (C) 1999 - 2010, Digium, Inc.
00005  *
00006  * Mark Spencer <markster@digium.com>
00007  *
00008  * See http://www.asterisk.org for more information about
00009  * the Asterisk project. Please do not directly contact
00010  * any of the maintainers of this project for assistance;
00011  * the project provides a web site, mailing lists and IRC
00012  * channels for your use.
00013  *
00014  * This program is free software, distributed under the terms of
00015  * the GNU General Public License Version 2. See the LICENSE file
00016  * at the top of the source tree.
00017  */
00018 
00019 /*! \file
00020  * \brief Asterisk locking-related definitions:
00021  * - ast_mutex_t, ast_rwlock_t and related functions;
00022  * - atomic arithmetic instructions;
00023  * - wrappers for channel locking.
00024  *
00025  * - See \ref LockDef
00026  */
00027 
00028 /*! \page LockDef Asterisk thread locking models
00029  *
00030  * This file provides different implementation of the functions,
00031  * depending on the platform, the use of DEBUG_THREADS, and the way
00032  * module-level mutexes are initialized.
00033  *
00034  *  - \b static: the mutex is assigned the value AST_MUTEX_INIT_VALUE
00035  *        this is done at compile time, and is the way used on Linux.
00036  *        This method is not applicable to all platforms e.g. when the
00037  *        initialization needs that some code is run.
00038  *
00039  *  - \b through constructors: for each mutex, a constructor function is
00040  *        defined, which then runs when the program (or the module)
00041  *        starts. The problem with this approach is that there is a
00042  *        lot of code duplication (a new block of code is created for
00043  *        each mutex). Also, it does not prevent a user from declaring
00044  *        a global mutex without going through the wrapper macros,
00045  *        so sane programming practices are still required.
00046  */
00047 
00048 #ifndef _ASTERISK_LOCK_H
00049 #define _ASTERISK_LOCK_H
00050 
00051 #include <pthread.h>
00052 #include <time.h>
00053 #include <sys/param.h>
00054 #ifdef HAVE_BKTR
00055 #include <execinfo.h>
00056 #endif
00057 
00058 #ifndef HAVE_PTHREAD_RWLOCK_TIMEDWRLOCK
00059 #include "asterisk/time.h"
00060 #endif
00061 
00062 #include "asterisk/backtrace.h"
00063 #include "asterisk/logger.h"
00064 #include "asterisk/compiler.h"
00065 
00066 #define AST_PTHREADT_NULL (pthread_t) -1
00067 #define AST_PTHREADT_STOP (pthread_t) -2
00068 
00069 #if (defined(SOLARIS) || defined(BSD))
00070 #define AST_MUTEX_INIT_W_CONSTRUCTORS
00071 #endif /* SOLARIS || BSD */
00072 
00073 /* Asterisk REQUIRES recursive (not error checking) mutexes
00074    and will not run without them. */
00075 #if defined(HAVE_PTHREAD_RECURSIVE_MUTEX_INITIALIZER_NP) && defined(HAVE_PTHREAD_MUTEX_RECURSIVE_NP)
00076 #define PTHREAD_MUTEX_INIT_VALUE PTHREAD_RECURSIVE_MUTEX_INITIALIZER_NP
00077 #define AST_MUTEX_KIND        PTHREAD_MUTEX_RECURSIVE_NP
00078 #else
00079 #define PTHREAD_MUTEX_INIT_VALUE PTHREAD_MUTEX_INITIALIZER
00080 #define AST_MUTEX_KIND        PTHREAD_MUTEX_RECURSIVE
00081 #endif /* PTHREAD_RECURSIVE_MUTEX_INITIALIZER_NP */
00082 
00083 #ifdef HAVE_PTHREAD_RWLOCK_INITIALIZER
00084 #define __AST_RWLOCK_INIT_VALUE     PTHREAD_RWLOCK_INITIALIZER
00085 #else  /* HAVE_PTHREAD_RWLOCK_INITIALIZER */
00086 #define __AST_RWLOCK_INIT_VALUE     {0}
00087 #endif /* HAVE_PTHREAD_RWLOCK_INITIALIZER */
00088 
00089 #ifdef HAVE_BKTR
00090 #define AST_LOCK_TRACK_INIT_VALUE { { NULL }, { 0 }, 0, { NULL }, { 0 }, {{{ 0 }}}, PTHREAD_MUTEX_INIT_VALUE }
00091 #else
00092 #define AST_LOCK_TRACK_INIT_VALUE { { NULL }, { 0 }, 0, { NULL }, { 0 }, PTHREAD_MUTEX_INIT_VALUE }
00093 #endif
00094 
00095 #define AST_MUTEX_INIT_VALUE { PTHREAD_MUTEX_INIT_VALUE, NULL, 1 }
00096 #define AST_MUTEX_INIT_VALUE_NOTRACKING { PTHREAD_MUTEX_INIT_VALUE, NULL, 0 }
00097 
00098 #define AST_RWLOCK_INIT_VALUE { __AST_RWLOCK_INIT_VALUE, NULL, 1 }
00099 #define AST_RWLOCK_INIT_VALUE_NOTRACKING { __AST_RWLOCK_INIT_VALUE, NULL, 0 }
00100 
00101 #define AST_MAX_REENTRANCY 10
00102 
00103 struct ast_channel;
00104 
00105 /*!
00106  * \brief Lock tracking information.
00107  *
00108  * \note Any changes to this struct MUST be reflected in the
00109  * lock.c:restore_lock_tracking() function.
00110  */
00111 struct ast_lock_track {
00112    const char *file[AST_MAX_REENTRANCY];
00113    int lineno[AST_MAX_REENTRANCY];
00114    int reentrancy;
00115    const char *func[AST_MAX_REENTRANCY];
00116    pthread_t thread[AST_MAX_REENTRANCY];
00117 #ifdef HAVE_BKTR
00118    struct ast_bt backtrace[AST_MAX_REENTRANCY];
00119 #endif
00120    pthread_mutex_t reentr_mutex;
00121 };
00122 
00123 /*! \brief Structure for mutex and tracking information.
00124  *
00125  * We have tracking information in this structure regardless of DEBUG_THREADS being enabled.
00126  * The information will just be ignored in the core if a module does not request it..
00127  */
00128 struct ast_mutex_info {
00129    pthread_mutex_t mutex;
00130    /*! Track which thread holds this mutex */
00131    struct ast_lock_track *track;
00132    unsigned int tracking:1;
00133 };
00134 
00135 /*! \brief Structure for rwlock and tracking information.
00136  *
00137  * We have tracking information in this structure regardless of DEBUG_THREADS being enabled.
00138  * The information will just be ignored in the core if a module does not request it..
00139  */
00140 struct ast_rwlock_info {
00141    pthread_rwlock_t lock;
00142    /*! Track which thread holds this lock */
00143    struct ast_lock_track *track;
00144    unsigned int tracking:1;
00145 };
00146 
00147 typedef struct ast_mutex_info ast_mutex_t;
00148 
00149 typedef struct ast_rwlock_info ast_rwlock_t;
00150 
00151 typedef pthread_cond_t ast_cond_t;
00152 
00153 int __ast_pthread_mutex_init(int tracking, const char *filename, int lineno, const char *func, const char *mutex_name, ast_mutex_t *t);
00154 int __ast_pthread_mutex_destroy(const char *filename, int lineno, const char *func, const char *mutex_name, ast_mutex_t *t);
00155 int __ast_pthread_mutex_lock(const char *filename, int lineno, const char *func, const char* mutex_name, ast_mutex_t *t);
00156 int __ast_pthread_mutex_trylock(const char *filename, int lineno, const char *func, const char* mutex_name, ast_mutex_t *t);
00157 int __ast_pthread_mutex_unlock(const char *filename, int lineno, const char *func, const char *mutex_name, ast_mutex_t *t);
00158 
00159 #define ast_mutex_init(pmutex)            __ast_pthread_mutex_init(1, __FILE__, __LINE__, __PRETTY_FUNCTION__, #pmutex, pmutex)
00160 #define ast_mutex_init_notracking(pmutex) __ast_pthread_mutex_init(0, __FILE__, __LINE__, __PRETTY_FUNCTION__, #pmutex, pmutex)
00161 #define ast_mutex_destroy(a)              __ast_pthread_mutex_destroy(__FILE__, __LINE__, __PRETTY_FUNCTION__, #a, a)
00162 #define ast_mutex_lock(a)                 __ast_pthread_mutex_lock(__FILE__, __LINE__, __PRETTY_FUNCTION__, #a, a)
00163 #define ast_mutex_unlock(a)               __ast_pthread_mutex_unlock(__FILE__, __LINE__, __PRETTY_FUNCTION__, #a, a)
00164 #define ast_mutex_trylock(a)              __ast_pthread_mutex_trylock(__FILE__, __LINE__, __PRETTY_FUNCTION__, #a, a)
00165 
00166 
00167 int __ast_cond_init(const char *filename, int lineno, const char *func, const char *cond_name, ast_cond_t *cond, pthread_condattr_t *cond_attr);
00168 int __ast_cond_signal(const char *filename, int lineno, const char *func, const char *cond_name, ast_cond_t *cond);
00169 int __ast_cond_broadcast(const char *filename, int lineno, const char *func, const char *cond_name, ast_cond_t *cond);
00170 int __ast_cond_destroy(const char *filename, int lineno, const char *func, const char *cond_name, ast_cond_t *cond);
00171 int __ast_cond_wait(const char *filename, int lineno, const char *func, const char *cond_name, const char *mutex_name, ast_cond_t *cond, ast_mutex_t *t);
00172 int __ast_cond_timedwait(const char *filename, int lineno, const char *func, const char *cond_name, const char *mutex_name, ast_cond_t *cond, ast_mutex_t *t, const struct timespec *abstime);
00173 
00174 #define ast_cond_init(cond, attr)             __ast_cond_init(__FILE__, __LINE__, __PRETTY_FUNCTION__, #cond, cond, attr)
00175 #define ast_cond_destroy(cond)                __ast_cond_destroy(__FILE__, __LINE__, __PRETTY_FUNCTION__, #cond, cond)
00176 #define ast_cond_signal(cond)                 __ast_cond_signal(__FILE__, __LINE__, __PRETTY_FUNCTION__, #cond, cond)
00177 #define ast_cond_broadcast(cond)              __ast_cond_broadcast(__FILE__, __LINE__, __PRETTY_FUNCTION__, #cond, cond)
00178 #define ast_cond_wait(cond, mutex)            __ast_cond_wait(__FILE__, __LINE__, __PRETTY_FUNCTION__, #cond, #mutex, cond, mutex)
00179 #define ast_cond_timedwait(cond, mutex, time) __ast_cond_timedwait(__FILE__, __LINE__, __PRETTY_FUNCTION__, #cond, #mutex, cond, mutex, time)
00180 
00181 
00182 int __ast_rwlock_init(int tracking, const char *filename, int lineno, const char *func, const char *rwlock_name, ast_rwlock_t *t);
00183 int __ast_rwlock_destroy(const char *filename, int lineno, const char *func, const char *rwlock_name, ast_rwlock_t *t);
00184 int __ast_rwlock_unlock(const char *filename, int lineno, const char *func, ast_rwlock_t *t, const char *name);
00185 int __ast_rwlock_rdlock(const char *filename, int lineno, const char *func, ast_rwlock_t *t, const char *name);
00186 int __ast_rwlock_wrlock(const char *filename, int lineno, const char *func, ast_rwlock_t *t, const char *name);
00187 int __ast_rwlock_timedrdlock(const char *filename, int lineno, const char *func, ast_rwlock_t *t, const char *name, const struct timespec *abs_timeout);
00188 int __ast_rwlock_timedwrlock(const char *filename, int lineno, const char *func, ast_rwlock_t *t, const char *name, const struct timespec *abs_timeout);
00189 int __ast_rwlock_tryrdlock(const char *filename, int lineno, const char *func, ast_rwlock_t *t, const char *name);
00190 int __ast_rwlock_trywrlock(const char *filename, int lineno, const char *func, ast_rwlock_t *t, const char *name);
00191 
00192 /*!
00193  * \brief wrapper for rwlock with tracking enabled
00194  * \return 0 on success, non zero for error
00195  * \since 1.6.1
00196  */
00197 #define ast_rwlock_init(rwlock)            __ast_rwlock_init(1, __FILE__, __LINE__, __PRETTY_FUNCTION__, #rwlock, rwlock)
00198 
00199 /*!
00200  * \brief wrapper for ast_rwlock_init with tracking disabled
00201  * \return 0 on success, non zero for error
00202  * \since 1.6.1
00203  */
00204 #define ast_rwlock_init_notracking(rwlock) __ast_rwlock_init(0, __FILE__, __LINE__, __PRETTY_FUNCTION__, #rwlock, rwlock)
00205 
00206 #define ast_rwlock_destroy(rwlock)         __ast_rwlock_destroy(__FILE__, __LINE__, __PRETTY_FUNCTION__, #rwlock, rwlock)
00207 #define ast_rwlock_unlock(a)               __ast_rwlock_unlock(__FILE__, __LINE__, __PRETTY_FUNCTION__, a, #a)
00208 #define ast_rwlock_rdlock(a)               __ast_rwlock_rdlock(__FILE__, __LINE__, __PRETTY_FUNCTION__, a, #a)
00209 #define ast_rwlock_wrlock(a)               __ast_rwlock_wrlock(__FILE__, __LINE__, __PRETTY_FUNCTION__, a, #a)
00210 #define ast_rwlock_tryrdlock(a)            __ast_rwlock_tryrdlock(__FILE__, __LINE__, __PRETTY_FUNCTION__, a, #a)
00211 #define ast_rwlock_trywrlock(a)            __ast_rwlock_trywrlock(__FILE__, __LINE__, __PRETTY_FUNCTION__, a, #a)
00212 #define ast_rwlock_timedrdlock(a, b)       __ast_rwlock_timedrdlock(__FILE__, __LINE__, __PRETTY_FUNCTION__, a, #a, b)
00213 #define ast_rwlock_timedwrlock(a, b)       __ast_rwlock_timedwrlock(__FILE__, __LINE__, __PRETTY_FUNCTION__, a, #a, b)
00214 
00215 #define  ROFFSET  ((lt->reentrancy > 0) ? (lt->reentrancy-1) : 0)
00216 
00217 #ifdef DEBUG_THREADS
00218 
00219 #define __ast_mutex_logger(...)  do { if (canlog) ast_log(LOG_ERROR, __VA_ARGS__); else fprintf(stderr, __VA_ARGS__); } while (0)
00220 
00221 #ifdef THREAD_CRASH
00222 #define DO_THREAD_CRASH do { *((int *)(0)) = 1; } while(0)
00223 #else
00224 #define DO_THREAD_CRASH do { } while (0)
00225 #endif
00226 
00227 #include <errno.h>
00228 
00229 enum ast_lock_type {
00230    AST_MUTEX,
00231    AST_RDLOCK,
00232    AST_WRLOCK,
00233 };
00234 
00235 /*!
00236  * \brief Store lock info for the current thread
00237  *
00238  * This function gets called in ast_mutex_lock() and ast_mutex_trylock() so
00239  * that information about this lock can be stored in this thread's
00240  * lock info struct.  The lock is marked as pending as the thread is waiting
00241  * on the lock.  ast_mark_lock_acquired() will mark it as held by this thread.
00242  */
00243 #if !defined(LOW_MEMORY)
00244 #ifdef HAVE_BKTR
00245 void ast_store_lock_info(enum ast_lock_type type, const char *filename,
00246    int line_num, const char *func, const char *lock_name, void *lock_addr, struct ast_bt *bt);
00247 #else
00248 void ast_store_lock_info(enum ast_lock_type type, const char *filename,
00249    int line_num, const char *func, const char *lock_name, void *lock_addr);
00250 #endif /* HAVE_BKTR */
00251 
00252 #else
00253 
00254 #ifdef HAVE_BKTR
00255 #define ast_store_lock_info(I,DONT,CARE,ABOUT,THE,PARAMETERS,BUD)
00256 #else
00257 #define ast_store_lock_info(I,DONT,CARE,ABOUT,THE,PARAMETERS)
00258 #endif /* HAVE_BKTR */
00259 #endif /* !defined(LOW_MEMORY) */
00260 
00261 /*!
00262  * \brief Mark the last lock as acquired
00263  */
00264 #if !defined(LOW_MEMORY)
00265 void ast_mark_lock_acquired(void *lock_addr);
00266 #else
00267 #define ast_mark_lock_acquired(ignore)
00268 #endif
00269 
00270 /*!
00271  * \brief Mark the last lock as failed (trylock)
00272  */
00273 #if !defined(LOW_MEMORY)
00274 void ast_mark_lock_failed(void *lock_addr);
00275 #else
00276 #define ast_mark_lock_failed(ignore)
00277 #endif
00278 
00279 /*!
00280  * \brief remove lock info for the current thread
00281  *
00282  * this gets called by ast_mutex_unlock so that information on the lock can
00283  * be removed from the current thread's lock info struct.
00284  */
00285 #if !defined(LOW_MEMORY)
00286 #ifdef HAVE_BKTR
00287 void ast_remove_lock_info(void *lock_addr, struct ast_bt *bt);
00288 #else
00289 void ast_remove_lock_info(void *lock_addr);
00290 #endif /* HAVE_BKTR */
00291 void ast_suspend_lock_info(void *lock_addr);
00292 void ast_restore_lock_info(void *lock_addr);
00293 #else
00294 #ifdef HAVE_BKTR
00295 #define ast_remove_lock_info(ignore,me)
00296 #else
00297 #define ast_remove_lock_info(ignore)
00298 #endif /* HAVE_BKTR */
00299 #define ast_suspend_lock_info(ignore);
00300 #define ast_restore_lock_info(ignore);
00301 #endif /* !defined(LOW_MEMORY) */
00302 
00303 /*!
00304  * \brief log info for the current lock with ast_log().
00305  *
00306  * this function would be mostly for debug. If you come across a lock
00307  * that is unexpectedly but momentarily locked, and you wonder who
00308  * are fighting with for the lock, this routine could be called, IF
00309  * you have the thread debugging stuff turned on.
00310  * \param this_lock_addr lock address to return lock information
00311  * \since 1.6.1
00312  */
00313 void ast_log_show_lock(void *this_lock_addr);
00314 
00315 /*!
00316  * \brief Generate a lock dump equivalent to "core show locks".
00317  *
00318  * The lock dump generated is generally too large to be output by a
00319  * single ast_verbose/log/debug/etc. call. Only ast_cli() handles it
00320  * properly without changing BUFSIZ in logger.c.
00321  *
00322  * Note: This must be ast_free()d when you're done with it.
00323  *
00324  * \retval An ast_str containing the lock dump
00325  * \retval NULL on error
00326  * \since 12
00327  */
00328 struct ast_str *ast_dump_locks(void);
00329 
00330 /*!
00331  * \brief retrieve lock info for the specified mutex
00332  *
00333  * this gets called during deadlock avoidance, so that the information may
00334  * be preserved as to what location originally acquired the lock.
00335  */
00336 #if !defined(LOW_MEMORY)
00337 int ast_find_lock_info(void *lock_addr, char *filename, size_t filename_size, int *lineno, char *func, size_t func_size, char *mutex_name, size_t mutex_name_size);
00338 #else
00339 #define ast_find_lock_info(a,b,c,d,e,f,g,h) -1
00340 #endif
00341 
00342 /*!
00343  * \brief Unlock a lock briefly
00344  *
00345  * used during deadlock avoidance, to preserve the original location where
00346  * a lock was originally acquired.
00347  */
00348 #define AO2_DEADLOCK_AVOIDANCE(obj) \
00349    do { \
00350       char __filename[80], __func[80], __mutex_name[80]; \
00351       int __lineno; \
00352       int __res = ast_find_lock_info(ao2_object_get_lockaddr(obj), __filename, sizeof(__filename), &__lineno, __func, sizeof(__func), __mutex_name, sizeof(__mutex_name)); \
00353       int __res2 = ao2_unlock(obj); \
00354       usleep(1); \
00355       if (__res < 0) { /* Could happen if the ao2 object does not have a mutex. */ \
00356          if (__res2) { \
00357             ast_log(LOG_WARNING, "Could not unlock ao2 object '%s': %s and no lock info found!  I will NOT try to relock.\n", #obj, strerror(__res2)); \
00358          } else { \
00359             ao2_lock(obj); \
00360          } \
00361       } else { \
00362          if (__res2) { \
00363             ast_log(LOG_WARNING, "Could not unlock ao2 object '%s': %s.  {{{Originally locked at %s line %d: (%s) '%s'}}}  I will NOT try to relock.\n", #obj, strerror(__res2), __filename, __lineno, __func, __mutex_name); \
00364          } else { \
00365             __ao2_lock(obj, AO2_LOCK_REQ_MUTEX, __filename, __func, __lineno, __mutex_name); \
00366          } \
00367       } \
00368    } while (0)
00369 
00370 #define CHANNEL_DEADLOCK_AVOIDANCE(chan) \
00371    do { \
00372       char __filename[80], __func[80], __mutex_name[80]; \
00373       int __lineno; \
00374       int __res = ast_find_lock_info(ao2_object_get_lockaddr(chan), __filename, sizeof(__filename), &__lineno, __func, sizeof(__func), __mutex_name, sizeof(__mutex_name)); \
00375       int __res2 = ast_channel_unlock(chan); \
00376       usleep(1); \
00377       if (__res < 0) { /* Shouldn't ever happen, but just in case... */ \
00378          if (__res2) { \
00379             ast_log(LOG_WARNING, "Could not unlock channel '%s': %s and no lock info found!  I will NOT try to relock.\n", #chan, strerror(__res2)); \
00380          } else { \
00381             ast_channel_lock(chan); \
00382          } \
00383       } else { \
00384          if (__res2) { \
00385             ast_log(LOG_WARNING, "Could not unlock channel '%s': %s.  {{{Originally locked at %s line %d: (%s) '%s'}}}  I will NOT try to relock.\n", #chan, strerror(__res2), __filename, __lineno, __func, __mutex_name); \
00386          } else { \
00387             __ao2_lock(chan, AO2_LOCK_REQ_MUTEX, __filename, __func, __lineno, __mutex_name); \
00388          } \
00389       } \
00390    } while (0)
00391 
00392 #define DEADLOCK_AVOIDANCE(lock) \
00393    do { \
00394       char __filename[80], __func[80], __mutex_name[80]; \
00395       int __lineno; \
00396       int __res = ast_find_lock_info(lock, __filename, sizeof(__filename), &__lineno, __func, sizeof(__func), __mutex_name, sizeof(__mutex_name)); \
00397       int __res2 = ast_mutex_unlock(lock); \
00398       usleep(1); \
00399       if (__res < 0) { /* Shouldn't ever happen, but just in case... */ \
00400          if (__res2 == 0) { \
00401             ast_mutex_lock(lock); \
00402          } else { \
00403             ast_log(LOG_WARNING, "Could not unlock mutex '%s': %s and no lock info found!  I will NOT try to relock.\n", #lock, strerror(__res2)); \
00404          } \
00405       } else { \
00406          if (__res2 == 0) { \
00407             __ast_pthread_mutex_lock(__filename, __lineno, __func, __mutex_name, lock); \
00408          } else { \
00409             ast_log(LOG_WARNING, "Could not unlock mutex '%s': %s.  {{{Originally locked at %s line %d: (%s) '%s'}}}  I will NOT try to relock.\n", #lock, strerror(__res2), __filename, __lineno, __func, __mutex_name); \
00410          } \
00411       } \
00412    } while (0)
00413 
00414 /*!
00415  * \brief Deadlock avoidance unlock
00416  *
00417  * In certain deadlock avoidance scenarios, there is more than one lock to be
00418  * unlocked and relocked.  Therefore, this pair of macros is provided for that
00419  * purpose.  Note that every DLA_UNLOCK _MUST_ be paired with a matching
00420  * DLA_LOCK.  The intent of this pair of macros is to be used around another
00421  * set of deadlock avoidance code, mainly CHANNEL_DEADLOCK_AVOIDANCE, as the
00422  * locking order specifies that we may safely lock a channel, followed by its
00423  * pvt, with no worries about a deadlock.  In any other scenario, this macro
00424  * may not be safe to use.
00425  */
00426 #define DLA_UNLOCK(lock) \
00427    do { \
00428       char __filename[80], __func[80], __mutex_name[80]; \
00429       int __lineno; \
00430       int __res = ast_find_lock_info(lock, __filename, sizeof(__filename), &__lineno, __func, sizeof(__func), __mutex_name, sizeof(__mutex_name)); \
00431       int __res2 = ast_mutex_unlock(lock);
00432 
00433 /*!
00434  * \brief Deadlock avoidance lock
00435  *
00436  * In certain deadlock avoidance scenarios, there is more than one lock to be
00437  * unlocked and relocked.  Therefore, this pair of macros is provided for that
00438  * purpose.  Note that every DLA_UNLOCK _MUST_ be paired with a matching
00439  * DLA_LOCK.  The intent of this pair of macros is to be used around another
00440  * set of deadlock avoidance code, mainly CHANNEL_DEADLOCK_AVOIDANCE, as the
00441  * locking order specifies that we may safely lock a channel, followed by its
00442  * pvt, with no worries about a deadlock.  In any other scenario, this macro
00443  * may not be safe to use.
00444  */
00445 #define DLA_LOCK(lock) \
00446       if (__res < 0) { /* Shouldn't ever happen, but just in case... */ \
00447          if (__res2) { \
00448             ast_log(LOG_WARNING, "Could not unlock mutex '%s': %s and no lock info found!  I will NOT try to relock.\n", #lock, strerror(__res2)); \
00449          } else { \
00450             ast_mutex_lock(lock); \
00451          } \
00452       } else { \
00453          if (__res2) { \
00454             ast_log(LOG_WARNING, "Could not unlock mutex '%s': %s.  {{{Originally locked at %s line %d: (%s) '%s'}}}  I will NOT try to relock.\n", #lock, strerror(__res2), __filename, __lineno, __func, __mutex_name); \
00455          } else { \
00456             __ast_pthread_mutex_lock(__filename, __lineno, __func, __mutex_name, lock); \
00457          } \
00458       } \
00459    } while (0)
00460 
00461 static inline void ast_reentrancy_lock(struct ast_lock_track *lt)
00462 {
00463    int res;
00464    if ((res = pthread_mutex_lock(&lt->reentr_mutex))) {
00465       fprintf(stderr, "ast_reentrancy_lock failed: '%s' (%d)\n", strerror(res), res);
00466 #if defined(DO_CRASH) || defined(THREAD_CRASH)
00467       abort();
00468 #endif
00469    }
00470 }
00471 
00472 static inline void ast_reentrancy_unlock(struct ast_lock_track *lt)
00473 {
00474    int res;
00475    if ((res = pthread_mutex_unlock(&lt->reentr_mutex))) {
00476       fprintf(stderr, "ast_reentrancy_unlock failed: '%s' (%d)\n", strerror(res), res);
00477 #if defined(DO_CRASH) || defined(THREAD_CRASH)
00478       abort();
00479 #endif
00480    }
00481 }
00482 
00483 #else /* !DEBUG_THREADS */
00484 
00485 #define AO2_DEADLOCK_AVOIDANCE(obj) \
00486    ao2_unlock(obj); \
00487    usleep(1); \
00488    ao2_lock(obj);
00489 
00490 #define CHANNEL_DEADLOCK_AVOIDANCE(chan) \
00491    ast_channel_unlock(chan); \
00492    usleep(1); \
00493    ast_channel_lock(chan);
00494 
00495 #define DEADLOCK_AVOIDANCE(lock) \
00496    do { \
00497       int __res; \
00498       if (!(__res = ast_mutex_unlock(lock))) { \
00499          usleep(1); \
00500          ast_mutex_lock(lock); \
00501       } else { \
00502          ast_log(LOG_WARNING, "Failed to unlock mutex '%s' (%s).  I will NOT try to relock. {{{ THIS IS A BUG. }}}\n", #lock, strerror(__res)); \
00503       } \
00504    } while (0)
00505 
00506 #define DLA_UNLOCK(lock) ast_mutex_unlock(lock)
00507 
00508 #define DLA_LOCK(lock) ast_mutex_lock(lock)
00509 
00510 #endif /* !DEBUG_THREADS */
00511 
00512 #if defined(AST_MUTEX_INIT_W_CONSTRUCTORS)
00513 /*
00514  * If AST_MUTEX_INIT_W_CONSTRUCTORS is defined, use file scope constructors
00515  * and destructors to create/destroy global mutexes.
00516  */
00517 #define __AST_MUTEX_DEFINE(scope, mutex, init_val, track)   \
00518    scope ast_mutex_t mutex = init_val;       \
00519 static void  __attribute__((constructor)) init_##mutex(void)   \
00520 {                       \
00521    if (track)                 \
00522       ast_mutex_init(&mutex);          \
00523    else                    \
00524       ast_mutex_init_notracking(&mutex);     \
00525 }                       \
00526                         \
00527 static void  __attribute__((destructor)) fini_##mutex(void) \
00528 {                       \
00529    ast_mutex_destroy(&mutex);          \
00530 }
00531 #else /* !AST_MUTEX_INIT_W_CONSTRUCTORS */
00532 /* By default, use static initialization of mutexes. */
00533 #define __AST_MUTEX_DEFINE(scope, mutex, init_val, track) scope ast_mutex_t mutex = init_val
00534 #endif /* AST_MUTEX_INIT_W_CONSTRUCTORS */
00535 
00536 #define AST_MUTEX_DEFINE_STATIC(mutex) __AST_MUTEX_DEFINE(static, mutex, AST_MUTEX_INIT_VALUE, 1)
00537 #define AST_MUTEX_DEFINE_STATIC_NOTRACKING(mutex) __AST_MUTEX_DEFINE(static, mutex, AST_MUTEX_INIT_VALUE_NOTRACKING, 0)
00538 
00539 
00540 /* Statically declared read/write locks */
00541 #ifdef AST_MUTEX_INIT_W_CONSTRUCTORS
00542 #define __AST_RWLOCK_DEFINE(scope, rwlock, init_val, track) \
00543         scope ast_rwlock_t rwlock = init_val; \
00544 static void  __attribute__((constructor)) init_##rwlock(void) \
00545 { \
00546    if (track) \
00547          ast_rwlock_init(&rwlock); \
00548    else \
00549       ast_rwlock_init_notracking(&rwlock); \
00550 } \
00551 static void  __attribute__((destructor)) fini_##rwlock(void) \
00552 { \
00553         ast_rwlock_destroy(&rwlock); \
00554 }
00555 #else
00556 #define __AST_RWLOCK_DEFINE(scope, rwlock, init_val, track) scope ast_rwlock_t rwlock = init_val
00557 #endif
00558 
00559 #define AST_RWLOCK_DEFINE_STATIC(rwlock) __AST_RWLOCK_DEFINE(static, rwlock, AST_RWLOCK_INIT_VALUE, 1)
00560 #define AST_RWLOCK_DEFINE_STATIC_NOTRACKING(rwlock) __AST_RWLOCK_DEFINE(static, rwlock, AST_RWLOCK_INIT_VALUE_NOTRACKING, 0)
00561 
00562 /*!
00563  * \brief Scoped Locks
00564  *
00565  * Scoped locks provide a way to use RAII locks. In other words,
00566  * declaration of a scoped lock will automatically define and lock
00567  * the lock. When the lock goes out of scope, it will automatically
00568  * be unlocked.
00569  *
00570  * \code
00571  * int some_function(struct ast_channel *chan)
00572  * {
00573  *     SCOPED_LOCK(lock, chan, ast_channel_lock, ast_channel_unlock);
00574  *
00575  *     if (!strcmp(ast_channel_name(chan, "foo")) {
00576  *         return 0;
00577  *     }
00578  *
00579  *     return -1;
00580  * }
00581  * \endcode
00582  *
00583  * In the above example, neither return path requires explicit unlocking
00584  * of the channel.
00585  *
00586  * \note
00587  * Care should be taken when using SCOPED_LOCKS in conjunction with ao2 objects.
00588  * ao2 objects should be unlocked before they are unreffed. Since SCOPED_LOCK runs
00589  * once the variable goes out of scope, this can easily lead to situations where the
00590  * variable gets unlocked after it is unreffed.
00591  *
00592  * \param varname The unique name to give to the scoped lock. You are not likely to reference
00593  * this outside of the SCOPED_LOCK invocation.
00594  * \param lock The variable to lock. This can be anything that can be passed to a locking
00595  * or unlocking function.
00596  * \param lockfunc The function to call to lock the lock
00597  * \param unlockfunc The function to call to unlock the lock
00598  */
00599 #define SCOPED_LOCK(varname, lock, lockfunc, unlockfunc) \
00600    RAII_VAR(typeof((lock)), varname, ({lockfunc((lock)); (lock); }), unlockfunc)
00601 
00602 /*!
00603  * \brief scoped lock specialization for mutexes
00604  */
00605 #define SCOPED_MUTEX(varname, lock) SCOPED_LOCK(varname, (lock), ast_mutex_lock, ast_mutex_unlock)
00606 
00607 /*!
00608  * \brief scoped lock specialization for read locks
00609  */
00610 #define SCOPED_RDLOCK(varname, lock) SCOPED_LOCK(varname, (lock), ast_rwlock_rdlock, ast_rwlock_unlock)
00611 
00612 /*!
00613  * \brief scoped lock specialization for write locks
00614  */
00615 #define SCOPED_WRLOCK(varname, lock) SCOPED_LOCK(varname, (lock), ast_rwlock_wrlock, ast_rwlock_unlock)
00616 
00617 /*!
00618  * \brief scoped lock specialization for ao2 mutexes.
00619  */
00620 #define SCOPED_AO2LOCK(varname, obj) SCOPED_LOCK(varname, (obj), ao2_lock, ao2_unlock)
00621 
00622 /*!
00623  * \brief scoped lock specialization for ao2 read locks.
00624  */
00625 #define SCOPED_AO2RDLOCK(varname, obj) SCOPED_LOCK(varname, (obj), ao2_rdlock, ao2_unlock)
00626 
00627 /*!
00628  * \brief scoped lock specialization for ao2 write locks.
00629  */
00630 #define SCOPED_AO2WRLOCK(varname, obj) SCOPED_LOCK(varname, (obj), ao2_wrlock, ao2_unlock)
00631 
00632 /*!
00633  * \brief scoped lock specialization for channels.
00634  */
00635 #define SCOPED_CHANNELLOCK(varname, chan) SCOPED_LOCK(varname, (chan), ast_channel_lock, ast_channel_unlock)
00636 
00637 #ifndef __CYGWIN__   /* temporary disabled for cygwin */
00638 #define pthread_mutex_t    use_ast_mutex_t_instead_of_pthread_mutex_t
00639 #define pthread_cond_t     use_ast_cond_t_instead_of_pthread_cond_t
00640 #endif
00641 #define pthread_mutex_lock use_ast_mutex_lock_instead_of_pthread_mutex_lock
00642 #define pthread_mutex_unlock  use_ast_mutex_unlock_instead_of_pthread_mutex_unlock
00643 #define pthread_mutex_trylock use_ast_mutex_trylock_instead_of_pthread_mutex_trylock
00644 #define pthread_mutex_init use_ast_mutex_init_instead_of_pthread_mutex_init
00645 #define pthread_mutex_destroy use_ast_mutex_destroy_instead_of_pthread_mutex_destroy
00646 #define pthread_cond_init  use_ast_cond_init_instead_of_pthread_cond_init
00647 #define pthread_cond_destroy  use_ast_cond_destroy_instead_of_pthread_cond_destroy
00648 #define pthread_cond_signal   use_ast_cond_signal_instead_of_pthread_cond_signal
00649 #define pthread_cond_broadcast   use_ast_cond_broadcast_instead_of_pthread_cond_broadcast
00650 #define pthread_cond_wait  use_ast_cond_wait_instead_of_pthread_cond_wait
00651 #define pthread_cond_timedwait   use_ast_cond_timedwait_instead_of_pthread_cond_timedwait
00652 
00653 #define AST_MUTEX_INITIALIZER __use_AST_MUTEX_DEFINE_STATIC_rather_than_AST_MUTEX_INITIALIZER__
00654 
00655 #define gethostbyname __gethostbyname__is__not__reentrant__use__ast_gethostbyname__instead__
00656 
00657 #ifndef __linux__
00658 #define pthread_create __use_ast_pthread_create_instead__
00659 #endif
00660 
00661 /*
00662  * Support for atomic instructions.
00663  * For platforms that have it, use the native cpu instruction to
00664  * implement them. For other platforms, resort to a 'slow' version
00665  * (defined in utils.c) that protects the atomic instruction with
00666  * a single lock.
00667  * The slow versions is always available, for testing purposes,
00668  * as ast_atomic_fetchadd_int_slow()
00669  */
00670 
00671 int ast_atomic_fetchadd_int_slow(volatile int *p, int v);
00672 
00673 #include "asterisk/inline_api.h"
00674 
00675 #if defined(HAVE_OSX_ATOMICS)
00676 #include "libkern/OSAtomic.h"
00677 #endif
00678 
00679 /*! \brief Atomically add v to *p and return * the previous value of *p.
00680  * This can be used to handle reference counts, and the return value
00681  * can be used to generate unique identifiers.
00682  */
00683 
00684 #if defined(HAVE_GCC_ATOMICS)
00685 AST_INLINE_API(int ast_atomic_fetchadd_int(volatile int *p, int v),
00686 {
00687    return __sync_fetch_and_add(p, v);
00688 })
00689 #elif defined(HAVE_OSX_ATOMICS) && (SIZEOF_INT == 4)
00690 AST_INLINE_API(int ast_atomic_fetchadd_int(volatile int *p, int v),
00691 {
00692    return OSAtomicAdd32(v, (int32_t *) p) - v;
00693 })
00694 #elif defined(HAVE_OSX_ATOMICS) && (SIZEOF_INT == 8)
00695 AST_INLINE_API(int ast_atomic_fetchadd_int(volatile int *p, int v),
00696 {
00697    return OSAtomicAdd64(v, (int64_t *) p) - v;
00698 })
00699 #elif defined (__i386__) || defined(__x86_64__)
00700 #ifdef sun
00701 AST_INLINE_API(int ast_atomic_fetchadd_int(volatile int *p, int v),
00702 {
00703    __asm __volatile (
00704    "       lock;  xaddl   %0, %1 ;        "
00705    : "+r" (v),                     /* 0 (result) */
00706      "=m" (*p)                     /* 1 */
00707    : "m" (*p));                    /* 2 */
00708    return (v);
00709 })
00710 #else /* ifndef sun */
00711 AST_INLINE_API(int ast_atomic_fetchadd_int(volatile int *p, int v),
00712 {
00713    __asm __volatile (
00714    "       lock   xaddl   %0, %1 ;        "
00715    : "+r" (v),                     /* 0 (result) */
00716      "=m" (*p)                     /* 1 */
00717    : "m" (*p));                    /* 2 */
00718    return (v);
00719 })
00720 #endif
00721 #else   /* low performance version in utils.c */
00722 AST_INLINE_API(int ast_atomic_fetchadd_int(volatile int *p, int v),
00723 {
00724    return ast_atomic_fetchadd_int_slow(p, v);
00725 })
00726 #endif
00727 
00728 /*! \brief decrement *p by 1 and return true if the variable has reached 0.
00729  * Useful e.g. to check if a refcount has reached 0.
00730  */
00731 #if defined(HAVE_GCC_ATOMICS)
00732 AST_INLINE_API(int ast_atomic_dec_and_test(volatile int *p),
00733 {
00734    return __sync_sub_and_fetch(p, 1) == 0;
00735 })
00736 #elif defined(HAVE_OSX_ATOMICS) && (SIZEOF_INT == 4)
00737 AST_INLINE_API(int ast_atomic_dec_and_test(volatile int *p),
00738 {
00739    return OSAtomicAdd32( -1, (int32_t *) p) == 0;
00740 })
00741 #elif defined(HAVE_OSX_ATOMICS) && (SIZEOF_INT == 8)
00742 AST_INLINE_API(int ast_atomic_dec_and_test(volatile int *p),
00743 {
00744    return OSAtomicAdd64( -1, (int64_t *) p) == 0;
00745 })
00746 #else
00747 AST_INLINE_API(int ast_atomic_dec_and_test(volatile int *p),
00748 {
00749    int a = ast_atomic_fetchadd_int(p, -1);
00750    return a == 1; /* true if the value is 0 now (so it was 1 previously) */
00751 })
00752 #endif
00753 
00754 #endif /* _ASTERISK_LOCK_H */

Generated on Thu Apr 16 06:27:38 2015 for Asterisk - The Open Source Telephony Project by  doxygen 1.5.6