00001 /* 00002 * Asterisk -- An open source telephony toolkit. 00003 * 00004 * Copyright (C) 2006, Digium, Inc. 00005 * 00006 * Russell Bryant <russell@digium.com> 00007 * 00008 * See http://www.asterisk.org for more information about 00009 * the Asterisk project. Please do not directly contact 00010 * any of the maintainers of this project for assistance; 00011 * the project provides a web site, mailing lists and IRC 00012 * channels for your use. 00013 * 00014 * This program is free software, distributed under the terms of 00015 * the GNU General Public License Version 2. See the LICENSE file 00016 * at the top of the source tree. 00017 */ 00018 00019 /*! 00020 * \file threadstorage.h 00021 * \author Russell Bryant <russell@digium.com> 00022 * \brief Definitions to aid in the use of thread local storage 00023 * 00024 * \arg \ref AstThreadStorage 00025 */ 00026 00027 /*! 00028 * \page AstThreadStorage The Asterisk Thread Storage API 00029 * 00030 * 00031 * The POSIX threads (pthreads) API provides the ability to define thread 00032 * specific data. The functions and structures defined here are intended 00033 * to centralize the code that is commonly used when using thread local 00034 * storage. 00035 * 00036 * The motivation for using this code in Asterisk is for situations where 00037 * storing data on a thread-specific basis can provide some amount of 00038 * performance benefit. For example, there are some call types in Asterisk 00039 * where ast_frame structures must be allocated very rapidly (easily 50, 100, 00040 * 200 times a second). Instead of doing the equivalent of that many calls 00041 * to malloc() and free() per second, thread local storage is used to keep a 00042 * list of unused frame structures so that they can be continuously reused. 00043 * 00044 * - \ref threadstorage.h 00045 */ 00046 00047 #ifndef ASTERISK_THREADSTORAGE_H 00048 #define ASTERISK_THREADSTORAGE_H 00049 00050 #include "asterisk/utils.h" 00051 #include "asterisk/inline_api.h" 00052 00053 /*! 00054 * \brief data for a thread locally stored variable 00055 */ 00056 struct ast_threadstorage { 00057 pthread_once_t once; /*!< Ensure that the key is only initialized by one thread */ 00058 pthread_key_t key; /*!< The key used to retrieve this thread's data */ 00059 void (*key_init)(void); /*!< The function that initializes the key */ 00060 int (*custom_init)(void *); /*!< Custom initialization function specific to the object */ 00061 }; 00062 00063 #if defined(DEBUG_THREADLOCALS) 00064 void __ast_threadstorage_object_add(void *key, size_t len, const char *file, const char *function, unsigned int line); 00065 void __ast_threadstorage_object_remove(void *key); 00066 void __ast_threadstorage_object_replace(void *key_old, void *key_new, size_t len); 00067 #endif /* defined(DEBUG_THREADLOCALS) */ 00068 00069 /*! 00070 * \brief Define a thread storage variable 00071 * 00072 * \param name The name of the thread storage object 00073 * 00074 * This macro would be used to declare an instance of thread storage in a file. 00075 * 00076 * Example usage: 00077 * \code 00078 * AST_THREADSTORAGE(my_buf); 00079 * \endcode 00080 */ 00081 #define AST_THREADSTORAGE(name) \ 00082 AST_THREADSTORAGE_CUSTOM(name, NULL, ast_free_ptr) 00083 00084 /*! 00085 * \brief Define a thread storage variable, with custom initialization and cleanup 00086 * 00087 * \param name The name of the thread storage object 00088 * \param init This is a custom function that will be called after each thread specific 00089 * object is allocated, with the allocated block of memory passed 00090 * as the argument. 00091 * \param cleanup This is a custom function that will be called instead of ast_free 00092 * when the thread goes away. Note that if this is used, it *MUST* 00093 * call free on the allocated memory. 00094 * 00095 * Example usage: 00096 * \code 00097 * AST_THREADSTORAGE_CUSTOM(my_buf, my_init, my_cleanup); 00098 * \endcode 00099 */ 00100 #if !defined(DEBUG_THREADLOCALS) 00101 #define AST_THREADSTORAGE_CUSTOM(name, c_init, c_cleanup) \ 00102 static void __init_##name(void); \ 00103 static struct ast_threadstorage name = { \ 00104 .once = PTHREAD_ONCE_INIT, \ 00105 .key_init = __init_##name, \ 00106 .custom_init = c_init, \ 00107 }; \ 00108 static void __init_##name(void) \ 00109 { \ 00110 pthread_key_create(&(name).key, c_cleanup); \ 00111 } 00112 #else /* defined(DEBUG_THREADLOCALS) */ 00113 #define AST_THREADSTORAGE_CUSTOM_SCOPE(name, c_init, c_cleanup, scope) \ 00114 static void __init_##name(void); \ 00115 static struct ast_threadstorage name = { \ 00116 .once = PTHREAD_ONCE_INIT, \ 00117 .key_init = __init_##name, \ 00118 .custom_init = c_init, \ 00119 }; \ 00120 static void __cleanup_##name(void *data) \ 00121 { \ 00122 __ast_threadstorage_object_remove(data); \ 00123 c_cleanup(data); \ 00124 } \ 00125 static void __init_##name(void) \ 00126 { \ 00127 pthread_key_create(&(name).key, __cleanup_##name); \ 00128 } 00129 #endif /* defined(DEBUG_THREADLOCALS) */ 00130 00131 /*! 00132 * \brief Retrieve thread storage 00133 * 00134 * \param ts This is a pointer to the thread storage structure declared by using 00135 * the AST_THREADSTORAGE macro. If declared with 00136 * AST_THREADSTORAGE(my_buf), then this argument would be (&my_buf). 00137 * \param init_size This is the amount of space to be allocated the first time 00138 * this thread requests its data. Thus, this should be the size that the 00139 * code accessing this thread storage is assuming the size to be. 00140 * 00141 * \return This function will return the thread local storage associated with 00142 * the thread storage management variable passed as the first argument. 00143 * The result will be NULL in the case of a memory allocation error. 00144 * 00145 * Example usage: 00146 * \code 00147 * AST_THREADSTORAGE(my_buf); 00148 * #define MY_BUF_SIZE 128 00149 * ... 00150 * void my_func(const char *fmt, ...) 00151 * { 00152 * void *buf; 00153 * 00154 * if (!(buf = ast_threadstorage_get(&my_buf, MY_BUF_SIZE))) 00155 * return; 00156 * ... 00157 * } 00158 * \endcode 00159 */ 00160 #if !defined(DEBUG_THREADLOCALS) 00161 AST_INLINE_API( 00162 void *ast_threadstorage_get(struct ast_threadstorage *ts, size_t init_size), 00163 { 00164 void *buf; 00165 00166 pthread_once(&ts->once, ts->key_init); 00167 if (!(buf = pthread_getspecific(ts->key))) { 00168 if (!(buf = ast_calloc(1, init_size))) 00169 return NULL; 00170 if (ts->custom_init && ts->custom_init(buf)) { 00171 free(buf); 00172 return NULL; 00173 } 00174 pthread_setspecific(ts->key, buf); 00175 } 00176 00177 return buf; 00178 } 00179 ) 00180 #else /* defined(DEBUG_THREADLOCALS) */ 00181 AST_INLINE_API( 00182 void *__ast_threadstorage_get(struct ast_threadstorage *ts, size_t init_size, const char *file, const char *function, unsigned int line), 00183 { 00184 void *buf; 00185 00186 pthread_once(&ts->once, ts->key_init); 00187 if (!(buf = pthread_getspecific(ts->key))) { 00188 if (!(buf = ast_calloc(1, init_size))) 00189 return NULL; 00190 if (ts->custom_init && ts->custom_init(buf)) { 00191 free(buf); 00192 return NULL; 00193 } 00194 pthread_setspecific(ts->key, buf); 00195 __ast_threadstorage_object_add(buf, init_size, file, function, line); 00196 } 00197 00198 return buf; 00199 } 00200 ) 00201 00202 #define ast_threadstorage_get(ts, init_size) __ast_threadstorage_get(ts, init_size, __FILE__, __PRETTY_FUNCTION__, __LINE__) 00203 #endif /* defined(DEBUG_THREADLOCALS) */ 00204 00205 #endif /* ASTERISK_THREADSTORAGE_H */