include/asterisk/threadstorage.h

   1 /*
   2  * Asterisk -- An open source telephony toolkit.
   3  *
   4  * Copyright (C) 2006, Digium, Inc.
   5  *
   6  * Russell Bryant <russell@digium.com>
   7  *
   8  * See http://www.asterisk.org for more information about
   9  * the Asterisk project. Please do not directly contact
  10  * any of the maintainers of this project for assistance;
  11  * the project provides a web site, mailing lists and IRC
  12  * channels for your use.
  13  *
  14  * This program is free software, distributed under the terms of
  15  * the GNU General Public License Version 2. See the LICENSE file
  16  * at the top of the source tree.
  17  */
  18
  19 /*!
  20  * \file threadstorage.h
  21  * \author Russell Bryant <russell@digium.com>
  22  * \brief Definitions to aid in the use of thread local storage
  23  *
  24  * \arg \ref AstThreadStorage
  25  */
  26
  27 /*!
  28  * \page AstThreadStorage The Asterisk Thread Storage API
  29  *
  30  *
  31  * The POSIX threads (pthreads) API provides the ability to define thread
  32  * specific data.  The functions and structures defined here are intended
  33  * to centralize the code that is commonly used when using thread local
  34  * storage.
  35  *
  36  * The motivation for using this code in Asterisk is for situations where
  37  * storing data on a thread-specific basis can provide some amount of
  38  * performance benefit.  For example, there are some call types in Asterisk
  39  * where ast_frame structures must be allocated very rapidly (easily 50, 100,
  40  * 200 times a second).  Instead of doing the equivalent of that many calls
  41  * to malloc() and free() per second, thread local storage is used to keep a
  42  * list of unused frame structures so that they can be continuously reused.
  43  *
  44  * - \ref threadstorage.h
  45  */
  46
  47 #ifndef ASTERISK_THREADSTORAGE_H
  48 #define ASTERISK_THREADSTORAGE_H
  49
  50 #include "asterisk/utils.h"
  51 #include "asterisk/inline_api.h"
  52
  53 /*!
  54  * \brief data for a thread locally stored variable
  55  */
  56 struct ast_threadstorage {
  57         pthread_once_t once;    /*!< Ensure that the key is only initialized by one thread */
  58         pthread_key_t key;      /*!< The key used to retrieve this thread's data */
  59         void (*key_init)(void); /*!< The function that initializes the key */
  60         int (*custom_init)(void *); /*!< Custom initialization function specific to the object */
  61 };
  62
  63 #if defined(DEBUG_THREADLOCALS)
  64 void __ast_threadstorage_object_add(void *key, size_t len, const char *file, const char *function, unsigned int line);
  65 void __ast_threadstorage_object_remove(void *key);
  66 void __ast_threadstorage_object_replace(void *key_old, void *key_new, size_t len);
  67 #endif /* defined(DEBUG_THREADLOCALS) */
  68
  69 /*!
  70  * \brief Define a thread storage variable
  71  *
  72  * \param name The name of the thread storage object
  73  *
  74  * This macro would be used to declare an instance of thread storage in a file.
  75  *
  76  * Example usage:
  77  * \code
  78  * AST_THREADSTORAGE(my_buf);
  79  * \endcode
  80  */
  81 #define AST_THREADSTORAGE(name) \
  82         AST_THREADSTORAGE_CUSTOM_SCOPE(name, NULL, ast_free_ptr, static)
  83 #define AST_THREADSTORAGE_PUBLIC(name) \
  84         AST_THREADSTORAGE_CUSTOM_SCOPE(name, NULL, ast_free_ptr,)
  85 #define AST_THREADSTORAGE_EXTERNAL(name) \
  86         extern struct ast_threadstorage name
  87
  88 /*!
  89  * \brief Define a thread storage variable, with custom initialization and cleanup
  90  *
  91  * \param a The name of the thread storage object
  92  * \param b This is a custom function that will be called after each thread specific
  93  *           object is allocated, with the allocated block of memory passed
  94  *           as the argument.
  95  * \param c This is a custom function that will be called instead of ast_free
  96  *              when the thread goes away.  Note that if this is used, it *MUST*
  97  *              call free on the allocated memory.
  98  *
  99  * Example usage:
 100  * \code
 101  * AST_THREADSTORAGE_CUSTOM(my_buf, my_init, my_cleanup);
 102  * \endcode
 103  */
 104 #define AST_THREADSTORAGE_CUSTOM(a,b,c) AST_THREADSTORAGE_CUSTOM_SCOPE(a,b,c,static)
 105
 106 #if defined(PTHREAD_ONCE_INIT_NEEDS_BRACES)
 107 # define AST_PTHREAD_ONCE_INIT { PTHREAD_ONCE_INIT }
 108 #else
 109 # define AST_PTHREAD_ONCE_INIT PTHREAD_ONCE_INIT
 110 #endif
 111
 112 #if !defined(DEBUG_THREADLOCALS)
 113 #define AST_THREADSTORAGE_CUSTOM_SCOPE(name, c_init, c_cleanup, scope)  \
 114 static void __init_##name(void);                \
 115 scope struct ast_threadstorage name = {         \
 116         .once = AST_PTHREAD_ONCE_INIT,              \
 117         .key_init = __init_##name,                  \
 118         .custom_init = c_init,                      \
 119 };                                              \
 120 static void __init_##name(void)                 \
 121 {                                               \
 122         pthread_key_create(&(name).key, c_cleanup); \
 123 }
 124 #else /* defined(DEBUG_THREADLOCALS) */
 125 #define AST_THREADSTORAGE_CUSTOM_SCOPE(name, c_init, c_cleanup, scope) \
 126 static void __init_##name(void);                \
 127 scope struct ast_threadstorage name = {         \
 128         .once = AST_PTHREAD_ONCE_INIT,              \
 129         .key_init = __init_##name,                  \
 130         .custom_init = c_init,                      \
 131 };                                              \
 132 static void __cleanup_##name(void *data)        \
 133 {                                               \
 134         __ast_threadstorage_object_remove(data);    \
 135         c_cleanup(data);                            \
 136 }                                               \
 137 static void __init_##name(void)                 \
 138 {                                               \
 139         pthread_key_create(&(name).key, __cleanup_##name); \
 140 }
 141 #endif /* defined(DEBUG_THREADLOCALS) */
 142
 143 /*!
 144  * \brief Retrieve thread storage
 145  *
 146  * \param ts This is a pointer to the thread storage structure declared by using
 147  *      the AST_THREADSTORAGE macro.  If declared with
 148  *      AST_THREADSTORAGE(my_buf), then this argument would be (&my_buf).
 149  * \param init_size This is the amount of space to be allocated the first time
 150  *      this thread requests its data. Thus, this should be the size that the
 151  *      code accessing this thread storage is assuming the size to be.
 152  *
 153  * \return This function will return the thread local storage associated with
 154  *         the thread storage management variable passed as the first argument.
 155  *         The result will be NULL in the case of a memory allocation error.
 156  *
 157  * Example usage:
 158  * \code
 159  * AST_THREADSTORAGE(my_buf);
 160  * #define MY_BUF_SIZE   128
 161  * ...
 162  * void my_func(const char *fmt, ...)
 163  * {
 164  *      void *buf;
 165  *
 166  *      if (!(buf = ast_threadstorage_get(&my_buf, MY_BUF_SIZE)))
 167  *           return;
 168  *      ...
 169  * }
 170  * \endcode
 171  */
 172 #if !defined(DEBUG_THREADLOCALS)
 173 AST_INLINE_API(
 174 void *ast_threadstorage_get(struct ast_threadstorage *ts, size_t init_size),
 175 {
 176         void *buf;
 177
 178         pthread_once(&ts->once, ts->key_init);
 179         if (!(buf = pthread_getspecific(ts->key))) {
 180                 if (!(buf = ast_calloc(1, init_size)))
 181                         return NULL;
 182                 if (ts->custom_init && ts->custom_init(buf)) {
 183                         free(buf);
 184                         return NULL;
 185                 }
 186                 pthread_setspecific(ts->key, buf);
 187         }
 188
 189         return buf;
 190 }
 191 )
 192 #else /* defined(DEBUG_THREADLOCALS) */
 193 AST_INLINE_API(
 194 void *__ast_threadstorage_get(struct ast_threadstorage *ts, size_t init_size, const char *file, const char *function, unsigned int line),
 195 {
 196         void *buf;
 197
 198         pthread_once(&ts->once, ts->key_init);
 199         if (!(buf = pthread_getspecific(ts->key))) {
 200                 if (!(buf = ast_calloc(1, init_size)))
 201                         return NULL;
 202                 if (ts->custom_init && ts->custom_init(buf)) {
 203                         free(buf);
 204                         return NULL;
 205                 }
 206                 pthread_setspecific(ts->key, buf);
 207                 __ast_threadstorage_object_add(buf, init_size, file, function, line);
 208         }
 209
 210         return buf;
 211 }
 212 )
 213
 214 #define ast_threadstorage_get(ts, init_size) __ast_threadstorage_get(ts, init_size, __FILE__, __PRETTY_FUNCTION__, __LINE__)
 215 #endif /* defined(DEBUG_THREADLOCALS) */
 216
 217 #endif /* ASTERISK_THREADSTORAGE_H */