From e6e433102a4f27ff85de1153976a175f190548f1 Mon Sep 17 00:00:00 2001 From: Mineplay Date: Sat, 19 Apr 2025 07:04:33 -0500 Subject: [PATCH 1/6] docs(readme): updated readme to explain features and setup for library --- README.md | 62 ++++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 61 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 4a593a3..5e68787 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,63 @@ # Hallocy -An advanced allocator library for C. \ No newline at end of file +An advanced allocator library for C. + +## Introduction + +Hallocy is an advanced C allocator library. This library implements the standard malloc, calloc, realloc, free, memset, memcopy, memmove and memcmp functions. The aim of this library is to be a better version of the standard C allocator by improving performance. Hallocy supports both Windows and Linux also keeping multithreading in mind. + +## Features + +The hallocy library offers the following features: + +- Allocating and freeing memory +- Zeroing memory on allocation +- Reallocating memory +- Copying and moving memory +- Setting memory +- Comparing memory + +## Installation + +### Prerequisites + +Ensure you have the following installed on your system: + +* CMake (minimum version 3.10) +* A compatible C compiler (e.g., GCC or MSVC) + +### Build Steps + +1. Clone the repository: + ```bash + git clone https://repo.strawhats.nl/Mineplay/Hallocy.git + ``` + +2. Navigate to the directory: + ```bash + cd Hallocy + ``` + +3. Create build directory and navigate to it: + ```bash + mkdir Build && cd Build + ``` + +4. Run CMake to configure project: + ```bash + cmake .. + ``` + +5. Build the project: + ```bash + cmake --build . --config Release + ``` + To build in debug use: + ```bash + cmake --build . + ``` + This will both generate the library and test files. + +## Using the library + +The library file can be found in the `./Build/Release` folder as Hallocy.lib for windows and in `./Build` folder as libHallocy.a for linux. To use the library file you will need to copy the Hallocy folder containing the header files and follow the setup process for a library in the build system you are using. \ No newline at end of file From c33a9a8bc835ba2e0351f77d181650a0c8eab30c Mon Sep 17 00:00:00 2001 From: Mineplay Date: Sat, 19 Apr 2025 07:28:33 -0500 Subject: [PATCH 2/6] docs(index): added index markdown file as starting file for docs --- Docs/Index.md | 12 ++++++++++++ README.md | 4 +++- 2 files changed, 15 insertions(+), 1 deletion(-) create mode 100644 Docs/Index.md diff --git a/Docs/Index.md b/Docs/Index.md new file mode 100644 index 0000000..7622610 --- /dev/null +++ b/Docs/Index.md @@ -0,0 +1,12 @@ +# Library documentation + +Welcome to the documentation of the **Hallocy C library**! + +This documentation is split into several parts: + +- [Allocator](Allocator.md) +- [Memory management](MemoryManagement.md) + +Use this as a guide for using the library within your existing project. + +> For installation and initial setup, please refer to the [README.md](../README.md). \ No newline at end of file diff --git a/README.md b/README.md index 5e68787..1eb6b9a 100644 --- a/README.md +++ b/README.md @@ -60,4 +60,6 @@ Ensure you have the following installed on your system: ## Using the library -The library file can be found in the `./Build/Release` folder as Hallocy.lib for windows and in `./Build` folder as libHallocy.a for linux. To use the library file you will need to copy the Hallocy folder containing the header files and follow the setup process for a library in the build system you are using. \ No newline at end of file +The library file can be found in the `./Build/Release` folder as Hallocy.lib for windows and in `./Build` folder as libHallocy.a for linux. To use the library file you will need to copy the Hallocy folder containing the header files and follow the setup process for a library in the build system you are using. + +For more info about how to use the library see the documentation folder named `Docs`. \ No newline at end of file From 027a8e85ef977b13e05c4215bb7540f18946c733 Mon Sep 17 00:00:00 2001 From: Mineplay Date: Sat, 19 Apr 2025 07:50:16 -0500 Subject: [PATCH 3/6] 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 +#include + +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 From 436594ae672d4a0c605a2e0c3400d0a55bbf36ac Mon Sep 17 00:00:00 2001 From: Mineplay Date: Sat, 19 Apr 2025 08:09:33 -0500 Subject: [PATCH 4/6] docs(memory management): added documentation for the memory management functions --- Docs/MemoryManagement.md | 91 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 91 insertions(+) create mode 100644 Docs/MemoryManagement.md diff --git a/Docs/MemoryManagement.md b/Docs/MemoryManagement.md new file mode 100644 index 0000000..9477a2a --- /dev/null +++ b/Docs/MemoryManagement.md @@ -0,0 +1,91 @@ +# Allocator + +This part of the library implements custom memory management functions for both windows and linux devices. + +## Featurs + +* Setting memory +* Copying memory +* Moving memory +* Comparing memory + +## Usage + +### Error handling + +When using `hallocy_set_memory`, `hallocy_copy_memory` or `hallocy_move_memory` they will return a HallocyError. This error should be handled correctly to avoid any futher problems. + +## Functions + +### Set memory + +Sets specified block of memory to specified value. + +```c +HallocyError hallocy_set_memory(void *destination, int value, const size_t size); +``` + +- `destination`: The memory to set the value of. +- `value`: The value to set the memory in destination to. +- `size`: The size of the memory in bytes to set the value of. + +### Copy memory + +Copies memory from one pointer to another pointer. + +```c +HallocyError hallocy_copy_memory(void *destination, void *source, const size_t size); +``` + +- `destination`: The memory to copy the values to. +- `source`: The memory to copy the values from. +- `size`: The size of the memory in bytes to copy the value to. + +### Move memory + +Copies memory from one pointer to another pointer. Unlike the `hallocy_copy_memory` function this function will handle overlapping memory right. + +```c +HallocyError hallocy_move_memory(void *destination, void *source, const size_t size); +``` + +- `destination`: The memory to copy the values to. +- `source`: The memory to copy the values from. +- `size`: The size of the memory in bytes to copy the value to. + +### Compare memory + +```c +bool hallocy_compare_memory(void *left_side, void *right_side, const size_t size); +``` + +- `left_side`: The memory to compare with the right side. +- `right_side`: The memory to compare with the left side. +- `size`: The size of the memory in bytes to compare the value to. + +## Example usage + +```c +#include +#include +#include + +int main() { + char *allocated_memory = hallocy_malloc(128 * sizeof(char)); + if (allocated_memory == NULL) { + return -1; + } + + HallocyError error = hallocy_memory_set(allocated_memory, 'T', 127); + if (error != HALLOCY_ERROR_NONE) { + return -1; // Check type of error here instead of returning -1 imidiatly. + } + + 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 From 89f8f2b5c4c0b2791fc2adcdce714a35bba2ba94 Mon Sep 17 00:00:00 2001 From: Mineplay Date: Sat, 19 Apr 2025 08:59:31 -0500 Subject: [PATCH 5/6] docs(allocator): added return type to functions in allocator docs --- Docs/Allocator.md | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/Docs/Allocator.md b/Docs/Allocator.md index d8116e7..559a370 100644 --- a/Docs/Allocator.md +++ b/Docs/Allocator.md @@ -35,9 +35,13 @@ 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. @@ -46,8 +50,12 @@ 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. @@ -56,9 +64,13 @@ 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. @@ -67,9 +79,13 @@ 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. @@ -78,8 +94,18 @@ 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 ```c From 6b3e24c2102827cfabca1ae033898bffb9941562 Mon Sep 17 00:00:00 2001 From: Mineplay Date: Sat, 19 Apr 2025 09:02:35 -0500 Subject: [PATCH 6/6] docs(memory management): added return type to functions in memory management docs --- Docs/MemoryManagement.md | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/Docs/MemoryManagement.md b/Docs/MemoryManagement.md index 9477a2a..972a632 100644 --- a/Docs/MemoryManagement.md +++ b/Docs/MemoryManagement.md @@ -25,10 +25,17 @@ Sets specified block of memory to specified value. HallocyError hallocy_set_memory(void *destination, int value, const size_t size); ``` +**Args**: + - `destination`: The memory to set the value of. - `value`: The value to set the memory in destination to. - `size`: The size of the memory in bytes to set the value of. +**Returns**: + +- **HALLOCY_ERROR_NONE**: Successfully set memory. +- **HALLOCY_ERROR_INVALID_POINTER**: Invalid pointer was given. + ### Copy memory Copies memory from one pointer to another pointer. @@ -37,10 +44,17 @@ Copies memory from one pointer to another pointer. HallocyError hallocy_copy_memory(void *destination, void *source, const size_t size); ``` +**Args**: + - `destination`: The memory to copy the values to. - `source`: The memory to copy the values from. - `size`: The size of the memory in bytes to copy the value to. +**Returns**: + +- **HALLOCY_ERROR_NONE**: Successfully copied memory. +- **HALLOCY_ERROR_INVALID_POINTER**: Invalid pointers where given. + ### Move memory Copies memory from one pointer to another pointer. Unlike the `hallocy_copy_memory` function this function will handle overlapping memory right. @@ -49,20 +63,31 @@ Copies memory from one pointer to another pointer. Unlike the `hallocy_copy_memo HallocyError hallocy_move_memory(void *destination, void *source, const size_t size); ``` +**Args**: + - `destination`: The memory to copy the values to. - `source`: The memory to copy the values from. - `size`: The size of the memory in bytes to copy the value to. +**Returns**: + +- **HALLOCY_ERROR_NONE**: Successfully moved memory. +- **HALLOCY_ERROR_INVALID_POINTER**: Invalid pointers where given. + ### Compare memory ```c bool hallocy_compare_memory(void *left_side, void *right_side, const size_t size); ``` +**Args**: + - `left_side`: The memory to compare with the right side. - `right_side`: The memory to compare with the left side. - `size`: The size of the memory in bytes to compare the value to. +**Returns**: True if both pointers contain same content, else returns false. + ## Example usage ```c