Match use of ast_free() with ast_calloc() and add some curly braces.
[asterisk/asterisk.git] / 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                 }
183                 if (ts->custom_init && ts->custom_init(buf)) {
184                         ast_free(buf);
185                         return NULL;
186                 }
187                 pthread_setspecific(ts->key, buf);
188         }
189
190         return buf;
191 }
192 )
193 #else /* defined(DEBUG_THREADLOCALS) */
194 AST_INLINE_API(
195 void *__ast_threadstorage_get(struct ast_threadstorage *ts, size_t init_size, const char *file, const char *function, unsigned int line),
196 {
197         void *buf;
198
199         pthread_once(&ts->once, ts->key_init);
200         if (!(buf = pthread_getspecific(ts->key))) {
201                 if (!(buf = ast_calloc(1, init_size))) {
202                         return NULL;
203                 }
204                 if (ts->custom_init && ts->custom_init(buf)) {
205                         ast_free(buf);
206                         return NULL;
207                 }
208                 pthread_setspecific(ts->key, buf);
209                 __ast_threadstorage_object_add(buf, init_size, file, function, line);
210         }
211
212         return buf;
213 }
214 )
215
216 #define ast_threadstorage_get(ts, init_size) __ast_threadstorage_get(ts, init_size, __FILE__, __PRETTY_FUNCTION__, __LINE__)
217 #endif /* defined(DEBUG_THREADLOCALS) */
218
219 #endif /* ASTERISK_THREADSTORAGE_H */