1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
|
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)
|
