.\" 
.\" 	Copyright 2004 Michael B. Allen <mba2000 ioplex.com>
.\" 
.TH suba 3m "Apr 29, 2005" "libmba-0.9.1" "MBA Library Functions"
.SH NAME
suba \- Sub-allocate memory from larger chunk of memory.
.SH SYNOPSIS
.nf
.B #include <mba/suba.h>
.sp
.BI "struct allocator *suba_init(void *" mem ", size_t " size ", int " rst ", size_t " mincell ");
.br
.BI "void *suba_alloc(struct allocator *" suba ", size_t " size ", int " zero ");
.br
.BI "int suba_free(struct allocator *" suba ", void *" ptr ");
.br
.BI "void *suba_addr(const struct allocator *" suba ", const ref_t " ref ");
.br
.BI "ref_t suba_ref(const struct allocator *" suba ", const void *" ptr ");
.br

.fi
.SH DESCRIPTION
The
.BR "suba" (3m)
module provides a "sub-allocator" that can allocate and free memory from a larger fixed size chunk of memory. This allocator is lock-less but reentrant meaning it will be faster but more consideration is necessary for coordinating multiple threads as opposed to the standard C library allocator.
.sp
All objects within the allocator are tracked using offsets relative to the beginning of the sub-allocator and all offsets and state are stored as part of the memory being sub-allocated. Thus the memory backing the allocator can be copied and deleted without being deinitialized to achive a variety of useful effects. The memory of an allocator can be copied temporarily to implement transaction control or checkpoints. Complex data structures can be manipulated by multiple processes in shared memory. When used with the POSIX
.BR "mmap" (2)
function (or Windows equivalent), sophisticated (but non-portable) data archives can be created easily.
.sp
A very simple and effective use for
.BR "suba" (3m)
is as a sub-allocator of stack memory that is implicitly freed when the function returns as the follow code example illustrates:
.PP
.RS
.nf
.ta 4n 19n 31n

int
myfn(void)
{
    unsigned char chunk[0x3FFF]; /* 16K */
    struct allocator *al = suba_init(chunk, 0x3FFF, 1, 0);
    struct hashmap map;

    hashmap_init(&map, 0, hash_text, cmp_text, NULL, al);

    /* use hashmap and allocator ... */

    return 0; /* no cleanup necessary; all memory on stack. */
}

.ta
.fi
.RE
.PP

.PP
.TP
.B init
The
.B suba_init
function initializes a new sub-allocator or attaches to an existing allocator. The memory pointed to by the
.I mem
parameter must be at least
.I size
bytes. When the
.I rst
parameter is non-zero, the beginning of this memory is "reset" meaning it is initialized with the
.I struct allocator
structure (discarding any existing allocation state). The remaining memory, which is
.I size
bytes minus the header, constitutes the "heap" from which memory will be allocated and freed. If the
.I rst
parameter is zero, the existing header is used which presumably came from shared memory or a disk file. If the
.I mincell
parameter is non-zero, no memory "cell" will be less than this value (i.e. if
.I mincell
is 32 alloc-ing 5 bytes results in a 32 byte cell to back it). The
.I mincell
parameter will be increased to accomodate memory alignment requirements if necessary. Larger values for
.I mincell
can be faster but results in poorer memory utilization.
.TP
.B alloc
The
.B suba_alloc
function returns a pointer to memory of
.I size
bytes from the sub-allocator identified by the
.I suba
parameter. If the
.I zero
parameter is non-zero, the memory will be set to zero.
.TP
.B free
The
.B suba_free
function frees the memory pointed to by
.I ptr
back into the allocator identified by
.B suba
parameter.
.TP
.B addr
The
.B suba_addr
function converts an offset, relative to the beginning of the sub-allocator, of the object idenfied by the
.I ref
parameter to a pointer in the current processes address space. This function is equivalent to the expression
.I (char *)suba + ref
but with bounds checking.
.TP
.B ref
The
.B suba_ref
function converts a pointer
.I ptr
that points to an object allocated from the sub-allocator identified by the
.I suba
parameter to an offset relative to the beginning of the sub-allocator. This function is equivalent to the expression
.I (char *)ptr - (char *)suba
but with bounds checking. See theSuba functionssection for a description of when it is necessary to convert pointer to a reference.
.SH RETURNS
.TP
.B init
The
.B suba_init
function returns a sub-allocator that can be used directly with the other
.BR "suba" (3m)
functions or with the more general
.BR "allocator" (3m)
functions used by other modules in this package. If an error occurs a null pointer is returned and
.I errno
is set accordingly.
.TP
.B free
On success, 0 is returned. On error, -1 is returned, and
.I errno
is set appropriately.
.TP
.B addr
The
.B suba_addr
function returns a pointer to the object referenced by
.I ref
or
.I NULL
if the reference was invalid.
.TP
.B ref
The
.B suba_ref
function returns an offset to the object pointed to by
.I ptr
or 0 if the pointer was invalid.