NAME
genalloc_ready_tuned, genalloc_ready, genalloc_readyplus, genalloc_free, genalloc_deepfree, genalloc_deepfree_size, genalloc_shrink - allocate and free memory associated with a genalloc
SYNOPSIS
#include <limb/genalloc.h>
int genalloc_ready_tuned(type, genalloc *ga, int num, size_t base, size_t a, size_t b) int genalloc_ready(type, genalloc *ga, int num) int genalloc_readyplus(type, genalloc *ga, int num) int genalloc_shrink(type, genalloc *ga) void genalloc_free(type, genalloc *ga) void genalloc_deepfree(type, genalloc *ga, free_func *fn) void genalloc_deepfree_size(genalloc *ga, free_func *fn, size_t len)
DESCRIPTION
The genalloc_ready() macro ensure that genalloc pointed by ga has enough
memory for num elements of type type, reallocating memory if needed.
This does not mean as much is available, as there might be data in use already.
The genalloc_readyplus() macro ensure that genalloc pointed by ga has enough
memory available for num more elements of type type, reallocating memory if
needed. Available here means space that is allocated but not yet in use, making
this the most commonly used way to prepare a genalloc before writing data into
it.
The genalloc_ready_tuned() is similar to genalloc_ready() but with more
fine-tuning settings.
Note that this is only needed when writing into the genalloc directly, as all functions of the genalloc API (e.g. genalloc_append(3)) handles that automatically.
The genalloc_shrink() macro will ensure that the allocated memory is only
as large as is in use in genalloc ga.
The genalloc_deepfree_size() function is useful when storing pointers in a
genalloc, or any data that must have associated memory freed for each elements.
It will iterate over the data in genalloc ga - which must contain elements of
len bytes - and call the function fn with the address of each element as
argument.
Once done, it will free all memory associated with the genalloc ga itself.
The genalloc_deepfree() macro is similar to genalloc_deepfree_size() but for
genalloc containing elements of type type.
The genalloc_free() macro will free all memory associated with the genalloc
ga.
RETURN VALUE
These functions (except for genalloc_free(), genalloc_deepfree() and
genalloc_deepfree_size()) return 1 on success. Otherwise they return 0 and
set errno to indicate the error.
ERRORS
The genalloc_ready_tuned(), genalloc_ready() and genalloc_readyplus()
functions may fail for the errors described for stralloc_ready_tuned(3),
stralloc_ready(3) and stralloc_readyplus(3), respectively.
The genalloc_shrink() function may fail for the errors described for
stralloc_shrink(3).