docs: update README with comprehensive benchmarks and thread-safe allocator

- add ThreadSafePoolAllocator to allocators list and usage examples
- include real benchmark results from Linux (GCC/Clang), macOS, and Windows
- add sanitiser build instructions (ASan, TSan with suppressions)
- document concurrent stress tests and CI infrastructure
- update project structure to reflect current codebase
- add testing section highlighting sanitiser coverage
- fix CMake version requirement (3.14+ instead of 4.0+)

Signed-off-by: NotKeira <github.rxs06@accounts.keira.boo>

Author: NotKeira

README.md

@@ -3,42 +3,66 @@
 ![CI](https://github.com/NotKeira/fast-alloc/workflows/CI/badge.svg)
 
 High-performance custom memory allocators with comprehensive benchmarks for game development and real-time applications.
+
 ## Allocators
 
 - **Pool Allocator**: Fixed-size block allocation for homogeneous objects (particles, game entities)
+- **Thread-Safe Pool Allocator**: Mutex-protected pool allocator for concurrent access
 - **Stack Allocator**: Linear allocator with frame-based reset for temporary allocations
 - **Free List Allocator**: General-purpose allocator with first-fit and best-fit strategies
 
 ## Performance
 
-Benchmarks on Windows (MSVC, Release build) demonstrate significant performance improvements over standard allocation:
+Benchmarks across multiple platforms demonstrate significant performance improvements over standard allocation:
+
+### Linux (GCC Release)
+
+| Allocator                 | Operation                   | Time   | vs Standard         | Speedup          |
+|---------------------------|-----------------------------|--------|---------------------|------------------|
+| **Pool**                  | Single allocation           | 1.97ns | 7.07ns (new/delete) | **3.6x faster**  |
+| **Stack**                 | Single allocation           | 2.20ns | 5.16ns (malloc)     | **2.3x faster**  |
+| **Stack**                 | Frame pattern (1000 allocs) | 1203ns | 12715ns (malloc)    | **10.6x faster** |
+| **Free List (First-Fit)** | Single allocation           | 4.99ns | 4.85ns (malloc)     | **Similar**      |
+| **Free List (Best-Fit)**  | Single allocation           | 5.80ns | 4.85ns (malloc)     | **Similar**      |
+
+### macOS (Apple Clang Release)
+
+| Allocator                 | Operation                   | Time   | vs Standard         | Speedup         |
+|---------------------------|-----------------------------|--------|---------------------|-----------------|
+| **Pool**                  | Single allocation           | 4.38ns | 19.4ns (new/delete) | **4.4x faster** |
+| **Stack**                 | Single allocation           | 2.37ns | 16.9ns (malloc)     | **7.1x faster** |
+| **Stack**                 | Frame pattern (1000 allocs) | 3736ns | 20393ns (malloc)    | **5.5x faster** |
+| **Free List (First-Fit)** | Single allocation           | 7.48ns | 16.5ns (malloc)     | **2.2x faster** |
+
+### Windows (MSVC Release)
 
-| Allocator                 | Operation                   | Time  | vs Standard           | Speedup         |
-|---------------------------|-----------------------------|-------|-----------------------|-----------------|
-| **Pool**                  | Single allocation           | 4.5ns | 33ns (new/delete)     | **7.3x faster** |
-| **Stack**                 | Single allocation           | 6.7ns | 31ns (malloc/free)    | **4.6x faster** |
-| **Stack**                 | Frame pattern (1000 allocs) | 5.8μs | 38μs (malloc pattern) | **6.5x faster** |
-| **Free List (First-Fit)** | Single allocation           | 15ns  | 31ns (malloc)         | **2.1x faster** |
-| **Free List (Best-Fit)**  | Single allocation           | 16ns  | 31ns (malloc)         | **1.9x faster** |
+| Allocator                 | Operation                   | Time   | vs Standard         | Speedup          |
+|---------------------------|-----------------------------|--------|---------------------|------------------|
+| **Pool**                  | Single allocation           | 2.22ns | 36.9ns (new/delete) | **16.6x faster** |
+| **Stack**                 | Single allocation           | 1.26ns | 36.2ns (malloc)     | **28.7x faster** |
+| **Stack**                 | Frame pattern (1000 allocs) | 1269ns | 44627ns (malloc)    | **35.2x faster** |
+| **Free List (First-Fit)** | Single allocation           | 5.25ns | 36.2ns (malloc)     | **6.9x faster**  |
 
 ### Key Results
 
-- **Pool Allocator**: 220M allocations/sec vs 30M with `new/delete`
-- **Stack Allocator**: 152M allocations/sec vs 33M with `malloc`
+- **Pool Allocator**: Up to 500M+ allocations/sec vs 50-150M with `new/delete`
+- **Stack Allocator**: Up to 800M+ allocations/sec vs 25-200M with `malloc`
+- **Windows shows most dramatic improvements** due to Windows heap overhead
 - **Zero fragmentation** with Pool and Stack allocators
 - **Automatic coalescence** reduces fragmentation in Free List allocator
+- **Thread-safe variant** available for concurrent workloads
 
 ## Building
 
-Requires C++20 compiler and CMake 4.0+.
+Requires C++20 compiler and CMake 3.14+.
 
 ### Windows (MSVC)
 
 ```bash
 cmake -B build
 cmake --build build --config Release
 .\build\Release\alloc_benchmarks.exe
-.\build\Debug\alloc_tests.exe
+ctest --test-dir build -C Release
 ```
 
 ### Linux/macOS
@@ -47,23 +71,44 @@ cmake --build build --config Release
 cmake -B build -DCMAKE_BUILD_TYPE=Release
 cmake --build build
 ./build/alloc_benchmarks
-./build/alloc_tests
+ctest --test-dir build --output-on-failure
+```
+
+### With Sanitizers (Linux/macOS)
+
+```bash
+# Address Sanitizer
+cmake -B build -DCMAKE_BUILD_TYPE=Debug \
+  -DCMAKE_CXX_FLAGS="-fsanitize=address -fno-omit-frame-pointer -g"
+cmake --build build
+ctest --test-dir build --output-on-failure
+
+# Thread Sanitizer
+cmake -B build -DCMAKE_BUILD_TYPE=Debug \
+  -DCMAKE_CXX_FLAGS="-fsanitize=thread -g"
+cmake --build build
+TSAN_OPTIONS="second_deadlock_stack=1 suppressions=tsan.supp" \
+  ctest --test-dir build --output-on-failure
 ```
 
 ## Project Structure
 
 ```
 fast-alloc/
 ├── src/
-│   ├── pool_allocator.h/cpp      - Fixed-size block allocator
-│   ├── stack_allocator.h/cpp     - Linear allocator with reset
-│   └── freelist_allocator.h/cpp  - General-purpose with coalescence
+│   ├── pool_allocator.h/cpp              - Fixed-size block allocator
+│   ├── threadsafe_pool_allocator.h/cpp   - Thread-safe pool allocator
+│   ├── stack_allocator.h/cpp             - Linear allocator with reset
+│   └── freelist_allocator.h/cpp          - General-purpose with coalescence
 ├── benchmarks/
 │   └── Comprehensive performance benchmarks vs malloc/new
 ├── tests/
-│   └── Unit tests with Catch2
-└── docs/
-    └── Performance analysis and implementation details
+│   ├── Unit tests with Catch2
+│   └── Concurrent stress tests for thread-safe allocators
+├── .github/workflows/
+│   └── CI with sanitizers (ASan, TSan, UBSan)
+└── tsan.supp
+    └── ThreadSanitizer suppressions for Catch2
 ```
 
 ## Usage Examples
@@ -81,6 +126,26 @@ void* obj = pool.allocate();
 pool.deallocate(obj);
 ```
 
+### Thread-Safe Pool Allocator
+
+```cpp
+#include "threadsafe_pool_allocator.h"
+#include <thread>
+
+fast_alloc::ThreadSafePoolAllocator pool(64, 1000);
+
+void worker_thread() {
+    void* obj = pool.allocate();
+    // Thread-safe allocation
+    pool.deallocate(obj);
+}
+
+std::thread t1(worker_thread);
+std::thread t2(worker_thread);
+t1.join();
+t2.join();
+```
+
 ### Stack Allocator
 
 ```cpp
@@ -123,6 +188,16 @@ Standard `malloc`/`new` are general-purpose but slow for game development patter
 
 Custom allocators exploit specific allocation patterns for dramatic performance improvements.
 
+## Testing
+
+Comprehensive test suite with Catch2:
+
+- Unit tests for all allocators
+- Move semantics validation
+- Edge case handling (nullptr, overflow, alignment)
+- Concurrent stress tests for thread-safe variants
+- CI with multiple sanitizers (ASan, TSan, UBSan)
+
 ## Licence
 
 MIT Licence - see [LICENSE](LICENSE) for details.