[svn-commits] tilghman: trunk r125895 - /trunk/include/asterisk/lock.h

[SVN commits to the Digium repositories]

Author: tilghman
Date: Fri Jun 27 12:02:56 2008
New Revision: 125895

URL: http://svn.digium.com/view/asterisk?view=rev&rev=125895
Log:
Document DLA_UNLOCK and DLA_LOCK

Modified:
    trunk/include/asterisk/lock.h

Modified: trunk/include/asterisk/lock.h
URL: http://svn.digium.com/view/asterisk/trunk/include/asterisk/lock.h?view=diff&rev=125895&r1=125894&r2=125895
==============================================================================
--- trunk/include/asterisk/lock.h (original)
+++ trunk/include/asterisk/lock.h Fri Jun 27 12:02:56 2008
@@ -289,6 +289,18 @@
 		} \
 	} while (0)
 
+/*!
+ * \brief Deadlock avoidance unlock
+ *
+ * In certain deadlock avoidance scenarios, there is more than one lock to be
+ * unlocked and relocked.  Therefore, this pair of macros is provided for that
+ * purpose.  Note that every DLA_UNLOCK _MUST_ be paired with a matching
+ * DLA_LOCK.  The intent of this pair of macros is to be used around another
+ * set of deadlock avoidance code, mainly CHANNEL_DEADLOCK_AVOIDANCE, as the
+ * locking order specifies that we may safely lock a channel, followed by its
+ * pvt, with no worries about a deadlock.  In any other scenario, this macro
+ * may not be safe to use.
+ */
 #define DLA_UNLOCK(lock) \
 	do { \
 		char __filename[80], __func[80], __mutex_name[80]; \
@@ -296,6 +308,18 @@
 		int __res = ast_find_lock_info(lock, __filename, sizeof(__filename), &__lineno, __func, sizeof(__func), __mutex_name, sizeof(__mutex_name)); \
 		ast_mutex_unlock(lock);
 
+/*!
+ * \brief Deadlock avoidance lock
+ *
+ * In certain deadlock avoidance scenarios, there is more than one lock to be
+ * unlocked and relocked.  Therefore, this pair of macros is provided for that
+ * purpose.  Note that every DLA_UNLOCK _MUST_ be paired with a matching
+ * DLA_LOCK.  The intent of this pair of macros is to be used around another
+ * set of deadlock avoidance code, mainly CHANNEL_DEADLOCK_AVOIDANCE, as the
+ * locking order specifies that we may safely lock a channel, followed by its
+ * pvt, with no worries about a deadlock.  In any other scenario, this macro
+ * may not be safe to use.
+ */
 #define DLA_LOCK(lock) \
 		if (__res < 0) { /* Shouldn't ever happen, but just in case... */ \
 			ast_mutex_lock(lock); \