From 027a8e85ef977b13e05c4215bb7540f18946c733 Mon Sep 17 00:00:00 2001
From: Mineplay <tristanfranssen@strawhats.nl>
Date: Sat, 19 Apr 2025 07:50:16 -0500
Subject: [PATCH] docs(allocator): wrote documentation for allocator

---
 Docs/Allocator.md | 107 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 107 insertions(+)
 create mode 100644 Docs/Allocator.md

diff --git a/Docs/Allocator.md b/Docs/Allocator.md
new file mode 100644
index 0000000..d8116e7
--- /dev/null
+++ b/Docs/Allocator.md
@@ -0,0 +1,107 @@
+# 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);
+```
+
+- `size`: The amount of bytes to allocate.
+- `zero_memory`: Zero's memory when `true`.
+
+### Malloc
+
+Allocates memory on the heap.
+
+```c
+static inline void *hallocy_malloc(size_t size) { return hallocy_allocate(size, false); }
+```
+
+- `size`: The amount of bytes to allocate.
+
+### 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); }
+```
+
+- `size`: Size of one element in bytes.
+- `count`: The amount of elements to allocate memory for.
+
+### Realloc
+
+Reallocates more memory for existing allocations.
+
+```c
+void *hallocy_realloc(void *memory_pointer, size_t size);
+```
+
+- `memory_pointer`: Pointer to already allocated heap memory.
+- `size`: The size of the new allocated memory.
+
+### Free
+
+Free's heap memory.
+
+```c
+HallocyError hallocy_free(void *pointer);
+```
+
+- `pointer`: The pointer to allocated heap memory to free.
+
+## 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;
+}
+```
\ No newline at end of file