Thu Oct 8 21:57:58 2009

Asterisk developer's documentation


threadstorage.h File Reference

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

#include <pthread.h>
#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...

Defines

#define ast_dynamic_str_thread_append_va(buf, max_len, ts, fmt, ap)
 Append to a thread local dynamic string using a va_list.
#define ast_dynamic_str_thread_set_va(buf, max_len, ts, fmt, ap)
 Set a thread locally stored dynamic string from a va_list.
#define AST_THREADSTORAGE(name, name_init)   AST_THREADSTORAGE_CUSTOM(name, name_init, ast_free)
 Define a thread storage variable.
#define AST_THREADSTORAGE_CUSTOM(name, name_init, cleanup)
#define THREADSTORAGE_ONCE_INIT   PTHREAD_ONCE_INIT

Functions

 ast_dynamic_str_thread_append (struct ast_dynamic_str **buf, size_t max_len, struct ast_threadstorage *ts, const char *fmt,...)
int ast_dynamic_str_thread_build_va (struct ast_dynamic_str **buf, size_t max_len, struct ast_threadstorage *ts, int append, const char *fmt, va_list ap)
 Core functionality of ast_dynamic_str_thread_(set|append)_va.
 AST_INLINE_API (int __attribute__((format(printf, 4, 5))) ast_dynamic_str_thread_set(struct ast_dynamic_str **buf, size_t max_len, struct ast_threadstorage *ts, const char *fmt,...),{int res;va_list ap;va_start(ap, fmt);res=ast_dynamic_str_thread_set_va(buf, max_len, ts, fmt, ap);va_end(ap);return res;}) AST_INLINE_API(int __attribute__((format(printf
 Set a thread locally stored dynamic string using variable arguments.
 AST_INLINE_API (struct ast_dynamic_str *attribute_malloc ast_dynamic_str_create(size_t init_len),{struct ast_dynamic_str *buf;if(!(buf=ast_calloc(1, sizeof(*buf)+init_len))) return NULL;buf->len=init_len;return buf;}) AST_INLINE_API(struct ast_dynamic_str *ast_dynamic_str_thread_get(struct ast_threadstorage *ts
 Create a dynamic length string.
 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;pthread_setspecific(ts->key, buf);}return buf;}) struct ast_dynamic_str
 Retrieve thread storage.

Variables

size_t init_len


Detailed Description

Definitions to aid in the use of thread local storage.

Author:
Russell Bryant <russell@digium.com>

Definition in file threadstorage.h.


Define Documentation

#define ast_dynamic_str_thread_append_va ( buf,
max_len,
ts,
fmt,
ap   ) 

Append to a thread local dynamic string using a va_list.

The arguments, return values, and usage of this are the same as those for ast_dynamic_str_thread_set_va(). However, instead of setting a new value for the string, this will append to the current value.

Definition at line 347 of file threadstorage.h.

Referenced by manager_event().

#define ast_dynamic_str_thread_set_va ( buf,
max_len,
ts,
fmt,
ap   ) 

Set a thread locally stored dynamic string from a va_list.

  • buf This is the address of a pointer to an ast_dynamic_str which should have been retrieved using ast_dynamic_str_thread_get. It will need to be updated in the case that the buffer has to be reallocated to accomodate a longer string than what it currently has space for.
  • max_len This is the maximum length to allow the string buffer to grow to. If this is set to 0, then there is no maximum length.
  • ts This is a pointer to the thread storage structure declared by using the AST_THREADSTORAGE macro. If declared with AST_THREADSTORAGE(my_buf, my_buf_init), then this argument would be (&my_buf).
  • fmt This is the format string (printf style)
  • ap This is the va_list
Returns:
The return value of this function is the same as that of the printf family of functions.
Example usage:
 AST_THREADSTORAGE(my_str, my_str_init);
 #define MY_STR_INIT_SIZE   128
 ...
 void my_func(const char *fmt, ...)
 {
      struct ast_dynamic_str *buf;
      va_list ap;

      if (!(buf = ast_dynamic_str_thread_get(&my_str, MY_STR_INIT_SIZE)))
           return;
      ...
      va_start(fmt, ap);
      ast_dynamic_str_thread_set_va(&buf, 0, &my_str, fmt, ap);
      va_end(ap);
 
      printf("This is the string we just built: %s\n", buf->str);
      ...
 }

Definition at line 329 of file threadstorage.h.

Referenced by ast_cli(), ast_log(), ast_verbose(), and astman_append().

#define AST_THREADSTORAGE ( name,
name_init   )     AST_THREADSTORAGE_CUSTOM(name, name_init, ast_free)

Define a thread storage variable.

  • name The name of the thread storage
  • name_init This is a name used to create the function that gets called to initialize this thread storage. It can be anything since it will not be referred to anywhere else
This macro would be used to declare an instance of thread storage in a file.

Example usage:

 AST_THREADSTORAGE(my_buf, my_buf_init);

Definition at line 73 of file threadstorage.h.

#define AST_THREADSTORAGE_CUSTOM ( name,
name_init,
cleanup   ) 

Definition at line 77 of file threadstorage.h.

#define THREADSTORAGE_ONCE_INIT   PTHREAD_ONCE_INIT

Definition at line 49 of file threadstorage.h.


Function Documentation

ast_dynamic_str_thread_append ( struct ast_dynamic_str **  buf,
size_t  max_len,
struct ast_threadstorage ts,
const char *  fmt,
  ... 
)

Referenced by manager_event().

int ast_dynamic_str_thread_build_va ( struct ast_dynamic_str **  buf,
size_t  max_len,
struct ast_threadstorage ts,
int  append,
const char *  fmt,
va_list  ap 
)

Core functionality of ast_dynamic_str_thread_(set|append)_va.

The arguments to this function are the same as those described for ast_dynamic_str_thread_set_va except for an addition argument, append. If append is non-zero, this will append to the current string instead of writing over it.

Definition at line 1328 of file utils.c.

References ast_realloc, ast_threadstorage::key, and offset.

01330 {
01331    int res;
01332    int offset = (append && (*buf)->len) ? strlen((*buf)->str) : 0;
01333 #if defined(DEBUG_THREADLOCALS)
01334    struct ast_dynamic_str *old_buf = *buf;
01335 #endif /* defined(DEBUG_THREADLOCALS) */
01336 
01337    res = vsnprintf((*buf)->str + offset, (*buf)->len - offset, fmt, ap);
01338 
01339    /* Check to see if there was not enough space in the string buffer to prepare
01340     * the string.  Also, if a maximum length is present, make sure the current
01341     * length is less than the maximum before increasing the size. */
01342    if ((res + offset + 1) > (*buf)->len && (max_len ? ((*buf)->len < max_len) : 1)) {
01343       /* Set the new size of the string buffer to be the size needed
01344        * to hold the resulting string (res) plus one byte for the
01345        * terminating '\0'.  If this size is greater than the max, set
01346        * the new length to be the maximum allowed. */
01347       if (max_len)
01348          (*buf)->len = ((res + offset + 1) < max_len) ? (res + offset + 1) : max_len;
01349       else
01350          (*buf)->len = res + offset + 1;
01351 
01352       if (!(*buf = ast_realloc(*buf, (*buf)->len + sizeof(*(*buf)))))
01353          return AST_DYNSTR_BUILD_FAILED;
01354 
01355       if (append)
01356          (*buf)->str[offset] = '\0';
01357 
01358       if (ts) {
01359          pthread_setspecific(ts->key, *buf);
01360 #if defined(DEBUG_THREADLOCALS)
01361          __ast_threadstorage_object_replace(old_buf, *buf, (*buf)->len + sizeof(*(*buf)));
01362 #endif /* defined(DEBUG_THREADLOCALS) */
01363       }
01364 
01365       /* va_end() and va_start() must be done before calling
01366        * vsnprintf() again. */
01367       return AST_DYNSTR_BUILD_RETRY;
01368    }
01369 
01370    return res;
01371 }

AST_INLINE_API ( int   __attribute__(format(printf, 4, 5))) ast_dynamic_str_thread_set(struct ast_dynamic_str **buf, size_t max_len,struct ast_threadstorage *ts, const char *fmt,...  ) 

Set a thread locally stored dynamic string using variable arguments.

  • buf This is the address of a pointer to an ast_dynamic_str which should have been retrieved using ast_dynamic_str_thread_get. It will need to be updated in the case that the buffer has to be reallocated to accomodate a longer string than what it currently has space for.
  • max_len This is the maximum length to allow the string buffer to grow to. If this is set to 0, then there is no maximum length.
  • ts This is a pointer to the thread storage structure declared by using the AST_THREADSTORAGE macro. If declared with AST_THREADSTORAGE(my_buf, my_buf_init), then this argument would be (&my_buf).
  • fmt This is the format string (printf style)
Returns:
The return value of this function is the same as that of the printf family of functions.
Example usage:
 AST_THREADSTORAGE(my_str, my_str_init);
 #define MY_STR_INIT_SIZE   128
 ...
 void my_func(int arg1, int arg2)
 {
      struct ast_dynamic_str *buf;
      va_list ap;

      if (!(buf = ast_dynamic_str_thread_get(&my_str, MY_STR_INIT_SIZE)))
           return;
      ...
      ast_dynamic_str_thread_set(&buf, 0, &my_str, "arg1: %d  arg2: %d\n",
           arg1, arg2);
 
      printf("This is the string we just built: %s\n", buf->str);
      ...
 }

Append to a thread local dynamic string The arguments, return values, and usage of this function are the same as ast_dynamic_str_thread_set(). However, instead of setting a new value for the string, this function appends to the current value.

AST_INLINE_API ( struct ast_dynamic_str *attribute_malloc   ast_dynamic_str_createsize_t init_len  ) 

Create a dynamic length string.

  • init_len This is the initial length of the string buffer
Returns:
This function returns a pointer to the dynamic string length. The result will be NULL in the case of a memory allocation error.
/note The result of this function is dynamically allocated memory, and must be free()'d after it is no longer needed.

Retrieve a thread locally stored dynamic string

  • ts This is a pointer to the thread storage structure declared by using the AST_THREADSTORAGE macro. If declared with AST_THREADSTORAGE(my_buf, my_buf_init), then this argument would be (&my_buf).
  • init_len This is the initial length of the thread's dynamic string. The current length may be bigger if previous operations in this thread have caused it to increase.
Returns:
This function will return the thread locally storaged dynamic string 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_str, my_str_init);
 #define MY_STR_INIT_SIZE   128
 ...
 void my_func(const char *fmt, ...)
 {
      struct ast_dynamic_str *buf;

      if (!(buf = ast_dynamic_str_thread_get(&my_str, MY_STR_INIT_SIZE)))
           return;
      ...
 }

AST_INLINE_API ( void *  ast_threadstorage_getstruct ast_threadstorage *ts, size_t init_size  ) 

Retrieve thread storage.

  • ts This is a pointer to the thread storage structure declared by using the AST_THREADSTORAGE macro. If declared with AST_THREADSTORAGE(my_buf, my_buf_init), 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, my_buf_init);
 #define MY_BUF_SIZE   128
 ...
 void my_func(const char *fmt, ...)
 {
      void *buf;

      if (!(buf = ast_threadstorage_get(&my_buf, MY_BUF_SIZE)))
           return;
      ...
 }

A dynamic length string

Definition at line 136 of file threadstorage.h.

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

00138 {
00139    void *buf;
00140 
00141    pthread_once(&ts->once, ts->key_init);
00142    if (!(buf = pthread_getspecific(ts->key))) {
00143       if (!(buf = ast_calloc(1, init_size)))
00144          return NULL;
00145       pthread_setspecific(ts->key, buf);
00146    }
00147 
00148    return buf;
00149 }
00150 )
00151 #else /* defined(DEBUG_THREADLOCALS) */
00152 AST_INLINE_API(
00153 void *__ast_threadstorage_get(struct ast_threadstorage *ts, size_t init_size, const char *file, const char *function, unsigned int line),
00154 {
00155    void *buf;
00156 
00157    pthread_once(&ts->once, ts->key_init);
00158    if (!(buf = pthread_getspecific(ts->key))) {
00159       if (!(buf = ast_calloc(1, init_size)))
00160          return NULL;
00161       pthread_setspecific(ts->key, buf);
00162       __ast_threadstorage_object_add(buf, init_size, file, function, line);
00163    }
00164 
00165    return buf;
00166 }
00167 )
00168 
00169 #define ast_threadstorage_get(ts, init_size) __ast_threadstorage_get(ts, init_size, __FILE__, __PRETTY_FUNCTION__, __LINE__)
00170 #endif /* defined(DEBUG_THREADLOCALS) */
00171 
00172 /*!
00173  * \brief A dynamic length string
00174  */
00175 struct ast_dynamic_str {
00176    /* The current maximum length of the string */
00177    size_t len;
00178    /* The string buffer */
00179    char str[0];
00180 };


Variable Documentation

size_t init_len

Definition at line 241 of file threadstorage.h.


Generated on Thu Oct 8 21:57:58 2009 for Asterisk - the Open Source PBX by  doxygen 1.5.8