Mon May 14 04:53:20 2007

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)

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 argumentsAppend to a thread local dynamic string.
 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 stringRetrieve a thread locally stored dynamic 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 storageA dynamic length string.

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 361 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.

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 343 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.

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 87 of file threadstorage.h.

#define AST_THREADSTORAGE_CUSTOM ( name,
name_init,
cleanup   ) 

Definition at line 91 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.

In the case that this function is called and the buffer was not large enough to hold the result, the partial write will be truncated, and the result AST_DYNSTR_BUILD_RETRY will be returned to indicate that the buffer size was increased, and the function should be called a second time.

A return of AST_DYNSTR_BUILD_FAILED indicates a memory allocation error.

A return value greater than or equal to zero indicates the number of characters that have been written, not including the terminating ''. In the append case, this only includes the number of characters appended.

Note:
This function should never need to be called directly. It should through calling one of the other functions or macros defined in this file.

Definition at line 975 of file utils.c.

References ast_realloc, ast_threadstorage::key, and offset.

00977 {
00978    int res;
00979    int offset = (append && (*buf)->len) ? strlen((*buf)->str) : 0;
00980 #if defined(DEBUG_THREADLOCALS)
00981    struct ast_dynamic_str *old_buf = *buf;
00982 #endif /* defined(DEBUG_THREADLOCALS) */
00983 
00984    res = vsnprintf((*buf)->str + offset, (*buf)->len - offset, fmt, ap);
00985 
00986    /* Check to see if there was not enough space in the string buffer to prepare
00987     * the string.  Also, if a maximum length is present, make sure the current
00988     * length is less than the maximum before increasing the size. */
00989    if ((res + offset + 1) > (*buf)->len && (max_len ? ((*buf)->len < max_len) : 1)) {
00990       /* Set the new size of the string buffer to be the size needed
00991        * to hold the resulting string (res) plus one byte for the
00992        * terminating '\0'.  If this size is greater than the max, set
00993        * the new length to be the maximum allowed. */
00994       if (max_len)
00995          (*buf)->len = ((res + offset + 1) < max_len) ? (res + offset + 1) : max_len;
00996       else
00997          (*buf)->len = res + offset + 1;
00998 
00999       if (!(*buf = ast_realloc(*buf, (*buf)->len + sizeof(*(*buf)))))
01000          return AST_DYNSTR_BUILD_FAILED;
01001 
01002       if (append)
01003          (*buf)->str[offset] = '\0';
01004 
01005       if (ts) {
01006          pthread_setspecific(ts->key, *buf);
01007 #if defined(DEBUG_THREADLOCALS)
01008          __ast_threadstorage_object_replace(old_buf, *buf, (*buf)->len + sizeof(*(*buf)));
01009 #endif /* defined(DEBUG_THREADLOCALS) */
01010       }
01011 
01012       /* va_end() and va_start() must be done before calling
01013        * vsnprintf() again. */
01014       return AST_DYNSTR_BUILD_RETRY;
01015    }
01016 
01017    return res;
01018 }

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 argumentsAppend 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_create(size_t init_len)  ) 

Create a dynamic length stringRetrieve a thread locally stored dynamic string.

Returns:
This function will return the thread locally stored 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_get(struct ast_threadstorage *ts, size_t init_size)  ) 

Retrieve thread storageA dynamic length string.

Definition at line 150 of file threadstorage.h.

References ast_calloc.

00152 {
00153    void *buf;
00154 
00155    pthread_once(&ts->once, ts->key_init);
00156    if (!(buf = pthread_getspecific(ts->key))) {
00157       if (!(buf = ast_calloc(1, init_size)))
00158          return NULL;
00159       pthread_setspecific(ts->key, buf);
00160    }
00161 
00162    return buf;
00163 }
00164 )
00165 #else /* defined(DEBUG_THREADLOCALS) */
00166 AST_INLINE_API(
00167 void *__ast_threadstorage_get(struct ast_threadstorage *ts, size_t init_size, const char *file, const char *function, unsigned int line),
00168 {
00169    void *buf;
00170 
00171    pthread_once(&ts->once, ts->key_init);
00172    if (!(buf = pthread_getspecific(ts->key))) {
00173       if (!(buf = ast_calloc(1, init_size)))
00174          return NULL;
00175       pthread_setspecific(ts->key, buf);
00176       __ast_threadstorage_object_add(buf, init_size, file, function, line);
00177    }
00178 
00179    return buf;
00180 }
00181 )
00182 
00183 #define ast_threadstorage_get(ts, init_size) __ast_threadstorage_get(ts, init_size, __FILE__, __PRETTY_FUNCTION__, __LINE__)
00184 #endif /* defined(DEBUG_THREADLOCALS) */
00185 
00186 /*!
00187  * \brief A dynamic length string
00188  */
00189 struct ast_dynamic_str {
00190    /* The current maximum length of the string */
00191    size_t len;
00192    /* The string buffer */
00193    char str[0];
00194 };


Variable Documentation

size_t init_len

Definition at line 255 of file threadstorage.h.


Generated on Mon May 14 04:53:22 2007 for Asterisk - the Open Source PBX by  doxygen 1.5.1