Asterisk - The Open Source Telephony Project  GIT-master-a24979a
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 <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
21  *
22  * \brief Definitions to aid in the use of thread local storage
23  *
24  * \author Russell Bryant <russell@digium.com>
25  *
26  * \arg \ref AstThreadStorage
27  */
28 
29 /*!
30  * \page AstThreadStorage The Asterisk Thread Storage API
31  *
32  *
33  * The POSIX threads (pthreads) API provides the ability to define thread
34  * specific data. The functions and structures defined here are intended
35  * to centralize the code that is commonly used when using thread local
36  * storage.
37  *
38  * The motivation for using this code in Asterisk is for situations where
39  * storing data on a thread-specific basis can provide some amount of
40  * performance benefit. For example, there are some call types in Asterisk
41  * where ast_frame structures must be allocated very rapidly (easily 50, 100,
42  * 200 times a second). Instead of doing the equivalent of that many calls
43  * to malloc() and free() per second, thread local storage is used to keep a
44  * list of unused frame structures so that they can be continuously reused.
45  *
46  * - \ref threadstorage.h
47  */
48 
49 #ifndef ASTERISK_THREADSTORAGE_H
50 #define ASTERISK_THREADSTORAGE_H
51 
52 #include "asterisk/utils.h"
53 #include "asterisk/inline_api.h"
54 
55 /*!
56  * \brief data for a thread locally stored variable
57  */
59  pthread_once_t once; /*!< Ensure that the key is only initialized by one thread */
60  pthread_key_t key; /*!< The key used to retrieve this thread's data */
61  void (*key_init)(void); /*!< The function that initializes the key */
62  int (*custom_init)(void *); /*!< Custom initialization function specific to the object */
63 };
64 
65 #if defined(DEBUG_THREADLOCALS)
66 void __ast_threadstorage_object_add(void *key, size_t len, const char *file, const char *function, unsigned int line);
67 void __ast_threadstorage_object_remove(void *key);
68 void __ast_threadstorage_object_replace(void *key_old, void *key_new, size_t len);
69 #define THREADSTORAGE_RAW_CLEANUP(v) {}
70 #else
71 #define THREADSTORAGE_RAW_CLEANUP NULL
72 #endif /* defined(DEBUG_THREADLOCALS) */
73 
74 /*!
75  * \brief Define a thread storage variable
76  *
77  * \param name The name of the thread storage object
78  *
79  * This macro would be used to declare an instance of thread storage in a file.
80  *
81  * Example usage:
82  * \code
83  * AST_THREADSTORAGE(my_buf);
84  * \endcode
85  */
86 #define AST_THREADSTORAGE(name) \
87  AST_THREADSTORAGE_CUSTOM_SCOPE(name, NULL, ast_free_ptr, static)
88 #define AST_THREADSTORAGE_PUBLIC(name) \
89  AST_THREADSTORAGE_CUSTOM_SCOPE(name, NULL, ast_free_ptr,)
90 #define AST_THREADSTORAGE_EXTERNAL(name) \
91  extern struct ast_threadstorage name
92 #define AST_THREADSTORAGE_RAW(name) \
93  AST_THREADSTORAGE_CUSTOM_SCOPE(name, NULL, THREADSTORAGE_RAW_CLEANUP,)
94 
95 /*!
96  * \brief Define a thread storage variable, with custom initialization and cleanup
97  *
98  * \param a The name of the thread storage object
99  * \param b This is a custom function that will be called after each thread specific
100  * object is allocated, with the allocated block of memory passed
101  * as the argument.
102  * \param c This is a custom function that will be called instead of ast_free
103  * when the thread goes away. Note that if this is used, it *MUST*
104  * call free on the allocated memory.
105  *
106  * Example usage:
107  * \code
108  * AST_THREADSTORAGE_CUSTOM(my_buf, my_init, my_cleanup);
109  * \endcode
110  */
111 #define AST_THREADSTORAGE_CUSTOM(a,b,c) AST_THREADSTORAGE_CUSTOM_SCOPE(a,b,c,static)
112 
113 #if defined(PTHREAD_ONCE_INIT_NEEDS_BRACES)
114 # define AST_PTHREAD_ONCE_INIT { PTHREAD_ONCE_INIT }
115 #else
116 # define AST_PTHREAD_ONCE_INIT PTHREAD_ONCE_INIT
117 #endif
118 
119 #if !defined(DEBUG_THREADLOCALS)
120 #define AST_THREADSTORAGE_CUSTOM_SCOPE(name, c_init, c_cleanup, scope) \
121 static void __init_##name(void); \
122 scope struct ast_threadstorage name = { \
123  .once = AST_PTHREAD_ONCE_INIT, \
124  .key_init = __init_##name, \
125  .custom_init = c_init, \
126 }; \
127 static void __init_##name(void) \
128 { \
129  pthread_key_create(&(name).key, c_cleanup); \
130 }
131 #else /* defined(DEBUG_THREADLOCALS) */
132 #define AST_THREADSTORAGE_CUSTOM_SCOPE(name, c_init, c_cleanup, scope) \
133 static void __init_##name(void); \
134 scope struct ast_threadstorage name = { \
135  .once = AST_PTHREAD_ONCE_INIT, \
136  .key_init = __init_##name, \
137  .custom_init = c_init, \
138 }; \
139 static void __cleanup_##name(void *data) \
140 { \
141  __ast_threadstorage_object_remove(data); \
142  c_cleanup(data); \
143 } \
144 static void __init_##name(void) \
145 { \
146  pthread_key_create(&(name).key, __cleanup_##name); \
147 }
148 #endif /* defined(DEBUG_THREADLOCALS) */
149 
150 /*!
151  * \brief Retrieve thread storage
152  *
153  * \param ts This is a pointer to the thread storage structure declared by using
154  * the AST_THREADSTORAGE macro. If declared with
155  * AST_THREADSTORAGE(my_buf), then this argument would be (&my_buf).
156  * \param init_size This is the amount of space to be allocated the first time
157  * this thread requests its data. Thus, this should be the size that the
158  * code accessing this thread storage is assuming the size to be.
159  *
160  * \return This function will return the thread local storage associated with
161  * the thread storage management variable passed as the first argument.
162  * The result will be NULL in the case of a memory allocation error.
163  *
164  * Example usage:
165  * \code
166  * AST_THREADSTORAGE(my_buf);
167  * #define MY_BUF_SIZE 128
168  * ...
169  * void my_func(const char *fmt, ...)
170  * {
171  * void *buf;
172  *
173  * if (!(buf = ast_threadstorage_get(&my_buf, MY_BUF_SIZE)))
174  * return;
175  * ...
176  * }
177  * \endcode
178  */
179 #if !defined(DEBUG_THREADLOCALS)
181 void *ast_threadstorage_get(struct ast_threadstorage *ts, size_t init_size),
182 {
183  void *buf;
184 
185  pthread_once(&ts->once, ts->key_init);
186  if (!(buf = pthread_getspecific(ts->key))) {
187  if (!(buf = ast_calloc(1, init_size))) {
188  return NULL;
189  }
190  if (ts->custom_init && ts->custom_init(buf)) {
191  ast_free(buf);
192  return NULL;
193  }
194  pthread_setspecific(ts->key, buf);
195  }
196 
197  return buf;
198 }
199 )
200 #else /* defined(DEBUG_THREADLOCALS) */
202 void *__ast_threadstorage_get(struct ast_threadstorage *ts, size_t init_size, const char *file, const char *function, unsigned int line),
203 {
204  void *buf;
205 
206  pthread_once(&ts->once, ts->key_init);
207  if (!(buf = pthread_getspecific(ts->key))) {
208  if (!(buf = ast_calloc(1, init_size))) {
209  return NULL;
210  }
211  if (ts->custom_init && ts->custom_init(buf)) {
212  ast_free(buf);
213  return NULL;
214  }
215  pthread_setspecific(ts->key, buf);
216  __ast_threadstorage_object_add(buf, init_size, file, function, line);
217  }
218 
219  return buf;
220 }
221 )
222 
223 #define ast_threadstorage_get(ts, init_size) __ast_threadstorage_get(ts, init_size, __FILE__, __PRETTY_FUNCTION__, __LINE__)
224 #endif /* defined(DEBUG_THREADLOCALS) */
225 
226 /*!
227  * \brief Retrieve a raw pointer from threadstorage.
228  * \param ts Threadstorage object to operate on.
229  *
230  * \return A pointer associated with the current thread, NULL
231  * if no pointer is associated yet.
232  *
233  * \note This should only be used on threadstorage declared
234  * by AST_THREADSTORAGE_RAW unless you really know what
235  * you are doing.
236  */
239 {
240  pthread_once(&ts->once, ts->key_init);
241  return pthread_getspecific(ts->key);
242 }
243 )
244 
245 /*!
246  * \brief Set a raw pointer from threadstorage.
247  * \param ts Threadstorage object to operate on.
248  * \param ptr
249  *
250  * \retval 0 Success
251  * \retval non-zero Failure
252  *
253  * \note This should only be used on threadstorage declared
254  * by AST_THREADSTORAGE_RAW unless you really know what
255  * you are doing.
256  */
258 int ast_threadstorage_set_ptr(struct ast_threadstorage *ts, void *ptr),
259 {
260  pthread_once(&ts->once, ts->key_init);
261  return pthread_setspecific(ts->key, ptr);
262 }
263 )
264 
265 #endif /* ASTERISK_THREADSTORAGE_H */
#define ast_free(a)
Definition: astmm.h:180
#define ast_calloc(num, len)
A wrapper for calloc()
Definition: astmm.h:202
char buf[BUFSIZE]
Definition: eagi_proxy.c:66
static int len(struct ast_channel *chan, const char *cmd, char *data, char *buf, size_t buflen)
Inlinable API function macro.
#define AST_INLINE_API(hdr, body)
Definition: inline_api.h:54
#define NULL
Definition: resample.c:96
data for a thread locally stored variable
Definition: threadstorage.h:58
int(* custom_init)(void *)
Definition: threadstorage.h:62
pthread_key_t key
Definition: threadstorage.h:60
pthread_once_t once
Definition: threadstorage.h:59
void(* key_init)(void)
Definition: threadstorage.h:61
int ast_threadstorage_set_ptr(struct ast_threadstorage *ts, void *ptr)
Set a raw pointer from threadstorage.
void * ast_threadstorage_get_ptr(struct ast_threadstorage *ts)
Retrieve a raw pointer from threadstorage.
void * ast_threadstorage_get(struct ast_threadstorage *ts, size_t init_size)
Retrieve thread storage.
Utility functions.