POOL_ALLOC(3)

NAME
pool_alloc, pool_free, pool_talloc, pool_tfree, pool_create, pool_destroy - Allocate and free memory in managed allocation pools.

SYNOPSIS
#include pool_alloc.h struct alloc_pool *pool_create(size_t size, size_t quantum, void (*bomb)(char *), int flags); void pool_destroy(struct alloc_pool *pool); void *pool_alloc(struct alloc_pool *pool, size_t size, char *msg); void pool_free(struct alloc_pool *pool, sise_t size, void *addr); void *pool_talloc(struct alloc_pool *pool, type), int count, char *msg); void pool_tfree(struct alloc_pool *pool, type, int count, void *addr);

DESCRIPTION

The pool allocation routines use malloc() for underlying memory management. What allocation pools do is cause memory within a given pool to be in large contigious blocks (called extents) that when freed will be reusable. Unlike malloc() the allocations are not managed individually. Instead each extent tracks the total free memory within the extent. Each extent can either be used to allocate memory or to manage the freeing of memory within that extent. When an extent has less free memory than a given allocation request or when the first request to free memory within that extent is received the extent ceases to be used for allocation.

This form of memory management is suited to large numbers of small related allocations that are held for a while and then freed as a group. Because the underlying allocations are done in large contigious extents when an extent is freed it releases a large enough contigious block of memory to be useful to subsequent malloc() and pool_alloc() calls even if allocations from other pools or from malloc() are made between allocations from a given pool.

pool_create() Creates an allocation pool for subsequent calls to the pool allocation functions. When an extent is created for allocations it will be size bytes. Allocations from the pool have their sizes rounded up to a multiple of quantum bytes in length. Specifying 0 for quantum Will produce a quantum that should meet maximal allignment on most platforms. If the POOL_QALIGN flag is set allocations will be aligned to addresses that are a multiple of quantum. If the POOL_CLEAR flag is set all allocations from the pool will be zero filled.

pool_destroy() destroys an allocation pool and frees all memory allocated in that pool.

pool_alloc() allocates size bytes from the specified pool. If size is 0 quantum bytes will be freed. If the requested memory cannot be allocated pool_alloc() will call bomb() function, if defined, with msg as it's sole argument and NULL will be returned.

pool_free() frees size bytes pointed to by addr previously allocated in the specified pool. The memory freed within an extent will not be reusable until all of the memory in that extent has been freed but depending on the order in which the allocations are freed some extents may be released for reuse while others are still in use. If size is 0 quantum bytes will be freed. If addr is 0 no memory will be freed but subsequent allocations will come from a new extent.

pool_talloc() is a macro that take a type and count instead of size and will cast the return value to the correct type.

pool_tfree is a macro to free memory previously allocated in the specified pool.

RETURN VALUE
pool_create() returns a pointer to struct alloc_pool.

pool_alloc() and pool_talloc() return pointers to the allocated memory, or NULL if the request fails. For each extent so long as no allocations are smaller than varaible allignment requirements this pointer will be suitably alligned for any kind of variable. The return type of pool_alloc() will normally require casting to the desired type but pool_talloc() will returns a pointer of the requested type.

pool_free(), pool_tfree() and pool_destroy() return no value.

SEE ALSO
malloc(3)

AUTHOR
pool_alloc was created by J.W. Schultz of Pegasystems Technologies.

BUGS AND ISSUES