Module: alloc
Synopsis
#include <core/alloc.h>
This module controls how the API should allocate memory. Although dynamic allocation isn't much used in the core API, it is used in few places where static arrays would not fit (e.g. loading maps).
Macros
ALLOC_POOL_INIT_DEFAULT
Default size to allocate in struct alloc_pool.
Warning
Must be a power of 2.
#define ALLOC_POOL_INIT_DEFAULT 32
Structs
alloc_funcs
Allocator functions.
Warning
When changing allocator using alloc_set all functions must be set.
Field | Access | Type |
---|---|---|
alloc | (+?) | void *(*)(size_t) |
realloc | (+?) | void *(*)(void *, size_t) |
free | (+?) | void (*)(void *) |
alloc
Allocate the given size
of bytes. Returns the allocated memory (or NULL on
failure).
The default implementation uses malloc and calls panic in case of failure.
Note
You should set an error in case of failure.
void *(*alloc)(size_t size)
realloc
Realloc the region ptr
with the new given size
. Returns the new memory (may
be NULL).
The default implementation uses malloc and calls panic in case of failure.
Note
You should set an error in case of failure.
void *(*realloc)(void *ptr, size_t size)
free
Free memory pointed by ptr
.
The default implementation calls standard C free function.
void (*free)(void *ptr)
alloc_pool
Pool allocator.
This small structure is a helper to reallocate data each time a new slot is requested. It allocates twice as the current storage when size exceeds capacity.
It uses realloc mechanism to upgrade the new storage space so pointers returned must not be referenced directly.
It is designed in mind to help allocating resources locally that may be referenced in another module without having to manage an array from the user code. Because it is designed for this responsability only it only supports insertion.
The initial capacity is controlled by the ALLOC_POOL_INIT_DEFAULT macro and must be a power of two.
A custom finalizer function can be set to finalize each individual object if necessary.
Field | Access | Type |
---|---|---|
data | (+?) | void * |
elemsize | (-) | size_t |
size | (-) | size_t |
capacity | (-) | size_t |
data
Pointer to the region.
void *data
elemsize
Size of individual element.
size_t elemsize
size
Number of items in array.
size_t size
capacity
Current capacity.
size_t capacity
finalizer
Optional finalizer that should finalize the object pointed by data
.
This function will be invoked for every element when alloc_pool_finish is called.
void (*finalizer)(void *data)
Functions
alloc_set
Use funcs
as the new allocator routines. It must be kept valid
until the program is no longer used.
void
alloc_set(const struct alloc_funcs *funcs)
alloc_new
Allocate new uninitialized data of the given size
. Returns the result of the
current allocator alloc function set.
void *
alloc_new(size_t size)
alloc_new0
Invoke alloc_new but zero initialize the memory.
void *
alloc_new0(size_t size)
alloc_array
Allocate an uninitialized array of n
elements of size
individually. Returns
the result of the current alloc function set.
void *
alloc_array(size_t n, size_t size)
alloc_array0
Invoke alloc_array but zero initialize the memory.
void *
alloc_array0(size_t n, size_t size)
alloc_renew
Reallocate the pointer ptr
(which may be NULL) to the new amount
size. The
size can be 0. Returns the result of the current alloc function set.
void *
alloc_renew(void *ptr, size_t amount)
alloc_rearray
Reallocate the ptr
(which may be NULL) as an array of n
elements of size
individually. Returns the result of the current alloc function set.
void *
alloc_rearray(void *ptr, size_t n, size_t size)
alloc_dup
Duplicate the ptr
region with the given size
.
void *
alloc_dup(const void *ptr, size_t size)
alloc_pool_init
Initialize the pool
as an array where elements have elemsize
size. Optional
finalizer
argument can be passed to finalize every element when
clearing the pool.
This will effectively create a initial storage according to ALLOC_POOL_INIT_DEFAULT.
Returns false on errors depending on the result of the of the current alloc function set.
bool
alloc_pool_init(struct alloc_pool *pool, size_t elemsize, void (*finalizer)(void *))
alloc_pool_new
Request a new slot from the pool
.
If the current size has reached the capacity, it will be doubled in that case it is possible that all previous pointer may be invalidated.
Returns NULL on errors depending on the result of the of the current realloc function set.
void *
alloc_pool_new(struct alloc_pool *pool)
alloc_pool_get
Get the value at the given index
from the pool
.
Warning
Undefined behavior if index
is out of bounds.
void *
alloc_pool_get(const struct alloc_pool *pool, size_t index)
alloc_pool_finish
inalize the pool
and all individual element if a finalizer is set.
You must call alloc_pool_init again before reusing it.
void
alloc_pool_finish(struct alloc_pool *pool)