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

These functions should be used to allocate and free memory using an allocator(3m).

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 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.
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 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.
Returns
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.

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 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.