# youngyangyang04/memory-pool architecture

> Architecture diagram of the GitHub repository youngyangyang04/memory-pool, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/youngyangyang04/memory-pool
- Repository: https://github.com/youngyangyang04/memory-pool

## Overview

##### Project Type and Purpose
- This is a C++ “library/framework” project (not a client–server app) that implements custom memory‐allocation strategies (memory pools) to replace or augment malloc/free, especially in multi‐threaded contexts.
- It ships three versions (v1, v2, v3)—each stored in its own subdirectory—showing an evolution from a simple hash‐map‐based allocator (v1) to a highly optimized, multi‐layered allocator (v2 and v3).

##### File Structure Analysis
- Top‐level directories:
· v1/ – first‐cut memory‐pool implementation
· v2/ – redesigned architecture with thread‐local caching, central cache, and page cache
· v3/ – further optimizations on v2
- Each version directory follows a CMake‐based organization: include/ (public headers), src/ (implementation), tests/ (unit and performance tests).
- Configuration: CMakeLists.txt in each vX directory drives build and links tests against src.

##### README Insights
- v1: single MemoryPool class using a hash of size‐buckets + lock‐free free lists
- v2/v3: three interacting layers—ThreadCache, CentralCache, PageCache—plus spin‐locks/atomics

##### Main Components & Their Relationships
A. Version 1 (v1)
- MemoryPool:
– Buckets indexed by size class
– allocate() & deallocate() methods
– lock‐free free‐list per bucket
- User code → MemoryPool::allocate/deallocate → system calls only on block exhaustion
B. Version 2/3 (v2, v3)
- ThreadCache (per thread): local free‐list for each size class
- CentralCache (global): services batch requests from ThreadCache → avoids contention
- PageCache (global): interfaces to OS (mmap/VirtualAlloc) for large chunks; merges/splits pages
- Synchronization: spin‐locks or atomic flags in CentralCache/PageCache
- Overall call flow:
Thread code
↕ allocate()/deallocate()
ThreadCache
↕ (batch refill/return)
CentralCache
↕ (page request/return)
PageCache
↕ (mmap/munmap)
Operating System

##### Architectural Patterns & Design Principles
- Layered Caching Pattern: per‐thread → central → OS
- Size‐class segregation: fixed‐size blocks to reduce fragmentation
- Lock minimization: lock‐free structures in v1, spin‐locks/atomics in v2/v3
- Extensibility: add new size classes or plug in custom locking strategies by altering CentralCache/PageCache

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "v1 Architecture"
        direction TB
        UT1["User Threads"]:::facade
        MP1["MemoryPool"]:::facade
        OS1["Operating System"]:::os
        UT1 -->|"allocate()/deallocate()"| MP1
        MP1 -->|"system call on miss"| OS1
        UT1 -->|"unit tests"| UT1_T["UnitTest.cpp"]:::test
    end

    subgraph "v2/v3 Architecture"
        direction TB
        MP23["MemoryPool Facade"]:::facade
        TC["N× ThreadCache"]:::thread
        CC["CentralCache"]:::global
        PC["PageCache"]:::global
        OS2["Operating System"]:::os

        MP23 -->|"allocate()/deallocate()"| TC
        TC -->|"batchAlloc()/batchFree()"| CC
        CC -->|"pageRequest()/pageReturn() (spin-lock)"| PC
        PC -->|"mmap()/munmap()"| OS2
        MP23 -->|"unit & perf tests"| TEST23["UnitTest.cpp & PerformanceTest.cpp"]:::test
    end

    %% Click Events for v1
    click MP1 "https://github.com/youngyangyang04/memory-pool/blob/main/v1/include/MemoryPool.h"
    click UT1_T "https://github.com/youngyangyang04/memory-pool/blob/main/v1/tests/UnitTest.cpp"

    %% Click Events for v2
    click TC "https://github.com/youngyangyang04/memory-pool/blob/main/v2/include/ThreadCache.h"
    click CC "https://github.com/youngyangyang04/memory-pool/blob/main/v2/include/CentralCache.h"
    click PC "https://github.com/youngyangyang04/memory-pool/blob/main/v2/include/PageCache.h"
    click MP23 "https://github.com/youngyangyang04/memory-pool/blob/main/v2/include/MemoryPool.h"
    click TEST23 "https://github.com/youngyangyang04/memory-pool/blob/main/v2/tests/UnitTest.cpp"

    %% Click Events for v3
    click TC "https://github.com/youngyangyang04/memory-pool/blob/main/v3/include/ThreadCache.h"
    click CC "https://github.com/youngyangyang04/memory-pool/blob/main/v3/include/CentralCache.h"
    click PC "https://github.com/youngyangyang04/memory-pool/blob/main/v3/include/PageCache.h"
    click MP23 "https://github.com/youngyangyang04/memory-pool/blob/main/v3/include/MemoryPool.h"
    click TEST23 "https://github.com/youngyangyang04/memory-pool/blob/main/v3/tests/UnitTest.cpp"

    classDef thread fill:#AEDFF7,stroke:#333,stroke-width:1px
    classDef global fill:#B7E4C7,stroke:#333,stroke-width:1px
    classDef os fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef facade fill:#FFF3BF,stroke:#333,stroke-width:1px
    classDef test fill:#F8D7DA,stroke:#333,stroke-width:1px
```
