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.

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.

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.

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.

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.

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

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