Allocator

# 1. Allocator

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.

### 1.1.

Definitions
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);

Description
The global `stdlib_allocator` provides an allocator that uses the malloc(3), calloc(3), and free(3) functions from the standard C library.

The `reclaim_fn` definition is to be used with the `allocator_set_reclaim` function. The `new_fn` and `del_fn` functions are used with other modules like `pool`(3m). With a cast it is reasonable to use the `allocator_alloc` and `allocator_free` functions where `new_fn` and `del_fn` functions might be used.

### 1.2. Allocator functions

The functions should be used to allocate and free memory using an allocator.

The `allocator_alloc` function
Synopsis

      #include <mba/allocator.h>
      void *allocator_alloc(struct allocator *al, size_t size, int flags);

Description
The `allocator_alloc` function allocates and returns `size` bytes of memory from the allocator `al`. The `flags` parameter permits additional 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`.
Returns
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`.

The `allocator_free` function
Synopsis

      #include <mba/allocator.h>
      int allocator_free(struct allocator *al, void *obj);

Description
The `allocator_free` function releases the memory pointed to by `obj` back to the allocator `al`.
Returns
The `allocator_free` function returns zero upon success or -1 if an error occured in which case `errno` is set appropriately.

The `allocator_realloc` function
Synopsis

      #include <mba/allocator.h>
      void *allocator_realloc(struct allocator *al, void *obj, size_t size);

Description
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 `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`.
Returns
The `allocator_realloc` function returns a pointer to the resized memory which may not equal `obj` or `NULL` if an error occured in which case `errno` is set appropriately.

The `allocator_set_reclaim` function
Synopsis

      #include <mba/allocator.h>
      void allocator_set_reclaim(struct allocator *al, reclaim_fn recl, void *arg);

Description
The `allocator_set_reclaim` function sets the function to 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.

Copyright 2004 Michael B. Allen <mba2000 ioplex.com>