threadstorage.h File Reference

Definitions to aid in the use of thread local storage. More...

#include "asterisk/utils.h"
#include "asterisk/inline_api.h"

Include dependency graph for threadstorage.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	ast_threadstorage
	data for a thread locally stored variable More...

Macros
#define	AST_PTHREAD_ONCE_INIT   PTHREAD_ONCE_INIT
#define	AST_THREADSTORAGE(name)    AST_THREADSTORAGE_CUSTOM_SCOPE(name, NULL, ast_free_ptr, static)
	Define a thread storage variable.
#define	AST_THREADSTORAGE_CUSTOM(a, b, c)   AST_THREADSTORAGE_CUSTOM_SCOPE(a,b,c,static)
	Define a thread storage variable, with custom initialization and cleanup.
#define	AST_THREADSTORAGE_CUSTOM_SCOPE(name, c_init, c_cleanup, scope)
#define	AST_THREADSTORAGE_EXTERNAL(name)    extern struct ast_threadstorage name
#define	AST_THREADSTORAGE_PUBLIC(name)    AST_THREADSTORAGE_CUSTOM_SCOPE(name, NULL, ast_free_ptr,)
#define	AST_THREADSTORAGE_RAW(name)    AST_THREADSTORAGE_CUSTOM_SCOPE(name, NULL, THREADSTORAGE_RAW_CLEANUP,)
#define	THREADSTORAGE_RAW_CLEANUP   NULL

Functions
void *	ast_threadstorage_get (struct ast_threadstorage *ts, size_t init_size)
	Retrieve thread storage.
void *	ast_threadstorage_get_ptr (struct ast_threadstorage *ts)
	Retrieve a raw pointer from threadstorage.
int	ast_threadstorage_set_ptr (struct ast_threadstorage *ts, void *ptr)
	Set a raw pointer from threadstorage.

Detailed Description

Definitions to aid in the use of thread local storage.

Author

Russell Bryant russe.nosp@m.ll@d.nosp@m.igium.nosp@m..com

• The Asterisk Thread Storage API

Definition in file threadstorage.h.

Macro Definition Documentation

AST_PTHREAD_ONCE_INIT

#define AST_PTHREAD_ONCE_INIT   PTHREAD_ONCE_INIT

Definition at line 116 of file threadstorage.h.

AST_THREADSTORAGE

#define AST_THREADSTORAGE

(

name

)

AST_THREADSTORAGE_CUSTOM_SCOPE(name, NULL, ast_free_ptr, static)

Define a thread storage variable.

Parameters

name	The name of the thread storage object

This macro would be used to declare an instance of thread storage in a file.

Example usage:

AST_THREADSTORAGE(my_buf);

Definition at line 86 of file threadstorage.h.

                               { PTHREAD_ONCE_INIT }
#else
# define AST_PTHREAD_ONCE_INIT PTHREAD_ONCE_INIT
#endif
 
#if !defined(DEBUG_THREADLOCALS)
#define AST_THREADSTORAGE_CUSTOM_SCOPE(name, c_init, c_cleanup, scope)  \
static void __init_##name(void);                \
scope struct ast_threadstorage name = {         \
    .once = AST_PTHREAD_ONCE_INIT,              \
    .key_init = __init_##name,                  \
    .custom_init = c_init,                      \
};                                              \
static void __init_##name(void)                 \
{                                               \
    pthread_key_create(&(name).key, c_cleanup); \
}
#else /* defined(DEBUG_THREADLOCALS) */
#define AST_THREADSTORAGE_CUSTOM_SCOPE(name, c_init, c_cleanup, scope) \
static void __init_##name(void);                \
scope struct ast_threadstorage name = {         \
    .once = AST_PTHREAD_ONCE_INIT,              \
    .key_init = __init_##name,                  \
    .custom_init = c_init,                      \
};                                              \
static void __cleanup_##name(void *data)        \
{                                               \
    __ast_threadstorage_object_remove(data);    \
    c_cleanup(data);                            \
}                                               \
static void __init_##name(void)                 \
{                                               \
    pthread_key_create(&(name).key, __cleanup_##name); \
}
#endif /* defined(DEBUG_THREADLOCALS) */
 
/*!
 * \brief Retrieve thread storage
 *
 * \param ts This is a pointer to the thread storage structure declared by using
 *      the AST_THREADSTORAGE macro.  If declared with
 *      AST_THREADSTORAGE(my_buf), then this argument would be (&my_buf).
 * \param init_size This is the amount of space to be allocated the first time
 *      this thread requests its data. Thus, this should be the size that the
 *      code accessing this thread storage is assuming the size to be.
 *
 * \return This function will return the thread local storage associated with
 *         the thread storage management variable passed as the first argument.
 *         The result will be NULL in the case of a memory allocation error.
 *
 * Example usage:
 * \code
 * AST_THREADSTORAGE(my_buf);
 * #define MY_BUF_SIZE   128
 * ...
 * void my_func(const char *fmt, ...)
 * {
 *      void *buf;
 *
 *      if (!(buf = ast_threadstorage_get(&my_buf, MY_BUF_SIZE)))
 *           return;
 *      ...
 * }
 * \endcode
 */
#if !defined(DEBUG_THREADLOCALS)
AST_INLINE_API(
void *ast_threadstorage_get(struct ast_threadstorage *ts, size_t init_size),
{
    void *buf;
 
    pthread_once(&ts->once, ts->key_init);
    if (!(buf = pthread_getspecific(ts->key))) {
        if (!(buf = ast_calloc(1, init_size))) {
            return NULL;
        }
        if (ts->custom_init && ts->custom_init(buf)) {
            ast_free(buf);
            return NULL;
        }
        pthread_setspecific(ts->key, buf);
    }
 
    return buf;
}
)
#else /* defined(DEBUG_THREADLOCALS) */
AST_INLINE_API(
void *__ast_threadstorage_get(struct ast_threadstorage *ts, size_t init_size, const char *file, const char *function, unsigned int line),
{
    void *buf;
 
    pthread_once(&ts->once, ts->key_init);
    if (!(buf = pthread_getspecific(ts->key))) {
        if (!(buf = ast_calloc(1, init_size))) {
            return NULL;
        }
        if (ts->custom_init && ts->custom_init(buf)) {
            ast_free(buf);
            return NULL;
        }
        pthread_setspecific(ts->key, buf);
        __ast_threadstorage_object_add(buf, init_size, file, function, line);
    }
 
    return buf;
}
)
 
#define ast_threadstorage_get(ts, init_size) __ast_threadstorage_get(ts, init_size, __FILE__, __PRETTY_FUNCTION__, __LINE__)
#endif /* defined(DEBUG_THREADLOCALS) */
 
/*!
 * \brief Retrieve a raw pointer from threadstorage.
 * \param ts Threadstorage object to operate on.
 *
 * \return A pointer associated with the current thread, NULL
 * if no pointer is associated yet.
 *
 * \note This should only be used on threadstorage declared
 * by AST_THREADSTORAGE_RAW unless you really know what
 * you are doing.
 */
AST_INLINE_API(
void *ast_threadstorage_get_ptr(struct ast_threadstorage *ts),
{
    pthread_once(&ts->once, ts->key_init);
    return pthread_getspecific(ts->key);
}
)
 
/*!
 * \brief Set a raw pointer from threadstorage.
 * \param ts Threadstorage object to operate on.
 * \param ptr
 *
 * \retval 0 Success
 * \retval non-zero Failure
 *
 * \note This should only be used on threadstorage declared
 * by AST_THREADSTORAGE_RAW unless you really know what
 * you are doing.
 */
AST_INLINE_API(
int ast_threadstorage_set_ptr(struct ast_threadstorage *ts, void *ptr),
{
    pthread_once(&ts->once, ts->key_init);
    return pthread_setspecific(ts->key, ptr);
}
)
 
#endif /* ASTERISK_THREADSTORAGE_H */

AST_THREADSTORAGE_CUSTOM

#define AST_THREADSTORAGE_CUSTOM	(		a,
			b,
			c
	)		AST_THREADSTORAGE_CUSTOM_SCOPE(a,b,c,static)

Define a thread storage variable, with custom initialization and cleanup.

Parameters

a	The name of the thread storage object
b	This is a custom function that will be called after each thread specific object is allocated, with the allocated block of memory passed as the argument.
c	This is a custom function that will be called instead of ast_free when the thread goes away. Note that if this is used, it MUST call free on the allocated memory.

Example usage:

AST_THREADSTORAGE_CUSTOM(my_buf, my_init, my_cleanup);

Definition at line 111 of file threadstorage.h.

AST_THREADSTORAGE_CUSTOM_SCOPE

#define AST_THREADSTORAGE_CUSTOM_SCOPE	(		name,
			c_init,
			c_cleanup,
			scope
	)

Definition at line 120 of file threadstorage.h.

                                      {         \
    .once = AST_PTHREAD_ONCE_INIT,              \
    .key_init = __init_##name,                  \
    .custom_init = c_init,                      \
};                                              \
static void __init_##name(void)                 \
{                                               \
    pthread_key_create(&(name).key, c_cleanup); \
}

AST_THREADSTORAGE_EXTERNAL

#define AST_THREADSTORAGE_EXTERNAL

(

name

)

extern struct ast_threadstorage name

Definition at line 90 of file threadstorage.h.

AST_THREADSTORAGE_PUBLIC

#define AST_THREADSTORAGE_PUBLIC

(

name

)

AST_THREADSTORAGE_CUSTOM_SCOPE(name, NULL, ast_free_ptr,)

Definition at line 88 of file threadstorage.h.

AST_THREADSTORAGE_RAW

#define AST_THREADSTORAGE_RAW

(

name

)

AST_THREADSTORAGE_CUSTOM_SCOPE(name, NULL, THREADSTORAGE_RAW_CLEANUP,)

Definition at line 92 of file threadstorage.h.

THREADSTORAGE_RAW_CLEANUP

#define THREADSTORAGE_RAW_CLEANUP   NULL

Definition at line 71 of file threadstorage.h.

Function Documentation

ast_threadstorage_get()

void * ast_threadstorage_get ( struct ast_threadstorage *  ts, size_t  init_size  )

inline

Retrieve thread storage.

Parameters

ts	This is a pointer to the thread storage structure declared by using the AST_THREADSTORAGE macro. If declared with AST_THREADSTORAGE(my_buf), then this argument would be (&my_buf).
init_size	This is the amount of space to be allocated the first time this thread requests its data. Thus, this should be the size that the code accessing this thread storage is assuming the size to be.

Returns

This function will return the thread local storage associated with the thread storage management variable passed as the first argument. The result will be NULL in the case of a memory allocation error.

Example usage:

AST_THREADSTORAGE(my_buf);
#define MY_BUF_SIZE   128
...
void my_func(const char *fmt, ...)
{
     void *buf;
 
     if (!(buf = ast_threadstorage_get(&my_buf, MY_BUF_SIZE)))
          return;
     ...
}

Definition at line 199 of file threadstorage.h.

References ast_calloc, ast_free, buf, ast_threadstorage::custom_init, ast_threadstorage::key, ast_threadstorage::key_init, NULL, and ast_threadstorage::once.

Referenced by __ast_frdup(), __frame_free(), acf_curl_helper(), ast_callid_threadassoc_add(), ast_callid_threadassoc_change(), ast_callid_threadassoc_remove(), ast_channel_internal_errno(), ast_channel_internal_errno_set(), ast_frame_header_new(), ast_inet_ntoa(), ast_read_threadstorage_callid(), ast_sched_del_nonrunning(), ast_sip_thread_is_servant(), ast_state2str(), ast_term_color(), ast_thread_inhibit_escalations(), ast_thread_inhibit_escalations_swap(), ast_thread_is_user_interface(), ast_thread_user_interface_set(), ast_verb_console_get(), ast_verb_console_register(), ast_verb_console_set(), ast_verb_console_unregister(), callid_set_chanloggroup(), chan_pjsip_get_uniqueid(), console_print(), dialplan_handle_msg_cb(), dummy_start(), find_or_create_temporary_state(), find_temporary_state(), get_auth(), get_callid_group(), iax_frame_free(), iax_frame_new(), idle_sched_init_pj_thread(), is_passthru_update(), pbx_substitute_variables_helper_full_location(), process_text_line(), registration_client_send(), remove_auth(), remove_temporary_state(), set_passthru_update(), sip_outbound_registration_response_cb(), sip_thread_start(), store_auth(), and thread_inhibits_escalations().

ast_threadstorage_get_ptr()

void * ast_threadstorage_get_ptr ( struct ast_threadstorage *  ts )

inline

Retrieve a raw pointer from threadstorage.

Parameters

ts	Threadstorage object to operate on.

Returns

A pointer associated with the current thread, NULL if no pointer is associated yet.

Note

This should only be used on threadstorage declared by AST_THREADSTORAGE_RAW unless you really know what you are doing.

Definition at line 243 of file threadstorage.h.

References ast_threadstorage::key, ast_threadstorage::key_init, and ast_threadstorage::once.

Referenced by ast_channel_get_intercept_mode(), ast_cli_completion_add(), ast_cli_completion_vector(), ast_log_safe(), ast_taskpool_get_current(), ast_taskpool_serializer_get_current(), and ast_threadpool_serializer_get_current().

ast_threadstorage_set_ptr()

int ast_threadstorage_set_ptr ( struct ast_threadstorage *  ts, void *  ptr  )

inline

Set a raw pointer from threadstorage.

Parameters

ts	Threadstorage object to operate on.
ptr

Return values

0	Success
non-zero	Failure

Note

This should only be used on threadstorage declared by AST_THREADSTORAGE_RAW unless you really know what you are doing.

Definition at line 263 of file threadstorage.h.

Referenced by ast_cli_completion_vector(), ast_log_safe(), ast_taskpool_serializer_push_wait(), channel_set_intercept_mode(), cli_completion_vector_add(), execute_tasks(), execute_tasks(), and taskpool_taskprocessor_start().