move the dynamic string support in a better place i.e. string.h

While doing this, add a bit of documentation, and slightly
extend the functionality as follows:
 + a max_len of -1 means that we take whatever the current size
   is, and never try to extend the buffer;
 + add support for alloca()-ted dynamic strings, which is very
   useful for all cases where we do an ast_build_string() now.

Next step is to simplify the interface by using shorter names
(e.g. ast_str as a prefix) and removing the _thread variant
of the functions by saving the threadstorage reference into
the struct ast_str. This can be done by overloading the
'type' field.

Finally, I will do my best to remove the convoluted interface
that results from trying to support platforms without va_copy().



git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@48509 65c4cc65-6c06-0410-ace0-fbb531ad65f3

1 files changed, 4 insertions, 331 deletions

diff --git a/include/asterisk/threadstorage.h b/include/asterisk/threadstorage.h
index d087f81d0..469f46389 100644
--- a/include/asterisk/threadstorage.h
+++ b/include/asterisk/threadstorage.h
@@ -56,14 +56,10 @@
  * \brief data for a thread locally stored variable
  */
 struct ast_threadstorage {
-	/*! Ensure that the key is only initialized by one thread */
-	pthread_once_t once;
-	/*! The key used to retrieve this thread's data */
-	pthread_key_t key;
-	/*! The function that initializes the key */
-	void (*key_init)(void);
-	/*! Custom initialization function specific to the object */
-	int (*custom_init)(void *);
+	pthread_once_t once;	/*!< Ensure that the key is only initialized by one thread */
+	pthread_key_t key;	/*!< The key used to retrieve this thread's data */
+	void (*key_init)(void);	/*!< The function that initializes the key */
+	int (*custom_init)(void *); /*!< Custom initialization function specific to the object */
 };
 
 /*!
@@ -161,327 +157,4 @@ void *ast_threadstorage_get(struct ast_threadstorage *ts, size_t init_size),
 
 void __ast_threadstorage_cleanup(void *);
 
-/*!
- * A dynamic length string. This is just a C string prefixed by a length
- * field. len reflects the actual space allocated, while the string is
- * NUL-terminated as a regular C string.
- * One should never declare a variable with this type, but only a pointer
- * to it, and use ast_dynamic_str_create() to initialize it.
- */
-struct ast_dynamic_str {
-	size_t len;	/*!< The current maximum length of the string */
-	char str[0];	/*!< The string buffer */
-};
-
-/*!
- * \brief Create a dynamic length string
- *
- * \arg init_len This is the initial length of the string buffer
- *
- * \return 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.
- */
-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;
-}
-)
-
-/*!
- * \brief Retrieve a thread locally stored dynamic string
- *
- * \arg 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).
- * \arg 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.
- *
- * \return 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:
- * \code
- * 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;
- *      ...
- * }
- * \endcode
- */
-AST_INLINE_API(
-struct ast_dynamic_str *ast_dynamic_str_thread_get(struct ast_threadstorage *ts,
-	size_t init_len),
-{
-	struct ast_dynamic_str *buf;
-
-	if (!(buf = ast_threadstorage_get(ts, sizeof(*buf) + init_len)))
-		return NULL;
-	
-	if (!buf->len)
-		buf->len = init_len;
-
-	return buf;
-}
-)
-
-/*!
- * \brief Error codes from ast_dynamic_str_thread_build_va()
- */
-enum {
-	/*! An error has occured and the contents of the dynamic string
-	 *  are undefined */
-	AST_DYNSTR_BUILD_FAILED = -1,
-	/*! 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().
-	 */
-	AST_DYNSTR_BUILD_RETRY = -2
-};
-
-/*!
- * \brief Set a thread locally stored dynamic string from a va_list
- *
- * \arg 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
- *      accommodate a longer string than what it currently has space for.
- * \arg 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.
- * \arg 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).
- * \arg fmt This is the format string (printf style)
- * \arg ap This is the va_list
- *
- * \return The return value of this function is the same as that of the printf
- *         family of functions.
- *
- * Example usage:
- * \code
- * 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);
- *      ...
- * }
- * \endcode
- */
-#define ast_dynamic_str_thread_set_va(buf, max_len, ts, fmt, ap)                 \
-	({                                                                       \
-		int __res;                                                       \
-		while ((__res = ast_dynamic_str_thread_build_va(buf, max_len,    \
-			ts, 0, fmt, ap)) == AST_DYNSTR_BUILD_RETRY) {            \
-			va_end(ap);                                              \
-			va_start(ap, fmt);                                       \
-		}                                                                \
-		(__res);                                                         \
-	})
-
-/*!
- * \brief 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.
- */
-#define ast_dynamic_str_thread_append_va(buf, max_len, ts, fmt, ap)              \
-	({                                                                       \
-		int __res;                                                       \
-		while ((__res = ast_dynamic_str_thread_build_va(buf, max_len,    \
-			ts, 1, fmt, ap)) == AST_DYNSTR_BUILD_RETRY) {            \
-			va_end(ap);                                              \
-			va_start(ap, fmt);                                       \
-		}                                                                \
-		(__res);                                                         \
-	})
-
-/*!
- * \brief 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 '\0'.
- * 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.
- */
-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);
-
-/*!
- * \brief Set a thread locally stored dynamic string using variable arguments
- *
- * \arg 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.
- * \arg 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.
- * \arg 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).
- * \arg fmt This is the format string (printf style)
- *
- * \return The return value of this function is the same as that of the printf
- *         family of functions.
- *
- * Example usage:
- * \code
- * 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);
- *      ...
- * }
- * \endcode
- */
-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;
-}
-)
-
-/*!
- * \brief 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(
-int __attribute__ ((format (printf, 4, 5))) ast_dynamic_str_thread_append(
-	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_append_va(buf, max_len, ts, fmt, ap);
-	va_end(ap);
-
-	return res;
-}
-)
-
-/*!
- * \brief Set a dynamic string
- *
- * \arg buf This is the address of a pointer to an ast_dynamic_str.  It will
- *      need to be updated in the case that the buffer has to be reallocated to
- *      accommodate a longer string than what it currently has space for.
- * \arg 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.
- *
- * \return The return value of this function is the same as that of the printf
- *         family of functions.
- */
-AST_INLINE_API(
-int __attribute__ ((format (printf, 3, 4))) ast_dynamic_str_set(
-	struct ast_dynamic_str **buf, size_t max_len,
-	const char *fmt, ...),
-{
-	int res;
-	va_list ap;
-	
-	va_start(ap, fmt);
-	res = ast_dynamic_str_thread_set_va(buf, max_len, NULL, fmt, ap);
-	va_end(ap);
-
-	return res;
-}
-)
-
-/*!
- * \brief Append to a dynamic 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.
- */
-AST_INLINE_API(
-int __attribute__ ((format (printf, 3, 4))) ast_dynamic_str_append(
-	struct ast_dynamic_str **buf, size_t max_len,
-	const char *fmt, ...),
-{
-	int res;
-	va_list ap;
-	
-	va_start(ap, fmt);
-	res = ast_dynamic_str_thread_append_va(buf, max_len, NULL, fmt, ap);
-	va_end(ap);
-
-	return res;
-}
-)
-
 #endif /* ASTERISK_THREADSTORAGE_H */