133 lines
No EOL
3.7 KiB
Markdown
133 lines
No EOL
3.7 KiB
Markdown
# Allocator
|
|
|
|
This part of the library implements a custom heap allocator which efficiently manages heap memory for both windows and linux devices.
|
|
|
|
## Featurs
|
|
|
|
* Memory allocation
|
|
* Freeing of memory
|
|
* Zeroing memory on allocation
|
|
* Reallocating memory from existing memory
|
|
|
|
## Usage
|
|
|
|
### Allocating
|
|
|
|
When using the library you can allocate memory using the `hallocy_allocate`, `hallocy_malloc` or `hallocy_calloc` functions. It is recommended to use `hallocy_malloc` and `hallocy_calloc` for clarity. You could also allocate memory using the `hallocy_realloc`, but this is not recommended as this is slightly slower than using the `hallocy_malloc` function.
|
|
|
|
### Freeing
|
|
|
|
When you are done with the allocated memory it is important you free it using the `hallocy_free` function. Freeing memory that is not used will not only prevent memory leaks, but also makes future allocations faster as the freeed memory blocks can be reused.
|
|
|
|
### Error handling
|
|
|
|
The `hallocy_allocate`, `hallocy_malloc`, `hallocy_calloc` and `hallocy_realloc` all return `NULL` on finding an error. These functions can return `NULL` when there is no memory available, parameters that where given where invalid or other reasons.
|
|
|
|
The `hallocy_free` function returns a `HallocyError` containing the reason for the error. When calling any Hallocy function it is important you handle these errors to prevent possible problems like trying to access an invalid memory address.
|
|
|
|
## Functions
|
|
|
|
### Allocate
|
|
|
|
Allocates memory on the heap and can zero the memory on allocation.
|
|
|
|
```c
|
|
void *hallocy_allocate(size_t size, bool zero_memory);
|
|
```
|
|
|
|
**Args**:
|
|
|
|
- `size`: The amount of bytes to allocate.
|
|
- `zero_memory`: Zero's memory when `true`.
|
|
|
|
**Returns**: Pointer to memory if successfull, else returns `NULL`.
|
|
|
|
### Malloc
|
|
|
|
Allocates memory on the heap.
|
|
|
|
```c
|
|
static inline void *hallocy_malloc(size_t size) { return hallocy_allocate(size, false); }
|
|
```
|
|
|
|
**Args**:
|
|
|
|
- `size`: The amount of bytes to allocate.
|
|
|
|
**Returns**: Pointer to memory if successfull, else returns `NULL`.
|
|
|
|
### Calloc
|
|
|
|
Allocates memory and zero's it on allocation.
|
|
|
|
```c
|
|
static inline void *hallocy_calloc(size_t size, size_t count) { return hallocy_allocate(size * count, true); }
|
|
```
|
|
|
|
**Args**:
|
|
|
|
- `size`: Size of one element in bytes.
|
|
- `count`: The amount of elements to allocate memory for.
|
|
|
|
**Returns**: Pointer to memory if successfull, else returns `NULL`.
|
|
|
|
### Realloc
|
|
|
|
Reallocates more memory for existing allocations.
|
|
|
|
```c
|
|
void *hallocy_realloc(void *memory_pointer, size_t size);
|
|
```
|
|
|
|
**Args**:
|
|
|
|
- `memory_pointer`: Pointer to already allocated heap memory.
|
|
- `size`: The size of the new allocated memory.
|
|
|
|
**Returns**: Pointer to memory if successfull, else returns `NULL`.
|
|
|
|
### Free
|
|
|
|
Free's heap memory.
|
|
|
|
```c
|
|
HallocyError hallocy_free(void *pointer);
|
|
```
|
|
|
|
**Args**:
|
|
|
|
- `pointer`: The pointer to allocated heap memory to free.
|
|
|
|
**Returns**:
|
|
|
|
- **HALLOCY_ERROR_NONE**: Successfully freeed memory.
|
|
- **HALLOCY_ERROR_INVALID_PARAM**: Invalid parameters given.
|
|
- **HALLOCY_ERROR_OUT_OF_MEMORY**: System is out of memory.
|
|
- **HALLOCY_ERROR_INVALID_POINTER**: Invalid memory address given.
|
|
- **HALLOCY_ERROR_UNKNOWN**: Unknown error.
|
|
|
|
## Example usage
|
|
|
|
```c
|
|
#include <Hallocy/Core/Allocator.h>
|
|
#include <Hallocy/Utils/Error.h>
|
|
|
|
int main() {
|
|
char *allocated_memory = hallocy_malloc(128 * sizeof(char));
|
|
if (allocated_memory == NULL) {
|
|
return -1;
|
|
}
|
|
|
|
allocated_memory = hallocy_realloc(allocated_memory, 256);
|
|
if (allocated_memory == NULL) {
|
|
return -1;
|
|
}
|
|
|
|
HallocyError error = hallocy_free(allocated memory);
|
|
if (error != HALLOCY_ERROR_NONE) {
|
|
return -1; // Check type of error here instead of returning -1 imidiatly.
|
|
}
|
|
|
|
return 0;
|
|
}
|
|
``` |