alloc_ctx

NAME: alloc_ctx - standard memory allocator abstraction

SYNOPSIS

#include <alloc_ctx.h>

int AC_delete(ctxp)
  alloc_ctx    *ctxp;

VOID *AC_calloc(ctx, nelem, elsize)
  alloc_ctx     ctx;
  unsigned int  nelem;
  unsigned int  elsize;

int  AC_free(ctx, ptr)
  alloc_ctx     ctx;
  VOID         *ptr;

VOID *AC_malloc(ctx, size)
  alloc_ctx     ctx;
  unsigned int  size;

VOID *AC_realloc(ctx, ptr, size)
  alloc_ctx     ctx;
  VOID         *ptr;
  unsigned int  size;

/*
 *    standard_heap -- by default normal calls to malloc(),
 *    calloc(), realloc(), and free(), without garbage
 *    collection or anything fancy
 */
alloc_ctx  standard_heap;

DESCRIPTION

alloc_ctx is a memory allocation abstraction based on the standard malloc allocator package. Except for AC_delete() (which is unique to alloc_ctx), this package is intended to behave identically to the standard malloc package.

AC_delete() deletes the alloc_ctx. In some alloc_ctx implementations, it may also free any memory that alloc_ctx functions have allocated in that context.

See documentation on malloc for information on the individual malloc-based routines: AC_calloc(), AC_free(), AC_malloc(), and AC_realloc().

RETURN VALUES

On success, AC_delete() returns NO_ERROR. On failure, AC_delete() returns ALLOC_CTX_ERR_BAD_PARAMETER.

See Return Values for descriptions of individual error codes. For documentation on displaying or logging return values, see error_ctx.

See documentation on malloc for the return values of the individual malloc-based routines: AC_calloc(), AC_free(), AC_malloc(), and AC_realloc().

SEE ALSO: alloc_ctx_pool

NOTES

The ctx argument must be initialized prior to use. See alloc_ctx_pool for information on creating an alloc_ctx.

standard_heap maps the alloc_ctx abstraction onto the built-in malloc package. For example, calls to AC_malloc() are directly mapped to malloc(). For standard_heap, AC_delete() does not deallocate memory allocated by the other calls.

Pointers obtained from one alloc_ctx should not be passed as parameters in calls using a different alloc_ctx.

AC_delete(), AC_calloc(), AC_free(), AC_malloc(), and AC_realloc() are macros, but only the ctx argument appears more than once in the macro expansion. Therefore, it is safe to use computed arguments, such as those using the ++ or -- operator, for all arguments except ctx. These macros should always be used to invoke the underlying functions, rather than invoking the functions directly.

BUGS: This document describes a beta implementation. The information contained in this document may be incomplete and is subject to change.