suba - Sub-allocate memory from larger chunk of memory.
struct allocator *suba_init(void *mem, size_t size, int rst, size_t mincell);
void *suba_alloc(struct allocator *suba, size_t size, int zero);
int suba_free(struct allocator *suba, void *ptr);
void *suba_addr(const struct allocator *suba, const ref_t ref);
ref_t suba_ref(const struct allocator *suba, const void *ptr);
(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.
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
(2) function (or Windows equivalent), sophisticated (but
non-portable) data archives can be created easily.
A very simple and effective use for suba
(3m) is as a sub-allocator of
stack memory that is implicitly freed when the function returns as the follow
code example illustrates:
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. */
- The suba_init function initializes a new sub-allocator or attaches
to an existing allocator. The memory pointed to by the mem
parameter must be at least size bytes. When the rst
parameter is non-zero, the beginning of this memory is "reset"
meaning it is initialized with the struct allocator structure
(discarding any existing allocation state). The remaining memory, which is
size bytes minus the header, constitutes the "heap" from
which memory will be allocated and freed. If the rst parameter is
zero, the existing header is used which presumably came from shared memory
or a disk file. If the mincell parameter is non-zero, no memory
"cell" will be less than this value (i.e. if mincell is
32 alloc-ing 5 bytes results in a 32 byte cell to back it). The
mincell parameter will be increased to accomodate memory alignment
requirements if necessary. Larger values for mincell can be faster
but results in poorer memory utilization.
- The suba_alloc function returns a pointer to memory of size
bytes from the sub-allocator identified by the suba parameter. If
the zero parameter is non-zero, the memory will be set to
- The suba_free function frees the memory pointed to by ptr
back into the allocator identified by suba parameter.
- The suba_addr function converts an offset, relative to the
beginning of the sub-allocator, of the object idenfied by the ref
parameter to a pointer in the current processes address space. This
function is equivalent to the expression (char *)suba + ref but
with bounds checking.
- The suba_ref function converts a pointer ptr that points to
an object allocated from the sub-allocator identified by the suba
parameter to an offset relative to the beginning of the sub-allocator.
This function is equivalent to the expression (char *)ptr - (char
*)suba but with bounds checking. See theSuba functionssection for a
description of when it is necessary to convert pointer to a
- The suba_init function returns a sub-allocator that can be used
directly with the other suba(3m) functions or with the more general
allocator(3m) functions used by other modules in this package. If
an error occurs a null pointer is returned and errno is set
- On success, 0 is returned. On error, -1 is returned, and errno is
- The suba_addr function returns a pointer to the object referenced
by ref or NULL if the reference was invalid.
- The suba_ref function returns an offset to the object pointed to by
ptr or 0 if the pointer was invalid.