stringfields.h File Reference

String fields in structures. More...

#include "asterisk/inline_api.h"

Include dependency graph for stringfields.h:

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

Go to the source code of this file.

Data Structures
struct	ast_string_field_mgr
struct	ast_string_field_pool
Defines
#define	ast_calloc_with_stringfields(n, type, size)
	Allocate a structure with embedded stringfields in a single allocation.
#define	AST_DECLARE_STRING_FIELDS(field_list)
	Declare the fields needed in a structure.
#define	AST_STRING_FIELD(name)   const ast_string_field name
	Declare a string field.
#define	AST_STRING_FIELD_ALLOCATION(x)   *((ast_string_field_allocation *) (x - __alignof__(ast_string_field_allocation)))
	Macro to provide access to the allocation field that lives immediately in front of a string field.
#define	ast_string_field_build(x, field, fmt, args...)   __ast_string_field_ptr_build(&(x)->__field_mgr, &(x)->__field_mgr_pool, (ast_string_field *) &(x)->field, fmt, args)
	Set a field to a complex (built) value.
#define	ast_string_field_build_va(x, field, fmt, args)   __ast_string_field_ptr_build_va(&(x)->__field_mgr, &(x)->__field_mgr_pool, (ast_string_field *) &(x)->field, fmt, args)
	Set a field to a complex (built) value.
#define	ast_string_field_free_memory(x)   __ast_string_field_init(&(x)->__field_mgr, &(x)->__field_mgr_pool, -1, __FILE__, __LINE__, __PRETTY_FUNCTION__)
	free all memory - to be called before destroying the object
#define	ast_string_field_init(x, size)   __ast_string_field_init(&(x)->__field_mgr, &(x)->__field_mgr_pool, size, __FILE__, __LINE__, __PRETTY_FUNCTION__)
	Initialize a field pool and fields.
#define	ast_string_field_ptr_build(x, ptr, fmt, args...)   __ast_string_field_ptr_build(&(x)->__field_mgr, &(x)->__field_mgr_pool, (ast_string_field *) ptr, fmt, args)
	Set a field to a complex (built) value.
#define	ast_string_field_ptr_build_va(x, ptr, fmt, args)   __ast_string_field_ptr_build_va(&(x)->__field_mgr, &(x)->__field_mgr_pool, (ast_string_field *) ptr, fmt, args)
	Set a field to a complex (built) value with prebuilt va_lists.
#define	ast_string_field_ptr_set(x, ptr, data)
	Set a field to a simple string value.
#define	ast_string_field_set(x, field, data)
	Set a field to a simple string value.
Typedefs
typedef const char *	ast_string_field
typedef uint16_t	ast_string_field_allocation
Functions
void *attribute_malloc	__ast_calloc_with_stringfields (unsigned int num_structs, size_t struct_size, size_t field_mgr_offset, size_t field_mgr_pool_offset, size_t pool_size, const char *file, int lineno, const char *func)
ast_string_field	__ast_string_field_alloc_space (struct ast_string_field_mgr *mgr, struct ast_string_field_pool **pool_head, size_t needed)
int	__ast_string_field_init (struct ast_string_field_mgr *mgr, struct ast_string_field_pool **pool_head, int needed, const char *file, int lineno, const char *func)
void	__ast_string_field_ptr_build (struct ast_string_field_mgr *mgr, struct ast_string_field_pool **pool_head, ast_string_field *ptr, const char *format,...)
void	__ast_string_field_ptr_build_va (struct ast_string_field_mgr *mgr, struct ast_string_field_pool **pool_head, ast_string_field *ptr, const char *format, va_list ap)
int	__ast_string_field_ptr_grow (struct ast_string_field_mgr *mgr, struct ast_string_field_pool **pool_head, size_t needed, const ast_string_field *ptr)
void	__ast_string_field_release_active (struct ast_string_field_pool *pool_head, const ast_string_field ptr)
Variables
const char *	__ast_string_field_empty

---

Detailed Description

String fields in structures.

This file contains objects and macros used to manage string fields in structures without requiring them to be allocated as fixed-size buffers or requiring individual allocations for for each field.

Using this functionality is quite simple. An example structure with three fields is defined like this:

  struct sample_fields {
     int x1;
     AST_DECLARE_STRING_FIELDS(
        AST_STRING_FIELD(foo);
        AST_STRING_FIELD(bar);
        AST_STRING_FIELD(blah);
     );
     long x2;
  };

When an instance of this structure is allocated (either statically or dynamically), the fields and the pool of storage for them must be initialized:

  struct sample_fields *x;
  
  x = ast_calloc(1, sizeof(*x));
  if (x == NULL || ast_string_field_init(x, 252)) {
   if (x)
      ast_free(x);
   x = NULL;
   ... handle error
  }

Fields will default to pointing to an empty string, and will revert to that when ast_string_field_set() is called with a NULL argument. A string field will never contain NULL.

ast_string_field_init(x, 0) will reset fields to the initial value while keeping the pool allocated.

Reading the fields is much like using 'const char * const' fields in the structure: you cannot write to the field or to the memory it points to.

Writing to the fields must be done using the wrapper macros listed below; and assignments are always by value (i.e. strings are copied): ast_string_field_set() stores a simple value; ast_string_field_build() builds the string using a printf-style format; ast_string_field_build_va() is the varargs version of the above (for portability reasons it uses two vararg arguments); variants of these function allow passing a pointer to the field as an argument.

  ast_string_field_set(x, foo, "infinite loop");
  ast_string_field_set(x, foo, NULL); // set to an empty string
  ast_string_field_ptr_set(x, &x->bar, "right way");

  ast_string_field_build(x, blah, "%d %s", zipcode, city);
  ast_string_field_ptr_build(x, &x->blah, "%d %s", zipcode, city);

  ast_string_field_build_va(x, bar, fmt, args1, args2)
  ast_string_field_ptr_build_va(x, &x->bar, fmt, args1, args2)

When the structure instance is no longer needed, the fields and their storage pool must be freed:

  ast_string_field_free_memory(x);
  ast_free(x);

This completes the API description.

Definition in file stringfields.h.

---

Define Documentation

#define ast_calloc_with_stringfields	(	n,
		type,
		size		)

Value:

__ast_calloc_with_stringfields(n, sizeof(type), offsetof(type, __field_mgr), offsetof(type, __field_mgr_pool), \
                   size, __FILE__, __LINE__, __PRETTY_FUNCTION__)

Allocate a structure with embedded stringfields in a single allocation.

Parameters:

	n	Number of structures to allocate (see ast_calloc)
	type	The type of structure to allocate
	size	The number of bytes of space (minimum) to allocate for stringfields to use

This function will allocate memory for one or more structures that use stringfields, and also allocate space for the stringfields and initialize the stringfield management structure embedded in the outer structure.

Since:

1.8

Definition at line 275 of file stringfields.h.

Referenced by append_mailbox_mapping(), ast_log(), AST_TEST_DEFINE(), build_extension(), build_profile(), jack_data_alloc(), load_config(), load_module(), raise_exception(), register_group(), register_group_feature(), sip_register(), sip_subscribe_mwi(), sla_build_station(), and sla_build_trunk().

#define AST_DECLARE_STRING_FIELDS

(

field_list

)

Value:

struct ast_string_field_pool *__field_mgr_pool; \
   field_list              \
   struct ast_string_field_mgr __field_mgr

Declare the fields needed in a structure.

Parameters:

field_list

The list of fields to declare, using AST_STRING_FIELD() for each one. Internally, string fields are stored as a pointer to the head of the pool, followed by individual string fields, and then a struct ast_string_field_mgr which describes the space allocated. We split the two variables so they can be used as markers around the field_list, and this allows us to determine how many entries are in the field, and play with them. In particular, for writing to the fields, we rely on __field_mgr_pool to be a non-const pointer, so we know it has the same size as ast_string_field, and we can use it to locate the fields.

Definition at line 235 of file stringfields.h.

#define AST_STRING_FIELD

(

name

)

const ast_string_field name

Declare a string field.

Parameters:

name

The field name

Definition at line 220 of file stringfields.h.

#define AST_STRING_FIELD_ALLOCATION

(

x

)

*((ast_string_field_allocation *) (x - __alignof__(ast_string_field_allocation)))

Macro to provide access to the allocation field that lives immediately in front of a string field.

Parameters:

x

Pointer to the string field

Note that x must be a pointer to a byte-sized type -- normally (char *) -- or this calculation would break horribly

Definition at line 309 of file stringfields.h.

Referenced by __ast_string_field_alloc_space(), __ast_string_field_ptr_build_va(), __ast_string_field_ptr_grow(), and __ast_string_field_release_active().

#define ast_string_field_build	(	x,
		field,
		fmt,
		args...		)	__ast_string_field_ptr_build(&(x)->__field_mgr, &(x)->__field_mgr_pool, (ast_string_field *) &(x)->field, fmt, args)

Set a field to a complex (built) value.

Parameters:

	x	Pointer to a structure containing fields
	field	Name of the field to set
	fmt	printf-style format string
	args	Arguments for format string

Returns:

nothing

Definition at line 365 of file stringfields.h.

Referenced by action_originate(), build_callid_pvt(), build_callid_registry(), build_contact(), build_profile(), build_user(), caldav_write_event(), fax_gateway_framehook(), handle_request_subscribe(), init_acf_query(), load_config(), parse_cdata(), parse_register_contact(), set_nonce_randdata(), sip_sendhtml(), sip_sipredirect(), spandsp_fax_gateway_cleanup(), and t30_phase_e_handler().

#define ast_string_field_build_va	(	x,
		field,
		fmt,
		args		)	__ast_string_field_ptr_build_va(&(x)->__field_mgr, &(x)->__field_mgr_pool, (ast_string_field *) &(x)->field, fmt, args)

Set a field to a complex (built) value.

Parameters:

	x	Pointer to a structure containing fields
	field	Name of the field to set
	fmt	printf-style format string
	args1	argument one
	args2	argument two

Returns:

nothing

Definition at line 389 of file stringfields.h.

#define ast_string_field_free_memory

(

x

)

__ast_string_field_init(&(x)->__field_mgr, &(x)->__field_mgr_pool, -1, __FILE__, __LINE__, __PRETTY_FUNCTION__)

free all memory - to be called before destroying the object

Definition at line 253 of file stringfields.h.

Referenced by __sip_destroy(), action_destroy(), ast_channel_destructor(), ast_custom_function_unregister(), ast_dummy_channel_destructor(), ast_pbx_outgoing_app(), ast_pbx_run_app(), AST_TEST_DEFINE(), ast_unregister_application(), ast_unregister_groups(), auth_http_callback(), build_user(), caldav_destructor(), calendar_destructor(), calendar_event_destructor(), db_destructor(), delete_extension(), delete_file(), destroy_fast_originate_helper(), destroy_jack_data(), destroy_mailbox_mapping(), destroy_queue(), destroy_session_details(), destroy_station(), destroy_trunk(), ewscal_destructor(), exception_store_free(), exchangecal_destructor(), free_acf_query(), free_outgoing(), icalendar_destructor(), init_acf_query(), load_module(), msg_data_destructor(), peer_destructor(), profile_destructor(), pvt_destructor(), realtime_multi_odbc(), realtime_odbc(), route_destructor(), sip_destroy_peer(), sip_monitor_instance_destructor(), sip_registry_destroy(), sip_subscribe_mwi_destroy(), tds_unload_module(), temp_pvt_cleanup(), update_odbc(), and user_destructor().

#define ast_string_field_init	(	x,
		size		)	__ast_string_field_init(&(x)->__field_mgr, &(x)->__field_mgr_pool, size, __FILE__, __LINE__, __PRETTY_FUNCTION__)

Initialize a field pool and fields.

Parameters:

	x	Pointer to a structure containing fields
	size	Amount of storage to allocate. Use 0 to reset fields to the default value, and release all but the most recent pool. size<0 (used internally) means free all pools.

Returns:

0 on success, non-zero on failure

Definition at line 249 of file stringfields.h.

Referenced by __ast_channel_alloc_ap(), acf_retrieve_docs(), action_originate(), alloc_queue(), ast_calendar_event_alloc(), ast_dummy_channel_alloc(), ast_manager_register2(), ast_pbx_outgoing_app(), ast_register_application2(), auth_http_callback(), build_calendar(), build_peer(), build_profile(), build_route(), build_user(), caldav_load_calendar(), ewscal_load_calendar(), exchangecal_load_calendar(), ical_load_calendar(), init_acf_query(), init_outgoing(), init_pvt(), msg_data_alloc(), new_iax(), new_realtime_sqlite3_db(), realtime_multi_odbc(), realtime_odbc(), session_details_new(), sip_alloc(), sip_monitor_instance_init(), tds_load_module(), temp_peer(), temp_pvt_init(), transmit_response_using_temp(), and update_odbc().

#define ast_string_field_ptr_build	(	x,
		ptr,
		fmt,
		args...		)	__ast_string_field_ptr_build(&(x)->__field_mgr, &(x)->__field_mgr_pool, (ast_string_field *) ptr, fmt, args)

Set a field to a complex (built) value.

Parameters:

	x	Pointer to a structure containing fields
	ptr	Pointer to a field within the structure
	fmt	printf-style format string
	args	Arguments for format string

Returns:

nothing

Definition at line 354 of file stringfields.h.

#define ast_string_field_ptr_build_va	(	x,
		ptr,
		fmt,
		args		)	__ast_string_field_ptr_build_va(&(x)->__field_mgr, &(x)->__field_mgr_pool, (ast_string_field *) ptr, fmt, args)

Set a field to a complex (built) value with prebuilt va_lists.

Parameters:

	x	Pointer to a structure containing fields
	ptr	Pointer to a field within the structure
	fmt	printf-style format string
	args1	Arguments for format string in va_list format
	args2	a second copy of the va_list for the sake of bsd, with no va_list copy operation

Returns:

nothing

Definition at line 377 of file stringfields.h.

#define ast_string_field_ptr_set	(	x,
		ptr,
		data		)

Set a field to a simple string value.

Parameters:

	x	Pointer to a structure containing fields
	ptr	Pointer to a field within the structure
	data	String value to be copied into the field

Returns:

nothing

Definition at line 318 of file stringfields.h.

Referenced by reply_digest().

#define ast_string_field_set	(	x,
		field,
		data		)

Value:

do {     \
   ast_string_field_ptr_set(x, &(x)->field, data);    \
   } while (0)

Set a field to a simple string value.

Parameters:

	x	Pointer to a structure containing fields
	field	Name of the field to set
	data	String value to be copied into the field

Returns:

nothing

Definition at line 342 of file stringfields.h.

Referenced by __find_callno(), __sip_subscribe_mwi_do(), acf_faxopt_write(), acf_retrieve_docs(), action_originate(), alloc_queue(), append_mailbox_mapping(), apply_outgoing(), ast_log(), ast_manager_register2(), ast_parse_digest(), ast_pbx_outgoing_app(), ast_register_application2(), authenticate_reply(), authenticate_request(), authenticate_verify(), build_calendar(), build_extension(), build_peer(), build_profile(), build_route(), build_user(), cache_get_callno_locked(), caldav_add_event(), caldav_load_calendar(), calendar_write_exec(), change_callid_pvt(), check_access(), check_peer_ok(), check_user_full(), copy_event_data(), create_addr(), create_addr_from_peer(), custom_prepare(), endelm(), ewscal_load_calendar(), exchangecal_load_calendar(), extract_uri(), fax_gateway_attach(), fax_gateway_detect_t38(), fax_gateway_framehook(), fax_gateway_start(), forked_invite_init(), generic_fax_exec(), get_also_info(), get_destination(), get_pai(), get_realm(), get_rpid(), handle_cc_notify(), handle_incoming(), handle_options(), handle_request_bye(), handle_request_invite(), handle_request_options(), handle_request_publish(), handle_request_refer(), handle_response(), handle_response_invite(), handle_response_notify(), handle_response_publish(), handle_response_subscribe(), iax2_call(), iax2_request(), ical_load_calendar(), icalendar_add_event(), init_acf_query(), init_pvt(), init_queue(), initreqprep(), load_config(), logger_print_normal(), msg_set_var_full(), new_iax(), new_realtime_sqlite3_db(), parse_ok_contact(), parse_register_contact(), queue_set_param(), raise_exception(), receive_message(), receivefax_exec(), reg_source_db(), register_group(), register_group_feature(), register_verify(), registry_authrequest(), reply_digest(), reqprep(), respprep(), save_osptoken(), sendfax_exec(), set_peer_defaults(), set_pvt_defaults(), sip_alloc(), sip_call(), sip_monitor_instance_init(), sip_msg_send(), sip_park_thread(), sip_parse_register_line(), sip_poke_peer(), sip_request_call(), sip_send_mwi_to_peer(), sip_sendtext(), sip_set_redirstr(), sip_subscribe_mwi(), sla_build_station(), sla_build_trunk(), socket_process(), startelm(), store_callerid(), t30_phase_e_handler(), tds_load_module(), transmit_refer(), transmit_register(), transmit_response_using_temp(), and update_realtime_sqlite3_db().

---

Typedef Documentation

typedef const char* ast_string_field

Definition at line 115 of file stringfields.h.

typedef uint16_t ast_string_field_allocation

Definition at line 119 of file stringfields.h.

---

Function Documentation

void* attribute_malloc __ast_calloc_with_stringfields	(	unsigned int	num_structs,
		size_t	struct_size,
		size_t	field_mgr_offset,
		size_t	field_mgr_pool_offset,
		size_t	pool_size,
		const char *	file,
		int	lineno,
		const char *	func
	)

Definition at line 1809 of file main/utils.c.

References __ast_calloc(), __ast_string_field_empty, allocation, ast_calloc, ast_string_field_pool::base, ast_string_field_mgr::embedded_pool, optimal_alloc_size(), and ast_string_field_pool::size.

{
   struct ast_string_field_mgr *mgr;
   struct ast_string_field_pool *pool;
   struct ast_string_field_pool **pool_head;
   size_t pool_size_needed = sizeof(*pool) + pool_size;
   size_t size_to_alloc = optimal_alloc_size(struct_size + pool_size_needed);
   void *allocation;
   unsigned int x;

#if defined(__AST_DEBUG_MALLOC)  
   if (!(allocation = __ast_calloc(num_structs, size_to_alloc, file, lineno, func))) {
      return NULL;
   }
#else
   if (!(allocation = ast_calloc(num_structs, size_to_alloc))) {
      return NULL;
   }
#endif

   for (x = 0; x < num_structs; x++) {
      void *base = allocation + (size_to_alloc * x);
      const char **p;

      mgr = base + field_mgr_offset;
      pool_head = base + field_mgr_pool_offset;
      pool = base + struct_size;

      p = (const char **) pool_head + 1;
      while ((struct ast_string_field_mgr *) p != mgr) {
         *p++ = __ast_string_field_empty;
      }

      mgr->embedded_pool = pool;
      *pool_head = pool;
      pool->size = size_to_alloc - struct_size - sizeof(*pool);
#if defined(__AST_DEBUG_MALLOC)
      mgr->owner_file = file;
      mgr->owner_func = func;
      mgr->owner_line = lineno;
#endif
   }

   return allocation;
}

ast_string_field __ast_string_field_alloc_space	(	struct ast_string_field_mgr *	mgr,
		struct ast_string_field_pool **	pool_head,
		size_t	needed
	)

Definition at line 1650 of file main/utils.c.

References add_string_pool(), ast_alignof, ast_assert, ast_make_room_for, AST_STRING_FIELD_ALLOCATION, and ast_string_field_mgr::last_alloc.

Referenced by __ast_string_field_ptr_build_va().

{
   char *result = NULL;
   size_t space = (*pool_head)->size - (*pool_head)->used;
   size_t to_alloc;

   /* Make room for ast_string_field_allocation and make it a multiple of that. */
   to_alloc = ast_make_room_for(needed, ast_string_field_allocation);
   ast_assert(to_alloc % ast_alignof(ast_string_field_allocation) == 0);

   if (__builtin_expect(to_alloc > space, 0)) {
      size_t new_size = (*pool_head)->size;

      while (new_size < to_alloc) {
         new_size *= 2;
      }

#if defined(__AST_DEBUG_MALLOC)
      if (add_string_pool(mgr, pool_head, new_size, mgr->owner_file, mgr->owner_line, mgr->owner_func))
         return NULL;
#else
      if (add_string_pool(mgr, pool_head, new_size, __FILE__, __LINE__, __FUNCTION__))
         return NULL;
#endif
   }

   /* pool->base is always aligned (gcc aligned attribute). We ensure that
    * to_alloc is also a multiple of ast_alignof(ast_string_field_allocation)
    * causing result to always be aligned as well; which in turn fixes that
    * AST_STRING_FIELD_ALLOCATION(result) is aligned. */
   result = (*pool_head)->base + (*pool_head)->used;
   (*pool_head)->used += to_alloc;
   (*pool_head)->active += needed;
   result += ast_alignof(ast_string_field_allocation);
   AST_STRING_FIELD_ALLOCATION(result) = needed;
   mgr->last_alloc = result;

   return result;
}

int __ast_string_field_init	(	struct ast_string_field_mgr *	mgr,
		struct ast_string_field_pool **	pool_head,
		int	needed,
		const char *	file,
		int	lineno,
		const char *	func
	)

Definition at line 1583 of file main/utils.c.

References __ast_string_field_empty, ast_string_field_pool::active, add_string_pool(), ast_free, ast_log(), ast_string_field_mgr::embedded_pool, ast_string_field_mgr::last_alloc, LOG_WARNING, ast_string_field_pool::prev, and ast_string_field_pool::used.

{
   const char **p = (const char **) pool_head + 1;
   struct ast_string_field_pool *cur = NULL;
   struct ast_string_field_pool *preserve = NULL;

   /* clear fields - this is always necessary */
   while ((struct ast_string_field_mgr *) p != mgr) {
      *p++ = __ast_string_field_empty;
   }

   mgr->last_alloc = NULL;
#if defined(__AST_DEBUG_MALLOC)
   mgr->owner_file = file;
   mgr->owner_func = func;
   mgr->owner_line = lineno;
#endif
   if (needed > 0) {    /* allocate the initial pool */
      *pool_head = NULL;
      mgr->embedded_pool = NULL;
      return add_string_pool(mgr, pool_head, needed, file, lineno, func);
   }

   /* if there is an embedded pool, we can't actually release *all*
    * pools, we must keep the embedded one. if the caller is about
    * to free the structure that contains the stringfield manager
    * and embedded pool anyway, it will be freed as part of that
    * operation.
    */
   if ((needed < 0) && mgr->embedded_pool) {
      needed = 0;
   }

   if (needed < 0) {    /* reset all pools */
      cur = *pool_head;
   } else if (mgr->embedded_pool) { /* preserve the embedded pool */
      preserve = mgr->embedded_pool;
      cur = *pool_head;
   } else {       /* preserve the last pool */
      if (*pool_head == NULL) {
         ast_log(LOG_WARNING, "trying to reset empty pool\n");
         return -1;
      }
      preserve = *pool_head;
      cur = preserve->prev;
   }

   if (preserve) {
      preserve->prev = NULL;
      preserve->used = preserve->active = 0;
   }

   while (cur) {
      struct ast_string_field_pool *prev = cur->prev;

      if (cur != preserve) {
         ast_free(cur);
      }
      cur = prev;
   }

   *pool_head = preserve;

   return 0;
}

void __ast_string_field_ptr_build	(	struct ast_string_field_mgr *	mgr,
		struct ast_string_field_pool **	pool_head,
		ast_string_field *	ptr,
		const char *	format,
			...
	)

Definition at line 1798 of file main/utils.c.

References __ast_string_field_ptr_build_va().

{
   va_list ap;

   va_start(ap, format);
   __ast_string_field_ptr_build_va(mgr, pool_head, ptr, format, ap);
   va_end(ap);
}

void __ast_string_field_ptr_build_va	(	struct ast_string_field_mgr *	mgr,
		struct ast_string_field_pool **	pool_head,
		ast_string_field *	ptr,
		const char *	format,
		va_list	ap
	)

Definition at line 1734 of file main/utils.c.

References __ast_string_field_alloc_space(), __ast_string_field_empty, __ast_string_field_release_active(), ast_align_for, ast_alignof, ast_make_room_for, AST_STRING_FIELD_ALLOCATION, available(), and ast_string_field_mgr::last_alloc.

Referenced by __ast_string_field_ptr_build().

{
   size_t needed;
   size_t available;
   size_t space = (*pool_head)->size - (*pool_head)->used;
   ssize_t grow;
   char *target;
   va_list ap2;

   /* if the field already has space allocated, try to reuse it;
      otherwise, try to use the empty space at the end of the current
      pool
   */
   if (*ptr != __ast_string_field_empty) {
      target = (char *) *ptr;
      available = AST_STRING_FIELD_ALLOCATION(*ptr);
      if (*ptr == mgr->last_alloc) {
         available += space;
      }
   } else {
      /* pool->used is always a multiple of ast_alignof(ast_string_field_allocation)
       * so we don't need to re-align anything here.
       */
      target = (*pool_head)->base + (*pool_head)->used + ast_alignof(ast_string_field_allocation);
      available = space - ast_alignof(ast_string_field_allocation);
   }

   va_copy(ap2, ap);
   needed = vsnprintf(target, available, format, ap2) + 1;
   va_end(ap2);

   if (needed > available) {
      /* the allocation could not be satisfied using the field's current allocation
         (if it has one), or the space available in the pool (if it does not). allocate
         space for it, adding a new string pool if necessary.
      */
      if (!(target = (char *) __ast_string_field_alloc_space(mgr, pool_head, needed))) {
         return;
      }
      vsprintf(target, format, ap);
      va_end(ap);
      __ast_string_field_release_active(*pool_head, *ptr);
      *ptr = target;
   } else if (*ptr != target) {
      /* the allocation was satisfied using available space in the pool, but not
         using the space already allocated to the field
      */
      __ast_string_field_release_active(*pool_head, *ptr);
      mgr->last_alloc = *ptr = target;
      AST_STRING_FIELD_ALLOCATION(target) = needed;
      (*pool_head)->used += ast_make_room_for(needed, ast_string_field_allocation);
      (*pool_head)->active += needed;
   } else if ((grow = (needed - AST_STRING_FIELD_ALLOCATION(*ptr))) > 0) {
      /* the allocation was satisfied by using available space in the pool *and*
         the field was the last allocated field from the pool, so it grew
      */
      AST_STRING_FIELD_ALLOCATION(*ptr) += grow;
      (*pool_head)->used += ast_align_for(grow, ast_string_field_allocation);
      (*pool_head)->active += grow;
   }
}

int __ast_string_field_ptr_grow	(	struct ast_string_field_mgr *	mgr,
		struct ast_string_field_pool **	pool_head,
		size_t	needed,
		const ast_string_field *	ptr
	)

Definition at line 1691 of file main/utils.c.

References AST_STRING_FIELD_ALLOCATION, and ast_string_field_mgr::last_alloc.

{
   ssize_t grow = needed - AST_STRING_FIELD_ALLOCATION(*ptr);
   size_t space = (*pool_head)->size - (*pool_head)->used;

   if (*ptr != mgr->last_alloc) {
      return 1;
   }

   if (space < grow) {
      return 1;
   }

   (*pool_head)->used += grow;
   (*pool_head)->active += grow;
   AST_STRING_FIELD_ALLOCATION(*ptr) += grow;

   return 0;
}

void __ast_string_field_release_active	(	struct ast_string_field_pool *	pool_head,
		const ast_string_field	ptr
	)

Definition at line 1713 of file main/utils.c.

References __ast_string_field_empty, ast_string_field_pool::active, ast_free, AST_STRING_FIELD_ALLOCATION, and ast_string_field_pool::prev.

Referenced by __ast_string_field_ptr_build_va().

{
   struct ast_string_field_pool *pool, *prev;

   if (ptr == __ast_string_field_empty) {
      return;
   }

   for (pool = pool_head, prev = NULL; pool; prev = pool, pool = pool->prev) {
      if ((ptr >= pool->base) && (ptr <= (pool->base + pool->size))) {
         pool->active -= AST_STRING_FIELD_ALLOCATION(ptr);
         if ((pool->active == 0) && prev) {
            prev->prev = pool->prev;
            ast_free(pool);
         }
         break;
      }
   }
}

---

Variable Documentation

const char* __ast_string_field_empty

Definition at line 1528 of file main/utils.c.

Referenced by __ast_calloc_with_stringfields(), __ast_string_field_init(), __ast_string_field_ptr_build_va(), and __ast_string_field_release_active().