From a3adf3e7543b59d2cfe4abfbf3d6ee36fc4cbdd3 Mon Sep 17 00:00:00 2001 From: Russell Bryant Date: Sun, 26 Nov 2006 06:55:33 +0000 Subject: - 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. git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@48019 65c4cc65-6c06-0410-ace0-fbb531ad65f3 --- include/asterisk/threadstorage.h | 15 ++++++++++++++- include/asterisk/utils.h | 10 ++++++++++ 2 files changed, 24 insertions(+), 1 deletion(-) (limited to 'include/asterisk') diff --git a/include/asterisk/threadstorage.h b/include/asterisk/threadstorage.h index d13b616f0..4886d3520 100644 --- a/include/asterisk/threadstorage.h +++ b/include/asterisk/threadstorage.h @@ -21,7 +21,20 @@ * \author Russell Bryant * * \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 diff --git a/include/asterisk/utils.h b/include/asterisk/utils.h index 30e9523e2..3fb817980 100644 --- a/include/asterisk/utils.h +++ b/include/asterisk/utils.h @@ -218,6 +218,16 @@ static force_inline void ast_slinear_saturated_divide(short *input, short *value 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 -- cgit v1.2.3