[svn-commits] russell: trunk r48019 - in /trunk/include/asterisk: threadstorage.h utils.h

[svn-commits at lists.digium.com]

Author: russell
Date: Sun Nov 26 00:55:33 2006
New Revision: 48019

URL: http://svn.digium.com/view/asterisk?view=rev&rev=48019
Log:
- Add some comments on thread storage with a brief explanation of what it is
  as well as what the motivation is for using it.
- Add a comment by the declaration of ast_inet_ntoa() noting that this function
  is not reentrant, and the result of a previous call to the function is no
  longer valid after calling it again.

Modified:
    trunk/include/asterisk/threadstorage.h
    trunk/include/asterisk/utils.h

Modified: trunk/include/asterisk/threadstorage.h
URL: http://svn.digium.com/view/asterisk/trunk/include/asterisk/threadstorage.h?view=diff&rev=48019&r1=48018&r2=48019
==============================================================================
--- trunk/include/asterisk/threadstorage.h (original)
+++ trunk/include/asterisk/threadstorage.h Sun Nov 26 00:55:33 2006
@@ -21,7 +21,20 @@
  * \author Russell Bryant <russell at digium.com>
  *
  * \brief Definitions to aid in the use of thread local storage
-*/
+ *
+ * The POSIX threads (pthreads) API provides the ability to define thread
+ * specific data.  The functions and structures defined here are intended
+ * to centralize the code that is commonly used when using thread local
+ * storage.
+ *
+ * The motivation for using this code in Asterisk is for situations where
+ * storing data on a thread-specific basis can provide some amount of
+ * performance benefit.  For example, there are some call types in Asterisk
+ * where ast_frame structures must be allocated very rapidly (easily 50, 100,
+ * 200 times a second).  Instead of doing the equivalent of that many calls
+ * to malloc() and free() per second, thread local storage is used to keep a
+ * list of unused frame structures so that they can be continuously reused.
+ */
 
 #ifndef ASTERISK_THREADSTORAGE_H
 #define ASTERISK_THREADSTORAGE_H

Modified: trunk/include/asterisk/utils.h
URL: http://svn.digium.com/view/asterisk/trunk/include/asterisk/utils.h?view=diff&rev=48019&r1=48018&r2=48019
==============================================================================
--- trunk/include/asterisk/utils.h (original)
+++ trunk/include/asterisk/utils.h Sun Nov 26 00:55:33 2006
@@ -218,6 +218,16 @@
 
 int test_for_thread_safety(void);
 
+/*!
+ * \brief thread-safe replacement for inet_ntoa().
+ *
+ * \note It is very important to note that even though this is a thread-safe
+ *       replacement for inet_ntoa(), it is *not* reentrant.  In a single
+ *       thread, the result from a previous call to this function is no longer
+ *       valid once it is called again.  If the result from multiple calls to
+ *       this function need to be kept or used at once, then the result must be
+ *       copied to a local buffer before calling this function again.
+ */
 const char *ast_inet_ntoa(struct in_addr ia);
 
 #ifdef inet_ntoa