Hallocy/Docs/Allocator.md

# 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;
}
```