CLI: Create ast_cli_completion_vector.
[asterisk/asterisk.git] / include / asterisk / lock.h
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 1999 - 2010, Digium, Inc.
5  *
6  * Mark Spencer <markster@digium.com>
7  *
8  * See http://www.asterisk.org for more information about
9  * the Asterisk project. Please do not directly contact
10  * any of the maintainers of this project for assistance;
11  * the project provides a web site, mailing lists and IRC
12  * channels for your use.
13  *
14  * This program is free software, distributed under the terms of
15  * the GNU General Public License Version 2. See the LICENSE file
16  * at the top of the source tree.
17  */
18
19 /*! \file
20  * \brief Asterisk locking-related definitions:
21  * - ast_mutex_t, ast_rwlock_t and related functions;
22  * - atomic arithmetic instructions;
23  * - wrappers for channel locking.
24  *
25  * - See \ref LockDef
26  */
27
28 /*! \page LockDef Asterisk thread locking models
29  *
30  * This file provides different implementation of the functions,
31  * depending on the platform, the use of DEBUG_THREADS, and the way
32  * module-level mutexes are initialized.
33  *
34  *  - \b static: the mutex is assigned the value AST_MUTEX_INIT_VALUE
35  *        this is done at compile time, and is the way used on Linux.
36  *        This method is not applicable to all platforms e.g. when the
37  *        initialization needs that some code is run.
38  *
39  *  - \b through constructors: for each mutex, a constructor function is
40  *        defined, which then runs when the program (or the module)
41  *        starts. The problem with this approach is that there is a
42  *        lot of code duplication (a new block of code is created for
43  *        each mutex). Also, it does not prevent a user from declaring
44  *        a global mutex without going through the wrapper macros,
45  *        so sane programming practices are still required.
46  */
47
48 #ifndef _ASTERISK_LOCK_H
49 #define _ASTERISK_LOCK_H
50
51 #include <pthread.h>
52 #include <time.h>
53 #include <sys/param.h>
54 #ifdef HAVE_BKTR
55 #include <execinfo.h>
56 #endif
57
58 #ifndef HAVE_PTHREAD_RWLOCK_TIMEDWRLOCK
59 #include "asterisk/time.h"
60 #endif
61
62 #include "asterisk/backtrace.h"
63 #include "asterisk/logger.h"
64 #include "asterisk/compiler.h"
65
66 #define AST_PTHREADT_NULL (pthread_t) -1
67 #define AST_PTHREADT_STOP (pthread_t) -2
68
69 #if (defined(SOLARIS) || defined(BSD))
70 #define AST_MUTEX_INIT_W_CONSTRUCTORS
71 #endif /* SOLARIS || BSD */
72
73 /* Asterisk REQUIRES recursive (not error checking) mutexes
74    and will not run without them. */
75 #if defined(HAVE_PTHREAD_RECURSIVE_MUTEX_INITIALIZER_NP) && defined(HAVE_PTHREAD_MUTEX_RECURSIVE_NP)
76 #define PTHREAD_MUTEX_INIT_VALUE        PTHREAD_RECURSIVE_MUTEX_INITIALIZER_NP
77 #define AST_MUTEX_KIND                  PTHREAD_MUTEX_RECURSIVE_NP
78 #else
79 #define PTHREAD_MUTEX_INIT_VALUE        PTHREAD_MUTEX_INITIALIZER
80 #define AST_MUTEX_KIND                  PTHREAD_MUTEX_RECURSIVE
81 #endif /* PTHREAD_RECURSIVE_MUTEX_INITIALIZER_NP */
82
83 #ifdef HAVE_PTHREAD_RWLOCK_INITIALIZER
84 #define __AST_RWLOCK_INIT_VALUE         PTHREAD_RWLOCK_INITIALIZER
85 #else  /* HAVE_PTHREAD_RWLOCK_INITIALIZER */
86 #define __AST_RWLOCK_INIT_VALUE         {0}
87 #endif /* HAVE_PTHREAD_RWLOCK_INITIALIZER */
88
89 #ifdef HAVE_BKTR
90 #define AST_LOCK_TRACK_INIT_VALUE { { NULL }, { 0 }, 0, { NULL }, { 0 }, {{{ 0 }}}, PTHREAD_MUTEX_INIT_VALUE }
91 #else
92 #define AST_LOCK_TRACK_INIT_VALUE { { NULL }, { 0 }, 0, { NULL }, { 0 }, PTHREAD_MUTEX_INIT_VALUE }
93 #endif
94
95 #define AST_MUTEX_INIT_VALUE { PTHREAD_MUTEX_INIT_VALUE, NULL, 1 }
96 #define AST_MUTEX_INIT_VALUE_NOTRACKING { PTHREAD_MUTEX_INIT_VALUE, NULL, 0 }
97
98 #define AST_RWLOCK_INIT_VALUE { __AST_RWLOCK_INIT_VALUE, NULL, 1 }
99 #define AST_RWLOCK_INIT_VALUE_NOTRACKING { __AST_RWLOCK_INIT_VALUE, NULL, 0 }
100
101 #define AST_MAX_REENTRANCY 10
102
103 struct ast_channel;
104
105 /*!
106  * \brief Lock tracking information.
107  *
108  * \note Any changes to this struct MUST be reflected in the
109  * lock.c:restore_lock_tracking() function.
110  */
111 struct ast_lock_track {
112         const char *file[AST_MAX_REENTRANCY];
113         int lineno[AST_MAX_REENTRANCY];
114         int reentrancy;
115         const char *func[AST_MAX_REENTRANCY];
116         pthread_t thread_id[AST_MAX_REENTRANCY];
117 #ifdef HAVE_BKTR
118         struct ast_bt backtrace[AST_MAX_REENTRANCY];
119 #endif
120         pthread_mutex_t reentr_mutex;
121 };
122
123 /*! \brief Structure for mutex and tracking information.
124  *
125  * We have tracking information in this structure regardless of DEBUG_THREADS being enabled.
126  * The information will just be ignored in the core if a module does not request it..
127  */
128 struct ast_mutex_info {
129         pthread_mutex_t mutex;
130         /*! Track which thread holds this mutex */
131         struct ast_lock_track *track;
132         unsigned int tracking:1;
133 };
134
135 /*! \brief Structure for rwlock and tracking information.
136  *
137  * We have tracking information in this structure regardless of DEBUG_THREADS being enabled.
138  * The information will just be ignored in the core if a module does not request it..
139  */
140 struct ast_rwlock_info {
141         pthread_rwlock_t lock;
142         /*! Track which thread holds this lock */
143         struct ast_lock_track *track;
144         unsigned int tracking:1;
145 };
146
147 typedef struct ast_mutex_info ast_mutex_t;
148
149 typedef struct ast_rwlock_info ast_rwlock_t;
150
151 typedef pthread_cond_t ast_cond_t;
152
153 int __ast_pthread_mutex_init(int tracking, const char *filename, int lineno, const char *func, const char *mutex_name, ast_mutex_t *t);
154 int __ast_pthread_mutex_destroy(const char *filename, int lineno, const char *func, const char *mutex_name, ast_mutex_t *t);
155 int __ast_pthread_mutex_lock(const char *filename, int lineno, const char *func, const char* mutex_name, ast_mutex_t *t);
156 int __ast_pthread_mutex_trylock(const char *filename, int lineno, const char *func, const char* mutex_name, ast_mutex_t *t);
157 int __ast_pthread_mutex_unlock(const char *filename, int lineno, const char *func, const char *mutex_name, ast_mutex_t *t);
158
159 #define ast_mutex_init(pmutex)            __ast_pthread_mutex_init(1, __FILE__, __LINE__, __PRETTY_FUNCTION__, #pmutex, pmutex)
160 #define ast_mutex_init_notracking(pmutex) __ast_pthread_mutex_init(0, __FILE__, __LINE__, __PRETTY_FUNCTION__, #pmutex, pmutex)
161 #define ast_mutex_destroy(a)              __ast_pthread_mutex_destroy(__FILE__, __LINE__, __PRETTY_FUNCTION__, #a, a)
162 #define ast_mutex_lock(a)                 __ast_pthread_mutex_lock(__FILE__, __LINE__, __PRETTY_FUNCTION__, #a, a)
163 #define ast_mutex_unlock(a)               __ast_pthread_mutex_unlock(__FILE__, __LINE__, __PRETTY_FUNCTION__, #a, a)
164 #define ast_mutex_trylock(a)              __ast_pthread_mutex_trylock(__FILE__, __LINE__, __PRETTY_FUNCTION__, #a, a)
165
166
167 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);
168 int __ast_cond_signal(const char *filename, int lineno, const char *func, const char *cond_name, ast_cond_t *cond);
169 int __ast_cond_broadcast(const char *filename, int lineno, const char *func, const char *cond_name, ast_cond_t *cond);
170 int __ast_cond_destroy(const char *filename, int lineno, const char *func, const char *cond_name, ast_cond_t *cond);
171 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);
172 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);
173
174 #define ast_cond_init(cond, attr)             __ast_cond_init(__FILE__, __LINE__, __PRETTY_FUNCTION__, #cond, cond, attr)
175 #define ast_cond_destroy(cond)                __ast_cond_destroy(__FILE__, __LINE__, __PRETTY_FUNCTION__, #cond, cond)
176 #define ast_cond_signal(cond)                 __ast_cond_signal(__FILE__, __LINE__, __PRETTY_FUNCTION__, #cond, cond)
177 #define ast_cond_broadcast(cond)              __ast_cond_broadcast(__FILE__, __LINE__, __PRETTY_FUNCTION__, #cond, cond)
178 #define ast_cond_wait(cond, mutex)            __ast_cond_wait(__FILE__, __LINE__, __PRETTY_FUNCTION__, #cond, #mutex, cond, mutex)
179 #define ast_cond_timedwait(cond, mutex, time) __ast_cond_timedwait(__FILE__, __LINE__, __PRETTY_FUNCTION__, #cond, #mutex, cond, mutex, time)
180
181
182 int __ast_rwlock_init(int tracking, const char *filename, int lineno, const char *func, const char *rwlock_name, ast_rwlock_t *t);
183 int __ast_rwlock_destroy(const char *filename, int lineno, const char *func, const char *rwlock_name, ast_rwlock_t *t);
184 int __ast_rwlock_unlock(const char *filename, int lineno, const char *func, ast_rwlock_t *t, const char *name);
185 int __ast_rwlock_rdlock(const char *filename, int lineno, const char *func, ast_rwlock_t *t, const char *name);
186 int __ast_rwlock_wrlock(const char *filename, int lineno, const char *func, ast_rwlock_t *t, const char *name);
187 int __ast_rwlock_timedrdlock(const char *filename, int lineno, const char *func, ast_rwlock_t *t, const char *name, const struct timespec *abs_timeout);
188 int __ast_rwlock_timedwrlock(const char *filename, int lineno, const char *func, ast_rwlock_t *t, const char *name, const struct timespec *abs_timeout);
189 int __ast_rwlock_tryrdlock(const char *filename, int lineno, const char *func, ast_rwlock_t *t, const char *name);
190 int __ast_rwlock_trywrlock(const char *filename, int lineno, const char *func, ast_rwlock_t *t, const char *name);
191
192 /*!
193  * \brief wrapper for rwlock with tracking enabled
194  * \return 0 on success, non zero for error
195  * \since 1.6.1
196  */
197 #define ast_rwlock_init(rwlock)            __ast_rwlock_init(1, __FILE__, __LINE__, __PRETTY_FUNCTION__, #rwlock, rwlock)
198
199 /*!
200  * \brief wrapper for ast_rwlock_init with tracking disabled
201  * \return 0 on success, non zero for error
202  * \since 1.6.1
203  */
204 #define ast_rwlock_init_notracking(rwlock) __ast_rwlock_init(0, __FILE__, __LINE__, __PRETTY_FUNCTION__, #rwlock, rwlock)
205
206 #define ast_rwlock_destroy(rwlock)         __ast_rwlock_destroy(__FILE__, __LINE__, __PRETTY_FUNCTION__, #rwlock, rwlock)
207 #define ast_rwlock_unlock(a)               __ast_rwlock_unlock(__FILE__, __LINE__, __PRETTY_FUNCTION__, a, #a)
208 #define ast_rwlock_rdlock(a)               __ast_rwlock_rdlock(__FILE__, __LINE__, __PRETTY_FUNCTION__, a, #a)
209 #define ast_rwlock_wrlock(a)               __ast_rwlock_wrlock(__FILE__, __LINE__, __PRETTY_FUNCTION__, a, #a)
210 #define ast_rwlock_tryrdlock(a)            __ast_rwlock_tryrdlock(__FILE__, __LINE__, __PRETTY_FUNCTION__, a, #a)
211 #define ast_rwlock_trywrlock(a)            __ast_rwlock_trywrlock(__FILE__, __LINE__, __PRETTY_FUNCTION__, a, #a)
212 #define ast_rwlock_timedrdlock(a, b)       __ast_rwlock_timedrdlock(__FILE__, __LINE__, __PRETTY_FUNCTION__, a, #a, b)
213 #define ast_rwlock_timedwrlock(a, b)       __ast_rwlock_timedwrlock(__FILE__, __LINE__, __PRETTY_FUNCTION__, a, #a, b)
214
215 #define ROFFSET ((lt->reentrancy > 0) ? (lt->reentrancy-1) : 0)
216
217 #ifdef DEBUG_THREADS
218
219 #define __ast_mutex_logger(...)  do { if (canlog) ast_log(LOG_ERROR, __VA_ARGS__); else fprintf(stderr, __VA_ARGS__); } while (0)
220
221 #ifdef THREAD_CRASH
222 #define DO_THREAD_CRASH do { *((int *)(0)) = 1; } while(0)
223 #else
224 #define DO_THREAD_CRASH do { } while (0)
225 #endif
226
227 #include <errno.h>
228
229 enum ast_lock_type {
230         AST_MUTEX,
231         AST_RDLOCK,
232         AST_WRLOCK,
233 };
234
235 /*!
236  * \brief Store lock info for the current thread
237  *
238  * This function gets called in ast_mutex_lock() and ast_mutex_trylock() so
239  * that information about this lock can be stored in this thread's
240  * lock info struct.  The lock is marked as pending as the thread is waiting
241  * on the lock.  ast_mark_lock_acquired() will mark it as held by this thread.
242  */
243 void ast_store_lock_info(enum ast_lock_type type, const char *filename,
244         int line_num, const char *func, const char *lock_name, void *lock_addr, struct ast_bt *bt);
245
246 /*!
247  * \brief Mark the last lock as acquired
248  */
249 void ast_mark_lock_acquired(void *lock_addr);
250
251 /*!
252  * \brief Mark the last lock as failed (trylock)
253  */
254 void ast_mark_lock_failed(void *lock_addr);
255
256 /*!
257  * \brief remove lock info for the current thread
258  *
259  * this gets called by ast_mutex_unlock so that information on the lock can
260  * be removed from the current thread's lock info struct.
261  */
262 void ast_remove_lock_info(void *lock_addr, struct ast_bt *bt);
263 void ast_suspend_lock_info(void *lock_addr);
264 void ast_restore_lock_info(void *lock_addr);
265
266 /*!
267  * \brief log info for the current lock with ast_log().
268  *
269  * this function would be mostly for debug. If you come across a lock
270  * that is unexpectedly but momentarily locked, and you wonder who
271  * are fighting with for the lock, this routine could be called, IF
272  * you have the thread debugging stuff turned on.
273  * \param this_lock_addr lock address to return lock information
274  * \since 1.6.1
275  */
276 void ast_log_show_lock(void *this_lock_addr);
277
278 /*!
279  * \brief Generate a lock dump equivalent to "core show locks".
280  *
281  * The lock dump generated is generally too large to be output by a
282  * single ast_verbose/log/debug/etc. call. Only ast_cli() handles it
283  * properly without changing BUFSIZ in logger.c.
284  *
285  * Note: This must be ast_free()d when you're done with it.
286  *
287  * \retval An ast_str containing the lock dump
288  * \retval NULL on error
289  * \since 12
290  */
291 struct ast_str *ast_dump_locks(void);
292
293 /*!
294  * \brief retrieve lock info for the specified mutex
295  *
296  * this gets called during deadlock avoidance, so that the information may
297  * be preserved as to what location originally acquired the lock.
298  */
299 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);
300
301 /*!
302  * \brief Unlock a lock briefly
303  *
304  * used during deadlock avoidance, to preserve the original location where
305  * a lock was originally acquired.
306  */
307 #define AO2_DEADLOCK_AVOIDANCE(obj) \
308         do { \
309                 char __filename[80], __func[80], __mutex_name[80]; \
310                 int __lineno; \
311                 int __res = ast_find_lock_info(ao2_object_get_lockaddr(obj), __filename, sizeof(__filename), &__lineno, __func, sizeof(__func), __mutex_name, sizeof(__mutex_name)); \
312                 int __res2 = ao2_unlock(obj); \
313                 usleep(1); \
314                 if (__res < 0) { /* Could happen if the ao2 object does not have a mutex. */ \
315                         if (__res2) { \
316                                 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)); \
317                         } else { \
318                                 ao2_lock(obj); \
319                         } \
320                 } else { \
321                         if (__res2) { \
322                                 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); \
323                         } else { \
324                                 __ao2_lock(obj, AO2_LOCK_REQ_MUTEX, __filename, __func, __lineno, __mutex_name); \
325                         } \
326                 } \
327         } while (0)
328
329 #define CHANNEL_DEADLOCK_AVOIDANCE(chan) \
330         do { \
331                 char __filename[80], __func[80], __mutex_name[80]; \
332                 int __lineno; \
333                 int __res = ast_find_lock_info(ao2_object_get_lockaddr(chan), __filename, sizeof(__filename), &__lineno, __func, sizeof(__func), __mutex_name, sizeof(__mutex_name)); \
334                 int __res2 = ast_channel_unlock(chan); \
335                 usleep(1); \
336                 if (__res < 0) { /* Shouldn't ever happen, but just in case... */ \
337                         if (__res2) { \
338                                 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)); \
339                         } else { \
340                                 ast_channel_lock(chan); \
341                         } \
342                 } else { \
343                         if (__res2) { \
344                                 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); \
345                         } else { \
346                                 __ao2_lock(chan, AO2_LOCK_REQ_MUTEX, __filename, __func, __lineno, __mutex_name); \
347                         } \
348                 } \
349         } while (0)
350
351 #define DEADLOCK_AVOIDANCE(lock) \
352         do { \
353                 char __filename[80], __func[80], __mutex_name[80]; \
354                 int __lineno; \
355                 int __res = ast_find_lock_info(lock, __filename, sizeof(__filename), &__lineno, __func, sizeof(__func), __mutex_name, sizeof(__mutex_name)); \
356                 int __res2 = ast_mutex_unlock(lock); \
357                 usleep(1); \
358                 if (__res < 0) { /* Shouldn't ever happen, but just in case... */ \
359                         if (__res2 == 0) { \
360                                 ast_mutex_lock(lock); \
361                         } else { \
362                                 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)); \
363                         } \
364                 } else { \
365                         if (__res2 == 0) { \
366                                 __ast_pthread_mutex_lock(__filename, __lineno, __func, __mutex_name, lock); \
367                         } else { \
368                                 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); \
369                         } \
370                 } \
371         } while (0)
372
373 /*!
374  * \brief Deadlock avoidance unlock
375  *
376  * In certain deadlock avoidance scenarios, there is more than one lock to be
377  * unlocked and relocked.  Therefore, this pair of macros is provided for that
378  * purpose.  Note that every DLA_UNLOCK _MUST_ be paired with a matching
379  * DLA_LOCK.  The intent of this pair of macros is to be used around another
380  * set of deadlock avoidance code, mainly CHANNEL_DEADLOCK_AVOIDANCE, as the
381  * locking order specifies that we may safely lock a channel, followed by its
382  * pvt, with no worries about a deadlock.  In any other scenario, this macro
383  * may not be safe to use.
384  */
385 #define DLA_UNLOCK(lock) \
386         do { \
387                 char __filename[80], __func[80], __mutex_name[80]; \
388                 int __lineno; \
389                 int __res = ast_find_lock_info(lock, __filename, sizeof(__filename), &__lineno, __func, sizeof(__func), __mutex_name, sizeof(__mutex_name)); \
390                 int __res2 = ast_mutex_unlock(lock);
391
392 /*!
393  * \brief Deadlock avoidance lock
394  *
395  * In certain deadlock avoidance scenarios, there is more than one lock to be
396  * unlocked and relocked.  Therefore, this pair of macros is provided for that
397  * purpose.  Note that every DLA_UNLOCK _MUST_ be paired with a matching
398  * DLA_LOCK.  The intent of this pair of macros is to be used around another
399  * set of deadlock avoidance code, mainly CHANNEL_DEADLOCK_AVOIDANCE, as the
400  * locking order specifies that we may safely lock a channel, followed by its
401  * pvt, with no worries about a deadlock.  In any other scenario, this macro
402  * may not be safe to use.
403  */
404 #define DLA_LOCK(lock) \
405                 if (__res < 0) { /* Shouldn't ever happen, but just in case... */ \
406                         if (__res2) { \
407                                 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)); \
408                         } else { \
409                                 ast_mutex_lock(lock); \
410                         } \
411                 } else { \
412                         if (__res2) { \
413                                 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); \
414                         } else { \
415                                 __ast_pthread_mutex_lock(__filename, __lineno, __func, __mutex_name, lock); \
416                         } \
417                 } \
418         } while (0)
419
420 static inline void ast_reentrancy_lock(struct ast_lock_track *lt)
421 {
422         int res;
423         if ((res = pthread_mutex_lock(&lt->reentr_mutex))) {
424                 fprintf(stderr, "ast_reentrancy_lock failed: '%s' (%d)\n", strerror(res), res);
425 #if defined(DO_CRASH) || defined(THREAD_CRASH)
426                 abort();
427 #endif
428         }
429 }
430
431 static inline void ast_reentrancy_unlock(struct ast_lock_track *lt)
432 {
433         int res;
434         if ((res = pthread_mutex_unlock(&lt->reentr_mutex))) {
435                 fprintf(stderr, "ast_reentrancy_unlock failed: '%s' (%d)\n", strerror(res), res);
436 #if defined(DO_CRASH) || defined(THREAD_CRASH)
437                 abort();
438 #endif
439         }
440 }
441
442 #else /* !DEBUG_THREADS */
443
444 #define AO2_DEADLOCK_AVOIDANCE(obj) \
445         ao2_unlock(obj); \
446         usleep(1); \
447         ao2_lock(obj);
448
449 #define CHANNEL_DEADLOCK_AVOIDANCE(chan) \
450         ast_channel_unlock(chan); \
451         usleep(1); \
452         ast_channel_lock(chan);
453
454 #define DEADLOCK_AVOIDANCE(lock) \
455         do { \
456                 int __res; \
457                 if (!(__res = ast_mutex_unlock(lock))) { \
458                         usleep(1); \
459                         ast_mutex_lock(lock); \
460                 } else { \
461                         ast_log(LOG_WARNING, "Failed to unlock mutex '%s' (%s).  I will NOT try to relock. {{{ THIS IS A BUG. }}}\n", #lock, strerror(__res)); \
462                 } \
463         } while (0)
464
465 #define DLA_UNLOCK(lock) ast_mutex_unlock(lock)
466
467 #define DLA_LOCK(lock) ast_mutex_lock(lock)
468
469 #endif /* !DEBUG_THREADS */
470
471 #if defined(AST_MUTEX_INIT_W_CONSTRUCTORS)
472 /*
473  * If AST_MUTEX_INIT_W_CONSTRUCTORS is defined, use file scope constructors
474  * and destructors to create/destroy global mutexes.
475  */
476 #define __AST_MUTEX_DEFINE(scope, mutex, init_val, track)       \
477         scope ast_mutex_t mutex = init_val;                     \
478 static void  __attribute__((constructor)) init_##mutex(void)    \
479 {                                                               \
480         if (track)                                              \
481                 ast_mutex_init(&mutex);                         \
482         else                                                    \
483                 ast_mutex_init_notracking(&mutex);              \
484 }                                                               \
485                                                                 \
486 static void  __attribute__((destructor)) fini_##mutex(void)     \
487 {                                                               \
488         ast_mutex_destroy(&mutex);                              \
489 }
490 #else /* !AST_MUTEX_INIT_W_CONSTRUCTORS */
491 /* By default, use static initialization of mutexes. */
492 #define __AST_MUTEX_DEFINE(scope, mutex, init_val, track) scope ast_mutex_t mutex = init_val
493 #endif /* AST_MUTEX_INIT_W_CONSTRUCTORS */
494
495 #define AST_MUTEX_DEFINE_STATIC(mutex) __AST_MUTEX_DEFINE(static, mutex, AST_MUTEX_INIT_VALUE, 1)
496 #define AST_MUTEX_DEFINE_STATIC_NOTRACKING(mutex) __AST_MUTEX_DEFINE(static, mutex, AST_MUTEX_INIT_VALUE_NOTRACKING, 0)
497
498
499 /* Statically declared read/write locks */
500 #ifdef AST_MUTEX_INIT_W_CONSTRUCTORS
501 #define __AST_RWLOCK_DEFINE(scope, rwlock, init_val, track) \
502         scope ast_rwlock_t rwlock = init_val; \
503 static void  __attribute__((constructor)) init_##rwlock(void) \
504 { \
505         if (track) \
506                 ast_rwlock_init(&rwlock); \
507         else \
508                 ast_rwlock_init_notracking(&rwlock); \
509 } \
510 static void  __attribute__((destructor)) fini_##rwlock(void) \
511 { \
512         ast_rwlock_destroy(&rwlock); \
513 }
514 #else
515 #define __AST_RWLOCK_DEFINE(scope, rwlock, init_val, track) scope ast_rwlock_t rwlock = init_val
516 #endif
517
518 #define AST_RWLOCK_DEFINE_STATIC(rwlock) __AST_RWLOCK_DEFINE(static, rwlock, AST_RWLOCK_INIT_VALUE, 1)
519 #define AST_RWLOCK_DEFINE_STATIC_NOTRACKING(rwlock) __AST_RWLOCK_DEFINE(static, rwlock, AST_RWLOCK_INIT_VALUE_NOTRACKING, 0)
520
521 /*!
522  * \brief Scoped Locks
523  *
524  * Scoped locks provide a way to use RAII locks. In other words,
525  * declaration of a scoped lock will automatically define and lock
526  * the lock. When the lock goes out of scope, it will automatically
527  * be unlocked.
528  *
529  * \code
530  * int some_function(struct ast_channel *chan)
531  * {
532  *     SCOPED_LOCK(lock, chan, ast_channel_lock, ast_channel_unlock);
533  *
534  *     if (!strcmp(ast_channel_name(chan, "foo")) {
535  *         return 0;
536  *     }
537  *
538  *     return -1;
539  * }
540  * \endcode
541  *
542  * In the above example, neither return path requires explicit unlocking
543  * of the channel.
544  *
545  * \note
546  * Care should be taken when using SCOPED_LOCKS in conjunction with ao2 objects.
547  * ao2 objects should be unlocked before they are unreffed. Since SCOPED_LOCK runs
548  * once the variable goes out of scope, this can easily lead to situations where the
549  * variable gets unlocked after it is unreffed.
550  *
551  * \param varname The unique name to give to the scoped lock. You are not likely to reference
552  * this outside of the SCOPED_LOCK invocation.
553  * \param lock The variable to lock. This can be anything that can be passed to a locking
554  * or unlocking function.
555  * \param lockfunc The function to call to lock the lock
556  * \param unlockfunc The function to call to unlock the lock
557  */
558 #define SCOPED_LOCK(varname, lock, lockfunc, unlockfunc) \
559         RAII_VAR(typeof((lock)), varname, ({lockfunc((lock)); (lock); }), unlockfunc)
560
561 /*!
562  * \brief scoped lock specialization for mutexes
563  */
564 #define SCOPED_MUTEX(varname, lock) SCOPED_LOCK(varname, (lock), ast_mutex_lock, ast_mutex_unlock)
565
566 /*!
567  * \brief scoped lock specialization for read locks
568  */
569 #define SCOPED_RDLOCK(varname, lock) SCOPED_LOCK(varname, (lock), ast_rwlock_rdlock, ast_rwlock_unlock)
570
571 /*!
572  * \brief scoped lock specialization for write locks
573  */
574 #define SCOPED_WRLOCK(varname, lock) SCOPED_LOCK(varname, (lock), ast_rwlock_wrlock, ast_rwlock_unlock)
575
576 /*!
577  * \brief scoped lock specialization for ao2 mutexes.
578  */
579 #define SCOPED_AO2LOCK(varname, obj) SCOPED_LOCK(varname, (obj), ao2_lock, ao2_unlock)
580
581 /*!
582  * \brief scoped lock specialization for ao2 read locks.
583  */
584 #define SCOPED_AO2RDLOCK(varname, obj) SCOPED_LOCK(varname, (obj), ao2_rdlock, ao2_unlock)
585
586 /*!
587  * \brief scoped lock specialization for ao2 write locks.
588  */
589 #define SCOPED_AO2WRLOCK(varname, obj) SCOPED_LOCK(varname, (obj), ao2_wrlock, ao2_unlock)
590
591 /*!
592  * \brief scoped lock specialization for channels.
593  */
594 #define SCOPED_CHANNELLOCK(varname, chan) SCOPED_LOCK(varname, (chan), ast_channel_lock, ast_channel_unlock)
595
596 #ifndef __CYGWIN__      /* temporary disabled for cygwin */
597 #define pthread_mutex_t         use_ast_mutex_t_instead_of_pthread_mutex_t
598 #define pthread_cond_t          use_ast_cond_t_instead_of_pthread_cond_t
599 #endif
600 #define pthread_mutex_lock      use_ast_mutex_lock_instead_of_pthread_mutex_lock
601 #define pthread_mutex_unlock    use_ast_mutex_unlock_instead_of_pthread_mutex_unlock
602 #define pthread_mutex_trylock   use_ast_mutex_trylock_instead_of_pthread_mutex_trylock
603 #define pthread_mutex_init      use_ast_mutex_init_instead_of_pthread_mutex_init
604 #define pthread_mutex_destroy   use_ast_mutex_destroy_instead_of_pthread_mutex_destroy
605 #define pthread_cond_init       use_ast_cond_init_instead_of_pthread_cond_init
606 #define pthread_cond_destroy    use_ast_cond_destroy_instead_of_pthread_cond_destroy
607 #define pthread_cond_signal     use_ast_cond_signal_instead_of_pthread_cond_signal
608 #define pthread_cond_broadcast  use_ast_cond_broadcast_instead_of_pthread_cond_broadcast
609 #define pthread_cond_wait       use_ast_cond_wait_instead_of_pthread_cond_wait
610 #define pthread_cond_timedwait  use_ast_cond_timedwait_instead_of_pthread_cond_timedwait
611
612 #define AST_MUTEX_INITIALIZER __use_AST_MUTEX_DEFINE_STATIC_rather_than_AST_MUTEX_INITIALIZER__
613
614 #define gethostbyname __gethostbyname__is__not__reentrant__use__ast_gethostbyname__instead__
615
616 #ifndef __linux__
617 #define pthread_create __use_ast_pthread_create_instead__
618 #endif
619
620 /*
621  * Support for atomic instructions.
622  * For platforms that have it, use the native cpu instruction to
623  * implement them. For other platforms, resort to a 'slow' version
624  * (defined in utils.c) that protects the atomic instruction with
625  * a single lock.
626  * The slow versions is always available, for testing purposes,
627  * as ast_atomic_fetchadd_int_slow()
628  */
629
630 int ast_atomic_fetchadd_int_slow(volatile int *p, int v);
631
632 #include "asterisk/inline_api.h"
633
634 #if defined(HAVE_OSX_ATOMICS)
635 #include "libkern/OSAtomic.h"
636 #endif
637
638 /*! \brief Atomically add v to *p and return * the previous value of *p.
639  * This can be used to handle reference counts, and the return value
640  * can be used to generate unique identifiers.
641  */
642
643 #if defined(HAVE_GCC_ATOMICS)
644 AST_INLINE_API(int ast_atomic_fetchadd_int(volatile int *p, int v),
645 {
646         return __sync_fetch_and_add(p, v);
647 })
648 #elif defined(HAVE_OSX_ATOMICS) && (SIZEOF_INT == 4)
649 AST_INLINE_API(int ast_atomic_fetchadd_int(volatile int *p, int v),
650 {
651         return OSAtomicAdd32(v, (int32_t *) p) - v;
652 })
653 #elif defined(HAVE_OSX_ATOMICS) && (SIZEOF_INT == 8)
654 AST_INLINE_API(int ast_atomic_fetchadd_int(volatile int *p, int v),
655 {
656         return OSAtomicAdd64(v, (int64_t *) p) - v;
657 })
658 #elif defined (__i386__) || defined(__x86_64__)
659 #ifdef sun
660 AST_INLINE_API(int ast_atomic_fetchadd_int(volatile int *p, int v),
661 {
662         __asm __volatile (
663         "       lock;  xaddl   %0, %1 ;        "
664         : "+r" (v),                     /* 0 (result) */
665           "=m" (*p)                     /* 1 */
666         : "m" (*p));                    /* 2 */
667         return (v);
668 })
669 #else /* ifndef sun */
670 AST_INLINE_API(int ast_atomic_fetchadd_int(volatile int *p, int v),
671 {
672         __asm __volatile (
673         "       lock   xaddl   %0, %1 ;        "
674         : "+r" (v),                     /* 0 (result) */
675           "=m" (*p)                     /* 1 */
676         : "m" (*p));                    /* 2 */
677         return (v);
678 })
679 #endif
680 #else   /* low performance version in utils.c */
681 AST_INLINE_API(int ast_atomic_fetchadd_int(volatile int *p, int v),
682 {
683         return ast_atomic_fetchadd_int_slow(p, v);
684 })
685 #endif
686
687 /*! \brief decrement *p by 1 and return true if the variable has reached 0.
688  * Useful e.g. to check if a refcount has reached 0.
689  */
690 #if defined(HAVE_GCC_ATOMICS)
691 AST_INLINE_API(int ast_atomic_dec_and_test(volatile int *p),
692 {
693         return __sync_sub_and_fetch(p, 1) == 0;
694 })
695 #elif defined(HAVE_OSX_ATOMICS) && (SIZEOF_INT == 4)
696 AST_INLINE_API(int ast_atomic_dec_and_test(volatile int *p),
697 {
698         return OSAtomicAdd32( -1, (int32_t *) p) == 0;
699 })
700 #elif defined(HAVE_OSX_ATOMICS) && (SIZEOF_INT == 8)
701 AST_INLINE_API(int ast_atomic_dec_and_test(volatile int *p),
702 {
703         return OSAtomicAdd64( -1, (int64_t *) p) == 0;
704 })
705 #else
706 AST_INLINE_API(int ast_atomic_dec_and_test(volatile int *p),
707 {
708         int a = ast_atomic_fetchadd_int(p, -1);
709         return a == 1; /* true if the value is 0 now (so it was 1 previously) */
710 })
711 #endif
712
713 #endif /* _ASTERISK_LOCK_H */