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)