{"id":29204345,"url":"https://github.com/thosey/lock-free-memory-pool","last_synced_at":"2025-07-02T15:03:22.217Z","repository":{"id":302345110,"uuid":"1009897748","full_name":"thosey/lock-free-memory-pool","owner":"thosey","description":"Lock-free memory pool for C++20 with thread safety and RAII support","archived":false,"fork":false,"pushed_at":"2025-07-01T21:23:29.000Z","size":30,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-01T22:24:58.171Z","etag":null,"topics":["cpp20","header-only","lockfree","memory-pool","performance","raii","thread-safe"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/thosey.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-27T23:12:16.000Z","updated_at":"2025-07-01T21:16:13.000Z","dependencies_parsed_at":"2025-07-01T22:25:04.582Z","dependency_job_id":"7e0617aa-cdc6-4638-9f16-995e0fb3ca0c","html_url":"https://github.com/thosey/lock-free-memory-pool","commit_stats":null,"previous_names":["thosey/lock-free-memory-pool"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/thosey/lock-free-memory-pool","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thosey%2Flock-free-memory-pool","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thosey%2Flock-free-memory-pool/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thosey%2Flock-free-memory-pool/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thosey%2Flock-free-memory-pool/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/thosey","download_url":"https://codeload.github.com/thosey/lock-free-memory-pool/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thosey%2Flock-free-memory-pool/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263162987,"owners_count":23423488,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cpp20","header-only","lockfree","memory-pool","performance","raii","thread-safe"],"created_at":"2025-07-02T15:01:38.667Z","updated_at":"2025-07-02T15:03:22.209Z","avatar_url":"https://github.com/thosey.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Lock Free Memory Pool\r\n\r\nA high-performance, thread-safe, lock-free memory pool implementation in C++20.\r\n\r\n## Features\r\n\r\n- **Lock-free allocation/deallocation** - Uses atomic operations with proper memory ordering for thread safety\r\n- **RAII support** - Automatic memory management with custom deleters and smart pointer integration\r\n- **Global pool management** - Easy-to-use macros for defining type-specific pools\r\n- **Header-only library** - Easy integration, just include the header\r\n- **Cross-platform** - Works on Windows, Linux, and macOS  \r\n- **Exception safe** - Proper cleanup even when constructors throw\r\n- **Performance optimized** - Cache-line alignment, search hints, and memory ordering optimizations\r\n\r\n## Quick Start\r\n\r\n### 1. Include the header\r\n```cpp\r\n#include \"LockFreeMemoryPool.h\"\r\nusing namespace lfmemorypool;\r\n```\r\n\r\n### 2. Define global pools for your types\r\n```cpp\r\n// Define pools for your types (must be at global scope, not inside namespaces)\r\nDEFINE_LOCKFREE_POOL(MyClass, 10000);  // Pool of 10,000 MyClass objects\r\nDEFINE_LOCKFREE_POOL(AnotherType, 5000);\r\n```\r\n\r\n**Important:** The `DEFINE_LOCKFREE_POOL` macro must be invoked at global scope (outside of any namespace). However, the types themselves can be in namespaces:\r\n\r\n```cpp\r\nnamespace myapp {\r\n    struct MyType { /* ... */ };\r\n}\r\n\r\n// Macro must be at global scope\r\nDEFINE_LOCKFREE_POOL(myapp::MyType, 1000);\r\n\r\nnamespace myapp {\r\n    void use_pool() {\r\n        // Usage code can be inside namespaces\r\n        auto obj = lfmemorypool::lockfree_pool_alloc_safe\u003cMyType\u003e();\r\n    }\r\n}\r\n```\r\n\r\n### 3. Use the pools\r\n```cpp\r\n// Safe allocation with RAII (recommended)\r\nauto obj1 = lockfree_pool_alloc_safe\u003cMyClass\u003e(constructor_args...);\r\n// obj1 is automatically cleaned up when it goes out of scope\r\n\r\n// Fast allocation for performance-critical paths\r\nMyClass* obj2 = lockfree_pool_alloc_fast\u003cMyClass\u003e(constructor_args...);\r\n// Must manually call lockfree_pool_free_fast(obj2) when done\r\nlockfree_pool_free_fast(obj2);\r\n```\r\n\r\n## Building\r\n\r\n### Prerequisites\r\n\r\n- **C++20 or later** compiler (GCC 10+, Clang 10+, MSVC with C++20 support)\r\n- **CMake 3.16+**\r\n- **Google Test** (automatically downloaded if not found)\r\n\r\n### Build Instructions\r\n\r\n#### Linux/macOS:\r\n```bash\r\n# Create build directory\r\nmkdir build \u0026\u0026 cd build\r\n\r\n# Configure\r\ncmake ..\r\n\r\n# Build\r\nmake -j$(nproc)\r\n\r\n# Run tests\r\nctest --verbose\r\n# or\r\nmake run_tests\r\n\r\n# Optional: Build and run examples\r\ncmake .. -DBUILD_EXAMPLES=ON\r\nmake\r\n./examples/basic_usage\r\n```\r\n\r\n#### Windows (PowerShell):\r\n```powershell\r\n# Create build directory\r\nmkdir build\r\ncd build\r\n\r\n# Configure (Visual Studio)\r\ncmake ..\r\n\r\n# Build\r\ncmake --build . --config Release\r\n\r\n# Run tests\r\nctest --verbose -C Release\r\n```\r\n\r\n### Build Options\r\n\r\n- `BUILD_TESTS=ON/OFF` - Build tests (default: ON)\r\n- `BUILD_EXAMPLES=ON/OFF` - Build usage examples (default: OFF)\r\n- `BUILD_BENCHMARKS=ON/OFF` - Build performance benchmarks (default: OFF)\r\n- `ENABLE_TSAN=ON/OFF` - Enable ThreadSanitizer for lock-free validation (default: OFF)\r\n- `ENABLE_ASAN=ON/OFF` - Enable AddressSanitizer for memory error detection (default: OFF)\r\n- `CMAKE_BUILD_TYPE=Debug/Release` - Build configuration (default: Release)\r\n\r\nExample:\r\n```bash\r\ncmake -DBUILD_EXAMPLES=ON -DBUILD_BENCHMARKS=ON -DCMAKE_BUILD_TYPE=Release ..\r\n```\r\n\r\n### Testing with ThreadSanitizer\r\n\r\n**Important**: ThreadSanitizer is essential for validating lock-free code across different CPU architectures. While the code works on Intel x86/x64 with strong memory ordering, TSan helps catch potential issues on ARM, RISC-V, and other architectures with weaker memory models.\r\n\r\n```bash\r\n# Build with ThreadSanitizer enabled\r\ncmake -DCMAKE_BUILD_TYPE=Debug -DENABLE_TSAN=ON ..\r\nmake -j$(nproc)\r\n\r\n# Run tests with TSan - will detect data races and memory ordering issues\r\n./build/test/lockfree_mempool_tests\r\n\r\n# For thorough testing, also run concurrent tests multiple times\r\nfor i in {1..10}; do ./build/test/lockfree_mempool_tests --gtest_filter=\"*Concurrent*\"; done\r\n```\r\n\r\n**Note**: ThreadSanitizer has significant performance overhead and should only be used during development and testing, not in production builds.\r\n\r\n## API Reference\r\n\r\n### Individual Pool Usage\r\n```cpp\r\n// Create a pool\r\nLockFreeMemoryPool\u003cMyType\u003e pool(1000);\r\n\r\n// Safe allocation with RAII\r\nauto obj = pool.allocate_safe(constructor_args...);\r\n\r\n// Fast allocation\r\nMyType* ptr = pool.allocate_fast(constructor_args...);\r\npool.deallocate_fast(ptr);\r\n\r\n// Get statistics\r\nauto stats = lfmemorypool::stats::get_pool_stats(pool);\r\nstd::cout \u003c\u003c \"Pool utilization: \" \u003c\u003c stats.utilization_percent \u003c\u003c \"%\" \u003c\u003c std::endl;\r\n```\r\n\r\n### Global Pool Functions\r\n```cpp\r\n// After defining pools with DEFINE_LOCKFREE_POOL\r\nauto obj = lockfree_pool_alloc_safe\u003cMyType\u003e(args...);\r\nMyType* ptr = lockfree_pool_alloc_fast\u003cMyType\u003e(args...);\r\nlockfree_pool_free_fast(ptr);\r\nauto stats = lfmemorypool::stats::lockfree_pool_stats\u003cMyType\u003e();\r\n```\r\n\r\n## Pool Statistics\r\n\r\nThe library provides comprehensive pool monitoring through the `lfmemorypool::stats` namespace. Include `LockFreeMemoryPoolStats.h` to enable statistics collection:\r\n\r\n```cpp\r\n#include \"LockFreeMemoryPoolStats.h\"\r\n\r\n// Pool instance statistics\r\nlfmemorypool::LockFreeMemoryPool\u003cMyType\u003e pool{1000};\r\nauto stats = lfmemorypool::stats::get_pool_stats(pool);\r\n\r\n// Global pool statistics\r\nauto global_stats = lfmemorypool::stats::lockfree_pool_stats\u003cMyType\u003e();\r\n\r\n// Statistics structure\r\nstruct PoolStats {\r\n    size_t total_objects;        // Total pool capacity\r\n    size_t free_objects;         // Available objects\r\n    size_t used_objects;         // Currently allocated objects  \r\n    double utilization_percent;  // Usage percentage (0-100)\r\n};\r\n\r\nstd::cout \u003c\u003c \"Pool utilization: \" \u003c\u003c stats.utilization_percent \u003c\u003c \"%\" \u003c\u003c std::endl;\r\nstd::cout \u003c\u003c \"Free objects: \" \u003c\u003c stats.free_objects \u003c\u003c \"/\" \u003c\u003c stats.total_objects \u003c\u003c std::endl;\r\n```\r\n\r\n## Performance Characteristics\r\n\r\n- **O(n) allocation** in worst case, but typically O(1) with good hint system\r\n- **O(1) deallocation**\r\n- **Lock-free** - No blocking between threads\r\n- **Memory efficient** - No fragmentation, predictable memory usage\r\n\r\n## Thread Safety\r\n\r\nThe memory pool is fully thread-safe:\r\n- Multiple threads can allocate simultaneously\r\n- Multiple threads can deallocate simultaneously  \r\n- Allocation and deallocation can happen concurrently\r\n- Uses atomic operations with proper memory ordering\r\n\r\n## Error Handling and Edge Cases\r\n\r\n### Pool Exhaustion\r\nWhen the pool is exhausted (all objects are allocated):\r\n- `allocate_safe()` returns `nullptr` (no exceptions thrown)\r\n- `lockfree_pool_alloc_safe()` returns `nullptr` (no exceptions thrown)\r\n- `allocate_fast()` returns `nullptr` (no exceptions thrown)\r\n- `lockfree_pool_alloc_fast()` returns `nullptr` (no exceptions thrown)\r\n\r\n```cpp\r\n// Safe handling of pool exhaustion\r\nauto obj = lockfree_pool_alloc_safe\u003cMyType\u003e();\r\nif (!obj) {\r\n    // Pool is exhausted - handle gracefully\r\n    std::cerr \u003c\u003c \"Pool exhausted, falling back to heap allocation\\n\";\r\n    auto heap_obj = std::make_unique\u003cMyType\u003e();\r\n    // ... continue with heap_obj\r\n}\r\n```\r\n\r\n### Constructor Exceptions\r\nIf object construction throws an exception:\r\n- Memory is automatically returned to the pool\r\n- Exception is propagated to the caller\r\n- Pool remains in a consistent state\r\n\r\n```cpp\r\nstruct ThrowingType {\r\n    ThrowingType() { throw std::runtime_error(\"Construction failed\"); }\r\n};\r\n\r\ntry {\r\n    auto obj = lockfree_pool_alloc_safe\u003cThrowingType\u003e();\r\n    // obj will be nullptr - exception was caught internally\r\n} catch (const std::exception\u0026 e) {\r\n    // This won't be reached for safe allocation\r\n    // Fast allocation would propagate the exception\r\n}\r\n```\r\n\r\n### Invalid Pointer Handling\r\n- `deallocate_fast()` and `lockfree_pool_free_fast()` are safe with `nullptr`\r\n- **Performance Note**: For maximum speed, the library does not validate that pointers belong to the pool\r\n- Passing invalid pointers results in undefined behavior - users must ensure correct usage\r\n- Debug builds may catch some invalid usage through assertions\r\n\r\n```cpp\r\n// Safe usage patterns\r\nMyType* obj = lockfree_pool_alloc_fast\u003cMyType\u003e();\r\nif (obj) {\r\n    // ... use obj\r\n    lockfree_pool_free_fast(obj);  // Safe\r\n}\r\n\r\nlockfree_pool_free_fast(nullptr);  // Safe - no-op\r\n\r\n// INCORRECT - undefined behavior:\r\n// MyType external_obj;\r\n// lockfree_pool_free_fast(\u0026external_obj);  // DON'T DO THIS!\r\n```\r\n\r\n### Memory Ordering Guarantees\r\n- All atomic operations use appropriate memory ordering\r\n- `acquire-release` semantics for allocation/deallocation synchronization\r\n- `relaxed` ordering for performance hints (search start position)\r\n- See code comments for detailed memory ordering rationale\r\n\r\n## License\r\n\r\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\r\n\r\n## Contributing\r\n\r\nContributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.\r\n\r\n## Performance Benchmarking\r\n\r\nThis project includes comprehensive performance benchmarks using **Google Benchmark**, a popular C++ benchmarking framework. The benchmarks provide detailed performance measurements comparing heap allocation to pool allocation.\r\n\r\n### Quick Performance Test\r\n```bash\r\n# Install Google Benchmark (Ubuntu/Debian)\r\nsudo apt install libbenchmark-dev\r\n\r\n# Build and run\r\ncmake -B build -DBUILD_BENCHMARKS=ON\r\ncmake --build build\r\nmake -C build run_google_benchmark\r\n```\r\n\r\nThe Google Benchmark suite includes:\r\n- **Allocation Benchmarks**: Heap vs Pool (safe/fast) across different object counts\r\n- **Multi-threaded Benchmarks**: Concurrent allocation performance\r\n- **Fragmentation Tests**: Realistic allocation/deallocation patterns\r\n- **Mixed Workloads**: Combined allocation patterns\r\n\r\nFor installation and detailed usage, see [benchmarks/README.md](benchmarks/README.md).\r\n\r\n## Examples\r\n\r\nSee the [`examples/`](examples/) directory for comprehensive usage demonstrations:\r\n\r\n- **[basic_usage.cpp](examples/basic_usage.cpp)** - Complete example showing safe/fast allocation, thread safety, pool exhaustion handling, and exception safety\r\n- **[Examples README](examples/README.md)** - Detailed explanation of all example programs\r\n\r\nQuick example run:\r\n```bash\r\ncmake -B build -DBUILD_EXAMPLES=ON\r\ncmake --build build\r\n./build/examples/basic_usage\r\n```\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthosey%2Flock-free-memory-pool","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthosey%2Flock-free-memory-pool","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthosey%2Flock-free-memory-pool/lists"}