move the dynamic string support in a better place i.e. string.h
[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 <pthread.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  */
58 struct ast_threadstorage {
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 /*!
66  * \brief Define a thread storage variable
67  *
68  * \arg name The name of the thread storage object
69  *
70  * This macro would be used to declare an instance of thread storage in a file.
71  *
72  * Example usage:
73  * \code
74  * AST_THREADSTORAGE(my_buf);
75  * \endcode
76  */
77 #define AST_THREADSTORAGE(name) \
78         AST_THREADSTORAGE_CUSTOM(name, NULL, ast_free) 
79
80 /*!
81  * \brief Define a thread storage variable, with custom initialization and cleanup
82  *
83  * \arg name The name of the thread storage object
84  * \arg init This is a custom function that will be called after each thread specific
85  *           object is allocated, with the allocated block of memory passed
86  *           as the argument.
87  * \arg cleanup This is a custom function that will be called instead of ast_free
88  *              when the thread goes away.  Note that if this is used, it *MUST*
89  *              call free on the allocated memory.
90  *
91  * Example usage:
92  * \code
93  * AST_THREADSTORAGE_CUSTOM(my_buf, my_init, my_cleanup);
94  * \endcode
95  */
96 #define AST_THREADSTORAGE_CUSTOM(name, c_init, c_cleanup) \
97 static void init_##name(void);                            \
98 static struct ast_threadstorage name = {                  \
99         .once = PTHREAD_ONCE_INIT,                        \
100         .key_init = init_##name,                          \
101         .custom_init = c_init,                            \
102 };                                                        \
103 static void init_##name(void)                             \
104 {                                                         \
105         pthread_key_create(&(name).key, c_cleanup);       \
106 }
107
108 /*!
109  * \brief Retrieve thread storage
110  *
111  * \arg ts This is a pointer to the thread storage structure declared by using
112  *      the AST_THREADSTORAGE macro.  If declared with 
113  *      AST_THREADSTORAGE(my_buf, my_buf_init), then this argument would be 
114  *      (&my_buf).
115  * \arg init_size This is the amount of space to be allocated the first time
116  *      this thread requests its data. Thus, this should be the size that the
117  *      code accessing this thread storage is assuming the size to be.
118  *
119  * \return This function will return the thread local storage associated with
120  *         the thread storage management variable passed as the first argument.
121  *         The result will be NULL in the case of a memory allocation error.
122  *
123  * Example usage:
124  * \code
125  * AST_THREADSTORAGE(my_buf, my_buf_init);
126  * #define MY_BUF_SIZE   128
127  * ...
128  * void my_func(const char *fmt, ...)
129  * {
130  *      void *buf;
131  *
132  *      if (!(buf = ast_threadstorage_get(&my_buf, MY_BUF_SIZE)))
133  *           return;
134  *      ...
135  * }
136  * \endcode
137  */
138 AST_INLINE_API(
139 void *ast_threadstorage_get(struct ast_threadstorage *ts, size_t init_size),
140 {
141         void *buf;
142
143         pthread_once(&ts->once, ts->key_init);
144         if (!(buf = pthread_getspecific(ts->key))) {
145                 if (!(buf = ast_calloc(1, init_size)))
146                         return NULL;
147                 if (ts->custom_init && ts->custom_init(buf)) {
148                         free(buf);
149                         return NULL;
150                 }
151                 pthread_setspecific(ts->key, buf);
152         }
153
154         return buf;
155 }
156 )
157
158 void __ast_threadstorage_cleanup(void *);
159
160 #endif /* ASTERISK_THREADSTORAGE_H */