[asterisk-commits] trunk r16528 - /trunk/include/asterisk/lock.h

[asterisk-commits at lists.digium.com]

Author: rizzo
Date: Thu Mar 30 10:09:23 2006
New Revision: 16528

URL: http://svn.digium.com/view/asterisk?rev=16528&view=rev
Log:
document why there are so many versions of the mutex functions,
with their pros and cons, and that we should converge to a single method.


Modified:
    trunk/include/asterisk/lock.h

Modified: trunk/include/asterisk/lock.h
URL: http://svn.digium.com/view/asterisk/trunk/include/asterisk/lock.h?rev=16528&r1=16527&r2=16528&view=diff
==============================================================================
--- trunk/include/asterisk/lock.h (original)
+++ trunk/include/asterisk/lock.h Thu Mar 30 10:09:23 2006
@@ -18,6 +18,33 @@
 
 /*! \file
  * \brief General Asterisk channel locking definitions.
+ *
+ * This file provides several different implementation of the functions,
+ * depending on the platform, the use of DEBUG_THREADS, and the way
+ * global mutexes are initialized.
+ * At the moment, we have 3 ways to initialize global mutexes, depending on
+ *
+ *  + static: the mutex is assigned the value AST_MUTEX_INIT_VALUE
+ *        this is done at compile time, and is the way used on Linux.
+ *        This method is not applicable to all platforms e.g. when the
+ *        initialization needs that some code is run.
+ *
+ *  + on first use: the mutex is assigned a magic value at compile time,
+ *        and ast_mutex_init() is called when this magic value is detected.
+ *        This technique is generally applicable, though it has a bit of
+ *        overhead on each access to check whether initialization is needed.
+ *        On the other hand, the overall cost of a mutex_lock operation
+ *        is such that this overhead is often negligible.
+
+ *  + through constructors: for each mutex, a constructor function is
+ *        defined, which then runs when the program (or the module)
+ *        starts. The problem with this approach is that there is a
+ *        lot of code duplication (a new block of code is created for
+ *        each mutex). Also, it does not prevent a user from declaring
+ *        a global mutex without going through the wrapper macros,
+ *        so sane programming practices are still required.
+ *
+ * Eventually we should converge on a single method for all platforms.
  */
 
 #ifndef _ASTERISK_LOCK_H