Asterisk - The Open Source Telephony Project  18.5.0
threadstorage.h
Go to the documentation of this file.
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 2006, Digium, Inc.
5  *
6  * Russell Bryant <[email protected]>
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 <[email protected]>
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  */
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 #define THREADSTORAGE_RAW_CLEANUP(v) {}
68 #else
69 #define THREADSTORAGE_RAW_CLEANUP NULL
70 #endif /* defined(DEBUG_THREADLOCALS) */
71 
72 /*!
73  * \brief Define a thread storage variable
74  *
75  * \param name The name of the thread storage object
76  *
77  * This macro would be used to declare an instance of thread storage in a file.
78  *
79  * Example usage:
80  * \code
81  * AST_THREADSTORAGE(my_buf);
82  * \endcode
83  */
84 #define AST_THREADSTORAGE(name) \
85  AST_THREADSTORAGE_CUSTOM_SCOPE(name, NULL, ast_free_ptr, static)
86 #define AST_THREADSTORAGE_PUBLIC(name) \
87  AST_THREADSTORAGE_CUSTOM_SCOPE(name, NULL, ast_free_ptr,)
88 #define AST_THREADSTORAGE_EXTERNAL(name) \
89  extern struct ast_threadstorage name
90 #define AST_THREADSTORAGE_RAW(name) \
91  AST_THREADSTORAGE_CUSTOM_SCOPE(name, NULL, THREADSTORAGE_RAW_CLEANUP,)
92 
93 /*!
94  * \brief Define a thread storage variable, with custom initialization and cleanup
95  *
96  * \param a The name of the thread storage object
97  * \param b This is a custom function that will be called after each thread specific
98  * object is allocated, with the allocated block of memory passed
99  * as the argument.
100  * \param c This is a custom function that will be called instead of ast_free
101  * when the thread goes away. Note that if this is used, it *MUST*
102  * call free on the allocated memory.
103  *
104  * Example usage:
105  * \code
106  * AST_THREADSTORAGE_CUSTOM(my_buf, my_init, my_cleanup);
107  * \endcode
108  */
109 #define AST_THREADSTORAGE_CUSTOM(a,b,c) AST_THREADSTORAGE_CUSTOM_SCOPE(a,b,c,static)
110 
111 #if defined(PTHREAD_ONCE_INIT_NEEDS_BRACES)
112 # define AST_PTHREAD_ONCE_INIT { PTHREAD_ONCE_INIT }
113 #else
114 # define AST_PTHREAD_ONCE_INIT PTHREAD_ONCE_INIT
115 #endif
116 
117 #if !defined(DEBUG_THREADLOCALS)
118 #define AST_THREADSTORAGE_CUSTOM_SCOPE(name, c_init, c_cleanup, scope) \
119 static void __init_##name(void); \
120 scope struct ast_threadstorage name = { \
121  .once = AST_PTHREAD_ONCE_INIT, \
122  .key_init = __init_##name, \
123  .custom_init = c_init, \
124 }; \
125 static void __init_##name(void) \
126 { \
127  pthread_key_create(&(name).key, c_cleanup); \
128 }
129 #else /* defined(DEBUG_THREADLOCALS) */
130 #define AST_THREADSTORAGE_CUSTOM_SCOPE(name, c_init, c_cleanup, scope) \
131 static void __init_##name(void); \
132 scope struct ast_threadstorage name = { \
133  .once = AST_PTHREAD_ONCE_INIT, \
134  .key_init = __init_##name, \
135  .custom_init = c_init, \
136 }; \
137 static void __cleanup_##name(void *data) \
138 { \
139  __ast_threadstorage_object_remove(data); \
140  c_cleanup(data); \
141 } \
142 static void __init_##name(void) \
143 { \
144  pthread_key_create(&(name).key, __cleanup_##name); \
145 }
146 #endif /* defined(DEBUG_THREADLOCALS) */
147 
148 /*!
149  * \brief Retrieve thread storage
150  *
151  * \param ts This is a pointer to the thread storage structure declared by using
152  * the AST_THREADSTORAGE macro. If declared with
153  * AST_THREADSTORAGE(my_buf), then this argument would be (&my_buf).
154  * \param init_size This is the amount of space to be allocated the first time
155  * this thread requests its data. Thus, this should be the size that the
156  * code accessing this thread storage is assuming the size to be.
157  *
158  * \return This function will return the thread local storage associated with
159  * the thread storage management variable passed as the first argument.
160  * The result will be NULL in the case of a memory allocation error.
161  *
162  * Example usage:
163  * \code
164  * AST_THREADSTORAGE(my_buf);
165  * #define MY_BUF_SIZE 128
166  * ...
167  * void my_func(const char *fmt, ...)
168  * {
169  * void *buf;
170  *
171  * if (!(buf = ast_threadstorage_get(&my_buf, MY_BUF_SIZE)))
172  * return;
173  * ...
174  * }
175  * \endcode
176  */
177 #if !defined(DEBUG_THREADLOCALS)
179 void *ast_threadstorage_get(struct ast_threadstorage *ts, size_t init_size),
180 {
181  void *buf;
182 
183  pthread_once(&ts->once, ts->key_init);
184  if (!(buf = pthread_getspecific(ts->key))) {
185  if (!(buf = ast_calloc(1, init_size))) {
186  return NULL;
187  }
188  if (ts->custom_init && ts->custom_init(buf)) {
189  ast_free(buf);
190  return NULL;
191  }
192  pthread_setspecific(ts->key, buf);
193  }
194 
195  return buf;
196 }
197 )
198 #else /* defined(DEBUG_THREADLOCALS) */
200 void *__ast_threadstorage_get(struct ast_threadstorage *ts, size_t init_size, const char *file, const char *function, unsigned int line),
201 {
202  void *buf;
203 
204  pthread_once(&ts->once, ts->key_init);
205  if (!(buf = pthread_getspecific(ts->key))) {
206  if (!(buf = ast_calloc(1, init_size))) {
207  return NULL;
208  }
209  if (ts->custom_init && ts->custom_init(buf)) {
210  ast_free(buf);
211  return NULL;
212  }
213  pthread_setspecific(ts->key, buf);
214  __ast_threadstorage_object_add(buf, init_size, file, function, line);
215  }
216 
217  return buf;
218 }
219 )
220 
221 #define ast_threadstorage_get(ts, init_size) __ast_threadstorage_get(ts, init_size, __FILE__, __PRETTY_FUNCTION__, __LINE__)
222 #endif /* defined(DEBUG_THREADLOCALS) */
223 
224 /*!
225  * \brief Retrieve a raw pointer from threadstorage.
226  * \param ts Threadstorage object to operate on.
227  *
228  * \return A pointer associated with the current thread, NULL
229  * if no pointer is associated yet.
230  *
231  * \note This should only be used on threadstorage declared
232  * by AST_THREADSTORAGE_RAW unless you really know what
233  * you are doing.
234  */
237 {
238  pthread_once(&ts->once, ts->key_init);
239  return pthread_getspecific(ts->key);
240 }
241 )
242 
243 /*!
244  * \brief Set a raw pointer from threadstorage.
245  * \param ts Threadstorage object to operate on.
246  *
247  * \retval 0 Success
248  * \retval non-zero Failure
249  *
250  * \note This should only be used on threadstorage declared
251  * by AST_THREADSTORAGE_RAW unless you really know what
252  * you are doing.
253  */
255 int ast_threadstorage_set_ptr(struct ast_threadstorage *ts, void *ptr),
256 {
257  pthread_once(&ts->once, ts->key_init);
258  return pthread_setspecific(ts->key, ptr);
259 }
260 )
261 
262 #endif /* ASTERISK_THREADSTORAGE_H */
void * ast_threadstorage_get(struct ast_threadstorage *ts, size_t init_size)
Retrieve thread storage.
char buf[BUFSIZE]
Definition: eagi_proxy.c:66
data for a thread locally stored variable
Definition: threadstorage.h:56
int(* custom_init)(void *)
Definition: threadstorage.h:60
#define NULL
Definition: resample.c:96
Utility functions.
pthread_once_t once
Definition: threadstorage.h:57
int ast_threadstorage_set_ptr(struct ast_threadstorage *ts, void *ptr)
Set a raw pointer from threadstorage.
Inlinable API function macro.
pthread_key_t key
Definition: threadstorage.h:58
static int len(struct ast_channel *chan, const char *cmd, char *data, char *buf, size_t buflen)
#define ast_free(a)
Definition: astmm.h:182
#define ast_calloc(num, len)
A wrapper for calloc()
Definition: astmm.h:204
void * ast_threadstorage_get_ptr(struct ast_threadstorage *ts)
Retrieve a raw pointer from threadstorage.
void(* key_init)(void)
Definition: threadstorage.h:59
#define AST_INLINE_API(hdr, body)
Definition: inline_api.h:54