Tue Aug 20 16:34:39 2013

Asterisk developer's documentation


threadstorage.h

Go to the documentation of this file.
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_SCOPE(name, NULL, ast_free_ptr, static) 
00083 #define AST_THREADSTORAGE_PUBLIC(name) \
00084    AST_THREADSTORAGE_CUSTOM_SCOPE(name, NULL, ast_free_ptr,) 
00085 #define AST_THREADSTORAGE_EXTERNAL(name) \
00086    extern struct ast_threadstorage name
00087 
00088 /*!
00089  * \brief Define a thread storage variable, with custom initialization and cleanup
00090  *
00091  * \param a The name of the thread storage object
00092  * \param b This is a custom function that will be called after each thread specific
00093  *           object is allocated, with the allocated block of memory passed
00094  *           as the argument.
00095  * \param c This is a custom function that will be called instead of ast_free
00096  *              when the thread goes away.  Note that if this is used, it *MUST*
00097  *              call free on the allocated memory.
00098  *
00099  * Example usage:
00100  * \code
00101  * AST_THREADSTORAGE_CUSTOM(my_buf, my_init, my_cleanup);
00102  * \endcode
00103  */
00104 #define AST_THREADSTORAGE_CUSTOM(a,b,c)   AST_THREADSTORAGE_CUSTOM_SCOPE(a,b,c,static)
00105 
00106 #if defined(PTHREAD_ONCE_INIT_NEEDS_BRACES)
00107 # define AST_PTHREAD_ONCE_INIT { PTHREAD_ONCE_INIT }
00108 #else
00109 # define AST_PTHREAD_ONCE_INIT PTHREAD_ONCE_INIT
00110 #endif
00111 
00112 #if !defined(DEBUG_THREADLOCALS)
00113 #define AST_THREADSTORAGE_CUSTOM_SCOPE(name, c_init, c_cleanup, scope)  \
00114 static void __init_##name(void);                \
00115 scope struct ast_threadstorage name = {         \
00116    .once = AST_PTHREAD_ONCE_INIT,              \
00117    .key_init = __init_##name,                  \
00118    .custom_init = c_init,                      \
00119 };                                              \
00120 static void __init_##name(void)                 \
00121 {                                               \
00122    pthread_key_create(&(name).key, c_cleanup); \
00123 }
00124 #else /* defined(DEBUG_THREADLOCALS) */
00125 #define AST_THREADSTORAGE_CUSTOM_SCOPE(name, c_init, c_cleanup, scope) \
00126 static void __init_##name(void);                \
00127 scope struct ast_threadstorage name = {         \
00128    .once = AST_PTHREAD_ONCE_INIT,              \
00129    .key_init = __init_##name,                  \
00130    .custom_init = c_init,                      \
00131 };                                              \
00132 static void __cleanup_##name(void *data)        \
00133 {                                               \
00134    __ast_threadstorage_object_remove(data);    \
00135    c_cleanup(data);                            \
00136 }                                               \
00137 static void __init_##name(void)                 \
00138 {                                               \
00139    pthread_key_create(&(name).key, __cleanup_##name); \
00140 }
00141 #endif /* defined(DEBUG_THREADLOCALS) */
00142 
00143 /*!
00144  * \brief Retrieve thread storage
00145  *
00146  * \param ts This is a pointer to the thread storage structure declared by using
00147  *      the AST_THREADSTORAGE macro.  If declared with 
00148  *      AST_THREADSTORAGE(my_buf), then this argument would be (&my_buf).
00149  * \param init_size This is the amount of space to be allocated the first time
00150  *      this thread requests its data. Thus, this should be the size that the
00151  *      code accessing this thread storage is assuming the size to be.
00152  *
00153  * \return This function will return the thread local storage associated with
00154  *         the thread storage management variable passed as the first argument.
00155  *         The result will be NULL in the case of a memory allocation error.
00156  *
00157  * Example usage:
00158  * \code
00159  * AST_THREADSTORAGE(my_buf);
00160  * #define MY_BUF_SIZE   128
00161  * ...
00162  * void my_func(const char *fmt, ...)
00163  * {
00164  *      void *buf;
00165  *
00166  *      if (!(buf = ast_threadstorage_get(&my_buf, MY_BUF_SIZE)))
00167  *           return;
00168  *      ...
00169  * }
00170  * \endcode
00171  */
00172 #if !defined(DEBUG_THREADLOCALS)
00173 AST_INLINE_API(
00174 void *ast_threadstorage_get(struct ast_threadstorage *ts, size_t init_size),
00175 {
00176    void *buf;
00177 
00178    pthread_once(&ts->once, ts->key_init);
00179    if (!(buf = pthread_getspecific(ts->key))) {
00180       if (!(buf = ast_calloc(1, init_size)))
00181          return NULL;
00182       if (ts->custom_init && ts->custom_init(buf)) {
00183          free(buf);
00184          return NULL;
00185       }
00186       pthread_setspecific(ts->key, buf);
00187    }
00188 
00189    return buf;
00190 }
00191 )
00192 #else /* defined(DEBUG_THREADLOCALS) */
00193 AST_INLINE_API(
00194 void *__ast_threadstorage_get(struct ast_threadstorage *ts, size_t init_size, const char *file, const char *function, unsigned int line),
00195 {
00196    void *buf;
00197 
00198    pthread_once(&ts->once, ts->key_init);
00199    if (!(buf = pthread_getspecific(ts->key))) {
00200       if (!(buf = ast_calloc(1, init_size)))
00201          return NULL;
00202       if (ts->custom_init && ts->custom_init(buf)) {
00203          free(buf);
00204          return NULL;
00205       }
00206       pthread_setspecific(ts->key, buf);
00207       __ast_threadstorage_object_add(buf, init_size, file, function, line);
00208    }
00209 
00210    return buf;
00211 }
00212 )
00213 
00214 #define ast_threadstorage_get(ts, init_size) __ast_threadstorage_get(ts, init_size, __FILE__, __PRETTY_FUNCTION__, __LINE__)
00215 #endif /* defined(DEBUG_THREADLOCALS) */
00216 
00217 #endif /* ASTERISK_THREADSTORAGE_H */

Generated on 20 Aug 2013 for Asterisk - The Open Source Telephony Project by  doxygen 1.6.1