.\" 
.\" 	Copyright 2004 Michael B. Allen <mba2000 ioplex.com>
.\" 
.TH allocator 3m "Apr 29, 2005" "libmba-0.9.1" "MBA Library Functions"
.SH NAME
allocator \- Allocate and free memory.
.SH SYNOPSIS
.nf
.B #include <mba/allocator.h>
.sp

.B struct allocator *stdlib_allocator;
.sp
.B typedef int (*reclaim_fn)(struct allocator *al, void *arg, int attempt);
.B typedef void *(*new_fn)(void *context, size_t size, int flags); 
.B typedef int (*del_fn)(void *context, void *object);
.B 
.sp
.sp
.BI "void *allocator_alloc(struct allocator *" al ", size_t " size ", int " flags ");
.br
.BI "int allocator_free(struct allocator *" al ", void *" obj ");
.br
.BI "void *allocator_realloc(struct allocator *" al ", void *" obj ", size_t " size ");
.br
.BI "void allocator_set_reclaim(struct allocator *" al ", reclaim_fn " recl ", void *" arg ");
.br

.fi
.SH DESCRIPTION
The
.BR "allocator" (3m)
module defines an interface for allocating and freeing memory without defining the implementation. Modules that implement this interface such as
.BR "suba" (3m)
provide a
.I struct allocator *
that can be used with these functions. Modules that utilize this interface such as
.BR "varray" (3m)
accept the specification of an allocator. This abstraction permits changing the memory management behavior of a program by switching allocators.
.PP
.TP
.B alloc
The
.B allocator_alloc
function allocates and returns at least
.I size
bytes of memory from the allocator
.IR "al" .
The memory will be aligned appropriately for the platform. The
.I flags
parameter permits additional allocator specific information to be specified. The
.I stdlib_allocator
and
.BR "suba" (3m)
allocator support the value 1 for this flag to indicate that the memory should be set to zero (like
.IR "calloc" ).
If
.I al
is
.B NULL
memory is allocated from the
.IR "stdlib_allocator" .
.TP
.B free
The
.B allocator_free
function releases the memory pointed to by
.I obj
back to the allocator
.IR "al" .
.TP
.B realloc
The
.B allocator_realloc
function resizes the memory pointed to by
.I ptr
using the allocator
.IR "al" .
The old portion of the memory will be unchanged up to
.I size
bytes. If
.I obj
is
.BR "NULL" ,
.I size
bytes of memory will be allocated. If
.I size
is 0,
.I obj
will be freed. The pointer to
.I obj
must have been allocated previously from the allocator
.IR "al" .
.TP
.B set_reclaim
The
.B allocator_set_reclaim
function sets the function that will be called to reclaim memory when it becomes scarce. The reclaim function will be called with the provided
.I arg
parameter and may be called more than once indicating memory should be freed more agressively with each call. The
.I attempt
parameter indicates how may times the reclaim function has been called without satisfying the allocators current need. The reclaim function should return a positive value to indicate that progress in freeing memory has occured. If the reclaim function returns 0 it will not be called again and the allocation that created the memory pressure will return failure. Currently only the
.BR "suba" (3m)
module will take advantage of this feedback mechanism. See also the
.I clean
functions of other modules in this package.
.SH RETURNS
.TP
.B alloc
The
.B allocator_alloc
function returns the allocated memory or
.B NULL
if an error occured in which case
.B errno
will be set appropriately. If
.I al
is
.B NULL
the memory will be freed from the
.IR "stdlib_allocator" .
.TP
.B free
The
.B allocator_free
function returns zero upon success or -1 if an error occured in which case
.B errno
is set appropriately.
.TP
.B realloc
The
.B allocator_realloc
function returns a pointer to the resized memory which may not equal
.IR "obj" .
If an error occurs,
.B NULL
is returned and
.B errno
is set appropriately.