NAME

allocator - Allocate and free memory.

SYNOPSIS

#include <mba/allocator.h>

struct allocator *stdlib_allocator;

typedef int (*reclaim_fn)(struct allocator *al, void *arg, int attempt);
typedef void *(*new_fn)(void *context, size_t size, int flags);
typedef int (*del_fn)(void *context, void *object);


void *allocator_alloc(struct allocator *al, size_t size, int flags);


int allocator_free(struct allocator *al, void *obj);


void *allocator_realloc(struct allocator *al, void *obj, size_t size);


void allocator_set_reclaim(struct allocator *al, reclaim_fn recl, void *arg);

DESCRIPTION

The allocator(3m) module defines an interface for allocating and freeing memory without defining the implementation. Modules that implement this interface such as suba(3m) provide a struct allocator * that can be used with these functions. Modules that utilize this interface such as varray(3m) accept the specification of an allocator. This abstraction permits changing the memory management behavior of a program by switching allocators.

alloc: The allocator_alloc function allocates and returns at least size bytes of memory from the allocator al. The memory will be aligned appropriately for the platform. The flags parameter permits additional allocator specific information to be specified. The stdlib_allocator and suba(3m) allocator support the value 1 for this flag to indicate that the memory should be set to zero (like calloc). If al is NULL memory is allocated from the stdlib_allocator.
free: The allocator_free function releases the memory pointed to by obj back to the allocator al.
realloc: The allocator_realloc function resizes the memory pointed to by ptr using the allocator al. The old portion of the memory will be unchanged up to size bytes. If obj is NULL, size bytes of memory will be allocated. If size is 0, obj will be freed. The pointer to obj must have been allocated previously from the allocator al.
set_reclaim: The allocator_set_reclaim function sets the function that will be called to reclaim memory when it becomes scarce. The reclaim function will be called with the provided arg parameter and may be called more than once indicating memory should be freed more agressively with each call. The attempt parameter indicates how may times the reclaim function has been called without satisfying the allocators current need. The reclaim function should return a positive value to indicate that progress in freeing memory has occured. If the reclaim function returns 0 it will not be called again and the allocation that created the memory pressure will return failure. Currently only the suba(3m) module will take advantage of this feedback mechanism. See also the clean functions of other modules in this package.

RETURNS

alloc: The allocator_alloc function returns the allocated memory or NULL if an error occured in which case errno will be set appropriately. If al is NULL the memory will be freed from the stdlib_allocator.
free: The allocator_free function returns zero upon success or -1 if an error occured in which case errno is set appropriately.
realloc: The allocator_realloc function returns a pointer to the resized memory which may not equal obj. If an error occurs, NULL is returned and errno is set appropriately.