MEM_ALLOCATOR(9)

# NAME

*mem_alloc*, *mem_realloc*, *mem_free* - allocator interface

# SYNOPSIS

```
#include <mem/allocator.h>

typedef struct mem_allocator MemAllocator;

void *mem_alloc(MemAllocator *self, usize n);
void *mem_realloc(MemAllocator *self, void *ptr, usize n);
void mem_free(MemAllocator *self, void *ptr);
```

# DESCRIPTION

An allocator is an abstract structure capable of managing several regions of memory in such a way that allocated regions to not impinge on each other. These regions may also be freed - meaning that the allocator will try to make them available again for allocation, so as to avoid running out of memory if proper care is taken - and reallocated - changing the size of an allocated region.

*MemAllocator* defines the basic interface common to all allocators in the kernel, comprising of the 3 following operations:

	. allocation (*mem_alloc()*)
	. reallocation (*mem_realloc()*)
	. freeing (*mem_free()*)

Actual implementations of the allocator use this structure as a virtual dispatch table in order to dispatch these procedure calls to their according implementations, such as *MemFramer*.

When working with allocators, proper care must be taken in regards of the limitations of each implementations of the allocator. For example, some allocators may be limited in terms of allocated region sizes; while others may not support one or more of those 3 operations.

## Allocating

The *mem_alloc()* function is used to dispatch the allocation method call to the underlying implementation of the allocator. This function takes the following arguments:

	_self_	The allocator that should be used
	_n_	The minimal amount of char-sized units of memory the allocated region should span

## Reallocation

The *mem_realloc()* function is used to dispatch the reallocation method call to the underlying implemention of the allocator. Reallocation consists in modifying the size of a previously allocated region. *mem_realloc()* takes the following arguments:

	_self_	The allocator that should be used
	_ptr_	The previously allocated region of memory, as returned by a previous call to *mem_alloc()* or *mem_realloc()*
	_n_	The new size of the allocated region, in char-sized units

## Freeing

The *mem_free()* function is used to dispatch the free method call to the underlying imprlemention of the allocator. Freeing consists in indicating to the allocator that a region is no longer in use and that it can be reclaimed; this reclaimed memory could then, for example, be used as the result of other allocation requests by *mem_alloc()* or *mem_realloc()*. *mem_free()* takes the following arguments:

	_self_	The allocator that should be used
	_ptr_	The previously allocated region of memory, as returned by a previous call to *mem_alloc()* or *mem_realloc()*

Proper care should be taken to only free region of memory that have been allocated by a previous call to the same allocator, this includes double frees.

# RETURN VALUES

*mem_alloc()* returns the beginning of the allocated region on success, nil on error or 0 provided.
*mem_realloc()* returns the beginning of the reallocated region on success, nil on error or 0 provided. Note: in case nil, the passed region is freed.

# CODE REFERENCES

The MemAllocator interface and its dispatching functions are implemented in _mem/allocator.c_.

# SEE ALSO

mem_framer(9)