Sat Aug 6 00:40:06 2011

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"

Go to the source code of this file.

Data Structures

struct  ast_dynamic_str
 A dynamic length string. More...
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_PTHREAD_ONCE_INIT   PTHREAD_ONCE_INIT
#define AST_THREADSTORAGE(name, name_init)   AST_THREADSTORAGE_CUSTOM(name, name_init, ast_free_ptr)
 Define a thread storage variable.
#define AST_THREADSTORAGE_CUSTOM(name, name_init, cleanup)

Enumerations

enum  { AST_DYNSTR_BUILD_FAILED = -1, AST_DYNSTR_BUILD_RETRY = -2 }
 Error codes from ast_dynamic_str_thread_build_va(). More...

Functions

int ast_dynamic_str_append (struct ast_dynamic_str **buf, size_t max_len, const char *fmt,...)
 Append to a dynatic string.
ast_dynamic_strast_dynamic_str_create (size_t init_len)
 Create a dynamic length string.
int ast_dynamic_str_set (struct ast_dynamic_str **buf, size_t max_len, const char *fmt,...)
 Set a dynamic string.
int ast_dynamic_str_thread_append (struct ast_dynamic_str **buf, size_t max_len, struct ast_threadstorage *ts, const char *fmt,...)
 Append to a thread local dynamic string.
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_dynamic_strast_dynamic_str_thread_get (struct ast_threadstorage *ts, size_t init_len)
 Retrieve a thread locally stored dynamic string.
int 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.
void * ast_threadstorage_get (struct ast_threadstorage *ts, size_t init_size)
 Retrieve thread storage.


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 ast_dynamic_str_set(), ast_dynamic_str_thread_set(), and 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 329 of file threadstorage.h.

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

#define AST_PTHREAD_ONCE_INIT   PTHREAD_ONCE_INIT

Definition at line 73 of file threadstorage.h.

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

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

#define AST_THREADSTORAGE_CUSTOM ( name,
name_init,
cleanup   ) 

Definition at line 77 of file threadstorage.h.


Enumeration Type Documentation

anonymous enum

Error codes from ast_dynamic_str_thread_build_va().

Enumerator:
AST_DYNSTR_BUILD_FAILED  An error has occured and the contents of the dynamic string are undefined
AST_DYNSTR_BUILD_RETRY  The buffer size for the dynamic string had to be increased, and ast_dynamic_str_thread_build_va() needs to be called again after a va_end() and va_start().

Definition at line 277 of file threadstorage.h.

00277      {
00278    /*! An error has occured and the contents of the dynamic string
00279     *  are undefined */
00280    AST_DYNSTR_BUILD_FAILED = -1,
00281    /*! The buffer size for the dynamic string had to be increased, and
00282     *  ast_dynamic_str_thread_build_va() needs to be called again after
00283     *  a va_end() and va_start().
00284     */
00285    AST_DYNSTR_BUILD_RETRY = -2
00286 };


Function Documentation

int ast_dynamic_str_append ( struct ast_dynamic_str **  buf,
size_t  max_len,
const char *  fmt,
  ... 
) [inline]

Append to a dynatic string.

The arguments, return values, and usage of this function are the same as ast_dynamic_str_set(). However, this function appends to the string instead of setting a new value.

Definition at line 496 of file threadstorage.h.

Referenced by astman_append(), and process_events().

struct ast_dynamic_str * ast_dynamic_str_create ( size_t  init_len  )  [inline]

Create a dynamic length string.

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.

Definition at line 205 of file threadstorage.h.

References ast_threadstorage_get(), and ast_dynamic_str::len.

Referenced by ast_hint_state_changed().

00223 :
 * \code

int ast_dynamic_str_set ( struct ast_dynamic_str **  buf,
size_t  max_len,
const char *  fmt,
  ... 
) [inline]

Set a dynamic string.

Returns:
The return value of this function is the same as that of the printf family of functions.

Definition at line 473 of file threadstorage.h.

References ast_dynamic_str_thread_append_va.

Referenced by ast_hint_state_changed().

00486 {

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

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.

Definition at line 445 of file threadstorage.h.

References ast_dynamic_str_thread_set_va.

Referenced by manager_event().

00463 {

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 1363 of file utils.c.

References AST_DYNSTR_BUILD_FAILED, AST_DYNSTR_BUILD_RETRY, ast_realloc, ast_threadstorage::key, ast_dynamic_str::len, and offset.

01365 {
01366    int res;
01367    int offset = (append && (*buf)->len) ? strlen((*buf)->str) : 0;
01368 #if defined(DEBUG_THREADLOCALS)
01369    struct ast_dynamic_str *old_buf = *buf;
01370 #endif /* defined(DEBUG_THREADLOCALS) */
01371 
01372    res = vsnprintf((*buf)->str + offset, (*buf)->len - offset, fmt, ap);
01373 
01374    /* Check to see if there was not enough space in the string buffer to prepare
01375     * the string.  Also, if a maximum length is present, make sure the current
01376     * length is less than the maximum before increasing the size. */
01377    if ((res + offset + 1) > (*buf)->len && (max_len ? ((*buf)->len < max_len) : 1)) {
01378       /* Set the new size of the string buffer to be the size needed
01379        * to hold the resulting string (res) plus one byte for the
01380        * terminating '\0'.  If this size is greater than the max, set
01381        * the new length to be the maximum allowed. */
01382       if (max_len)
01383          (*buf)->len = ((res + offset + 1) < max_len) ? (res + offset + 1) : max_len;
01384       else
01385          (*buf)->len = res + offset + 1;
01386 
01387       if (!(*buf = ast_realloc(*buf, (*buf)->len + sizeof(*(*buf)))))
01388          return AST_DYNSTR_BUILD_FAILED;
01389 
01390       if (append)
01391          (*buf)->str[offset] = '\0';
01392 
01393       if (ts) {
01394          pthread_setspecific(ts->key, *buf);
01395 #if defined(DEBUG_THREADLOCALS)
01396          __ast_threadstorage_object_replace(old_buf, *buf, (*buf)->len + sizeof(*(*buf)));
01397 #endif /* defined(DEBUG_THREADLOCALS) */
01398       }
01399 
01400       /* va_end() and va_start() must be done before calling
01401        * vsnprintf() again. */
01402       return AST_DYNSTR_BUILD_RETRY;
01403    }
01404 
01405    return res;
01406 }

struct ast_dynamic_str * ast_dynamic_str_thread_get ( struct ast_threadstorage ts,
size_t  init_len 
) [inline]

Retrieve a thread locally stored dynamic string.

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;
      ...
 }

Definition at line 253 of file threadstorage.h.

Referenced by ast_cli(), ast_log(), ast_verbose(), astman_append(), check_auth(), manager_event(), and transmit_fake_auth_response().

00258 {

int ast_dynamic_str_thread_set ( struct ast_dynamic_str **  buf,
size_t  max_len,
struct ast_threadstorage ts,
const char *  fmt,
  ... 
) [inline]

Set a thread locally stored dynamic string using variable arguments.

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);
      ...
 }

Definition at line 422 of file threadstorage.h.

References ast_dynamic_str_thread_append_va.

Referenced by ast_log(), check_auth(), manager_event(), and transmit_fake_auth_response().

00435 {

void * ast_threadstorage_get ( struct ast_threadstorage ts,
size_t  init_size 
) [inline]

Retrieve thread storage.

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;
      ...
 }

Definition at line 150 of file threadstorage.h.

References ast_calloc.

Referenced by __frame_free(), ast_dynamic_str_create(), ast_frame_header_new(), ast_frdup(), ast_inet_ntoa(), ast_state2str(), control2str(), curl_internal(), device2str(), dummy_start(), iax_frame_free(), iax_frame_new(), process_sdp(), and transmit_response_using_temp().

00154 {


Generated on Sat Aug 6 00:40:06 2011 for Asterisk - the Open Source PBX by  doxygen 1.4.7