2 * Asterisk -- An open source telephony toolkit.
4 * Copyright (C) 2006, Digium, Inc.
6 * Russell Bryant <russell@digium.com>
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.
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.
20 * \file threadstorage.h
21 * \author Russell Bryant <russell@digium.com>
23 * \brief Definitions to aid in the use of thread local storage
26 #ifndef ASTERISK_THREADSTORAGE_H
27 #define ASTERISK_THREADSTORAGE_H
31 #include "asterisk/utils.h"
32 #include "asterisk/inline_api.h"
35 * \brief data for a thread locally stored variable
37 struct ast_threadstorage
{
38 /*! Ensure that the key is only initialized by one thread */
40 /*! The key used to retrieve this thread's data */
42 /*! The function that initializes the key */
43 void (*key_init
)(void);
47 #define THREADSTORAGE_ONCE_INIT {PTHREAD_ONCE_INIT}
49 #define THREADSTORAGE_ONCE_INIT PTHREAD_ONCE_INIT
52 #if defined(DEBUG_THREADLOCALS)
53 void __ast_threadstorage_object_add(void *key
, size_t len
, const char *file
, const char *function
, unsigned int line
);
54 void __ast_threadstorage_object_remove(void *key
);
55 void __ast_threadstorage_object_replace(void *key_old
, void *key_new
, size_t len
);
56 #endif /* defined(DEBUG_THREADLOCALS) */
59 * \brief Define a thread storage variable
61 * \arg name The name of the thread storage
62 * \arg name_init This is a name used to create the function that gets called
63 * to initialize this thread storage. It can be anything since it will not
64 * be referred to anywhere else
66 * This macro would be used to declare an instance of thread storage in a file.
70 * AST_THREADSTORAGE(my_buf, my_buf_init);
73 #define AST_THREADSTORAGE(name, name_init) \
74 AST_THREADSTORAGE_CUSTOM(name, name_init, ast_free)
76 #if !defined(DEBUG_THREADLOCALS)
77 #define AST_THREADSTORAGE_CUSTOM(name, name_init, cleanup) \
78 static void name_init(void); \
79 static struct ast_threadstorage name = { \
80 .once = THREADSTORAGE_ONCE_INIT, \
81 .key_init = name_init, \
83 static void name_init(void) \
85 pthread_key_create(&(name).key, cleanup); \
87 #else /* defined(DEBUG_THREADLOCALS) */
88 #define AST_THREADSTORAGE_CUSTOM(name, name_init, cleanup) \
89 static void name_init(void); \
90 static struct ast_threadstorage name = { \
91 .once = THREADSTORAGE_ONCE_INIT, \
92 .key_init = name_init, \
94 static void __cleanup_##name(void *data) \
96 __ast_threadstorage_object_remove(data); \
99 static void name_init(void) \
101 pthread_key_create(&(name).key, __cleanup_##name); \
103 #endif /* defined(DEBUG_THREADLOCALS) */
106 * \brief Retrieve thread storage
108 * \arg ts This is a pointer to the thread storage structure declared by using
109 * the AST_THREADSTORAGE macro. If declared with
110 * AST_THREADSTORAGE(my_buf, my_buf_init), then this argument would be
112 * \arg init_size This is the amount of space to be allocated the first time
113 * this thread requests its data. Thus, this should be the size that the
114 * code accessing this thread storage is assuming the size to be.
116 * \return This function will return the thread local storage associated with
117 * the thread storage management variable passed as the first argument.
118 * The result will be NULL in the case of a memory allocation error.
122 * AST_THREADSTORAGE(my_buf, my_buf_init);
123 * #define MY_BUF_SIZE 128
125 * void my_func(const char *fmt, ...)
129 * if (!(buf = ast_threadstorage_get(&my_buf, MY_BUF_SIZE)))
135 #if !defined(DEBUG_THREADLOCALS)
137 void *ast_threadstorage_get(struct ast_threadstorage
*ts
, size_t init_size
),
141 pthread_once(&ts
->once
, ts
->key_init
);
142 if (!(buf
= pthread_getspecific(ts
->key
))) {
143 if (!(buf
= ast_calloc(1, init_size
)))
145 pthread_setspecific(ts
->key
, buf
);
151 #else /* defined(DEBUG_THREADLOCALS) */
153 void *__ast_threadstorage_get(struct ast_threadstorage
*ts
, size_t init_size
, const char *file
, const char *function
, unsigned int line
),
157 pthread_once(&ts
->once
, ts
->key_init
);
158 if (!(buf
= pthread_getspecific(ts
->key
))) {
159 if (!(buf
= ast_calloc(1, init_size
)))
161 pthread_setspecific(ts
->key
, buf
);
162 __ast_threadstorage_object_add(ts
->key
, init_size
, file
, function
, line
);
169 #define ast_threadstorage_get(ts, init_size) __ast_threadstorage_get(ts, init_size, __FILE__, __PRETTY_FUNCTION__, __LINE__)
170 #endif /* defined(DEBUG_THREADLOCALS) */
173 * \brief A dynamic length string
175 struct ast_dynamic_str
{
176 /* The current maximum length of the string */
178 /* The string buffer */
183 * \brief Create a dynamic length string
185 * \arg init_len This is the initial length of the string buffer
187 * \return This function returns a pointer to the dynamic string length. The
188 * result will be NULL in the case of a memory allocation error.
190 * /note The result of this function is dynamically allocated memory, and must
191 * be free()'d after it is no longer needed.
194 struct ast_dynamic_str
* attribute_malloc
ast_dynamic_str_create(size_t init_len
),
196 struct ast_dynamic_str
*buf
;
198 if (!(buf
= ast_calloc(1, sizeof(*buf
) + init_len
)))
208 * \brief Retrieve a thread locally stored dynamic string
210 * \arg ts This is a pointer to the thread storage structure declared by using
211 * the AST_THREADSTORAGE macro. If declared with
212 * AST_THREADSTORAGE(my_buf, my_buf_init), then this argument would be
214 * \arg init_len This is the initial length of the thread's dynamic string. The
215 * current length may be bigger if previous operations in this thread have
216 * caused it to increase.
218 * \return This function will return the thread locally storaged dynamic string
219 * associated with the thread storage management variable passed as the
221 * The result will be NULL in the case of a memory allocation error.
225 * AST_THREADSTORAGE(my_str, my_str_init);
226 * #define MY_STR_INIT_SIZE 128
228 * void my_func(const char *fmt, ...)
230 * struct ast_dynamic_str *buf;
232 * if (!(buf = ast_dynamic_str_thread_get(&my_str, MY_STR_INIT_SIZE)))
238 #if !defined(DEBUG_THREADLOCALS)
240 struct ast_dynamic_str
*ast_dynamic_str_thread_get(struct ast_threadstorage
*ts
,
243 struct ast_dynamic_str
*buf
;
245 if (!(buf
= ast_threadstorage_get(ts
, sizeof(*buf
) + init_len
)))
254 #else /* defined(DEBUG_THREADLOCALS) */
256 struct ast_dynamic_str
*__ast_dynamic_str_thread_get(struct ast_threadstorage
*ts
,
257 size_t init_len
, const char *file
, const char *function
, unsigned int line
),
259 struct ast_dynamic_str
*buf
;
261 if (!(buf
= __ast_threadstorage_get(ts
, sizeof(*buf
) + init_len
, file
, function
, line
)))
271 #define ast_dynamic_str_thread_get(ts, init_len) __ast_dynamic_str_thread_get(ts, init_len, __FILE__, __PRETTY_FUNCTION__, __LINE__)
272 #endif /* defined(DEBUG_THREADLOCALS) */
275 * \brief Error codes from ast_dynamic_str_thread_build_va()
278 /*! An error has occured and the contents of the dynamic string
280 AST_DYNSTR_BUILD_FAILED
= -1,
281 /*! The buffer size for the dynamic string had to be increased, and
282 * ast_dynamic_str_thread_build_va() needs to be called again after
283 * a va_end() and va_start().
285 AST_DYNSTR_BUILD_RETRY
= -2
289 * \brief Set a thread locally stored dynamic string from a va_list
291 * \arg buf This is the address of a pointer to an ast_dynamic_str which should
292 * have been retrieved using ast_dynamic_str_thread_get. It will need to
293 * be updated in the case that the buffer has to be reallocated to
294 * accomodate a longer string than what it currently has space for.
295 * \arg max_len This is the maximum length to allow the string buffer to grow
296 * to. If this is set to 0, then there is no maximum length.
297 * \arg ts This is a pointer to the thread storage structure declared by using
298 * the AST_THREADSTORAGE macro. If declared with
299 * AST_THREADSTORAGE(my_buf, my_buf_init), then this argument would be
301 * \arg fmt This is the format string (printf style)
302 * \arg ap This is the va_list
304 * \return The return value of this function is the same as that of the printf
305 * family of functions.
309 * AST_THREADSTORAGE(my_str, my_str_init);
310 * #define MY_STR_INIT_SIZE 128
312 * void my_func(const char *fmt, ...)
314 * struct ast_dynamic_str *buf;
317 * if (!(buf = ast_dynamic_str_thread_get(&my_str, MY_STR_INIT_SIZE)))
321 * ast_dynamic_str_thread_set_va(&buf, 0, &my_str, fmt, ap);
324 * printf("This is the string we just built: %s\n", buf->str);
329 #define ast_dynamic_str_thread_set_va(buf, max_len, ts, fmt, ap) \
332 while ((__res = ast_dynamic_str_thread_build_va(buf, max_len, \
333 ts, 0, fmt, ap)) == AST_DYNSTR_BUILD_RETRY) { \
341 * \brief Append to a thread local dynamic string using a va_list
343 * The arguments, return values, and usage of this are the same as those for
344 * ast_dynamic_str_thread_set_va(). However, instead of setting a new value
345 * for the string, this will append to the current value.
347 #define ast_dynamic_str_thread_append_va(buf, max_len, ts, fmt, ap) \
350 while ((__res = ast_dynamic_str_thread_build_va(buf, max_len, \
351 ts, 1, fmt, ap)) == AST_DYNSTR_BUILD_RETRY) { \
359 * \brief Core functionality of ast_dynamic_str_thread_(set|append)_va
361 * The arguments to this function are the same as those described for
362 * ast_dynamic_str_thread_set_va except for an addition argument, append.
363 * If append is non-zero, this will append to the current string instead of
366 int ast_dynamic_str_thread_build_va(struct ast_dynamic_str
**buf
, size_t max_len
,
367 struct ast_threadstorage
*ts
, int append
, const char *fmt
, va_list ap
);
370 * \brief Set a thread locally stored dynamic string using variable arguments
372 * \arg buf This is the address of a pointer to an ast_dynamic_str which should
373 * have been retrieved using ast_dynamic_str_thread_get. It will need to
374 * be updated in the case that the buffer has to be reallocated to
375 * accomodate a longer string than what it currently has space for.
376 * \arg max_len This is the maximum length to allow the string buffer to grow
377 * to. If this is set to 0, then there is no maximum length.
378 * \arg ts This is a pointer to the thread storage structure declared by using
379 * the AST_THREADSTORAGE macro. If declared with
380 * AST_THREADSTORAGE(my_buf, my_buf_init), then this argument would be
382 * \arg fmt This is the format string (printf style)
384 * \return The return value of this function is the same as that of the printf
385 * family of functions.
389 * AST_THREADSTORAGE(my_str, my_str_init);
390 * #define MY_STR_INIT_SIZE 128
392 * void my_func(int arg1, int arg2)
394 * struct ast_dynamic_str *buf;
397 * if (!(buf = ast_dynamic_str_thread_get(&my_str, MY_STR_INIT_SIZE)))
400 * ast_dynamic_str_thread_set(&buf, 0, &my_str, "arg1: %d arg2: %d\n",
403 * printf("This is the string we just built: %s\n", buf->str);
409 int __attribute__ ((format (printf
, 4, 5))) ast_dynamic_str_thread_set(
410 struct ast_dynamic_str
**buf
, size_t max_len
,
411 struct ast_threadstorage
*ts
, const char *fmt
, ...),
417 res
= ast_dynamic_str_thread_set_va(buf
, max_len
, ts
, fmt
, ap
);
425 * \brief Append to a thread local dynamic string
427 * The arguments, return values, and usage of this function are the same as
428 * ast_dynamic_str_thread_set(). However, instead of setting a new value for
429 * the string, this function appends to the current value.
432 int __attribute__ ((format (printf
, 4, 5))) ast_dynamic_str_thread_append(
433 struct ast_dynamic_str
**buf
, size_t max_len
,
434 struct ast_threadstorage
*ts
, const char *fmt
, ...),
440 res
= ast_dynamic_str_thread_append_va(buf
, max_len
, ts
, fmt
, ap
);
448 * \brief Set a dynamic string
450 * \arg buf This is the address of a pointer to an ast_dynamic_str. It will
451 * need to be updated in the case that the buffer has to be reallocated to
452 * accomodate a longer string than what it currently has space for.
453 * \arg max_len This is the maximum length to allow the string buffer to grow
454 * to. If this is set to 0, then there is no maximum length.
456 * \return The return value of this function is the same as that of the printf
457 * family of functions.
460 int __attribute__ ((format (printf
, 3, 4))) ast_dynamic_str_set(
461 struct ast_dynamic_str
**buf
, size_t max_len
,
462 const char *fmt
, ...),
468 res
= ast_dynamic_str_thread_set_va(buf
, max_len
, NULL
, fmt
, ap
);
476 * \brief Append to a dynatic string
478 * The arguments, return values, and usage of this function are the same as
479 * ast_dynamic_str_set(). However, this function appends to the string instead
480 * of setting a new value.
483 int __attribute__ ((format (printf
, 3, 4))) ast_dynamic_str_append(
484 struct ast_dynamic_str
**buf
, size_t max_len
,
485 const char *fmt
, ...),
491 res
= ast_dynamic_str_thread_append_va(buf
, max_len
, NULL
, fmt
, ap
);
498 #endif /* ASTERISK_THREADSTORAGE_H */