Skip to content

docs(advanced): document memory pool and allocator architecture#370

Merged
kcenon merged 2 commits into
mainfrom
docs/issue-366-document-memory-pool-and-allocator
Feb 9, 2026
Merged

docs(advanced): document memory pool and allocator architecture#370
kcenon merged 2 commits into
mainfrom
docs/issue-366-document-memory-pool-and-allocator

Conversation

@kcenon

@kcenon kcenon commented Feb 9, 2026 •
edited
Loading

Copy link
Copy Markdown
Owner

Closes #366

Summary

  • Add docs/advanced/MEMORY_MANAGEMENT.md covering internal memory management
  • Document fixed_block_pool: intrusive free list architecture, chunk growth, O(1) alloc/dealloc
  • Document pool_allocator: thread-local singleton, 3-tier size-class routing (small<=64B, medium<=256B, large=heap)
  • Document helper functions: pool_allocate<T>(), pool_deallocate<T>(), is_pool_allocatable<T>()
  • Cover integration with value_container via CONTAINER_USE_MEMORY_POOL CMake option
  • Include performance analysis, configuration options, and best practices

Test Plan

  • Verify documentation renders correctly on GitHub
  • Cross-reference API descriptions against internal/memory_pool.h and internal/pool_allocator.h
  • Confirm code examples use correct APIs and would compile
  • Verify size class thresholds (64B, 256B) and parameters (1024 blocks/chunk) match source

@kcenon
docs(advanced): document memory pool and allocator architecture
5ea222b 
Add comprehensive documentation for internal memory management:
- fixed_block_pool: intrusive free list, chunk growth, thread safety
- pool_allocator: thread-local singleton, size-class routing (small/medium/large)
- Integration with value_container via CONTAINER_USE_MEMORY_POOL
- Performance analysis: allocation throughput, fragmentation, cache locality
- Configuration: CMake options, pool parameters, pre-allocation strategy
- Best practices: when to use pool vs heap, monitoring, sizing recommendations
@kcenon kcenon mentioned this pull request Feb 9, 2026
Closed
6 tasks
@kcenon
docs: fix 7 source-code cross-reference discrepancies in MEMORY_MANAG…
ab6f847 
…EMENT.md

- Add `explicit` keyword to fixed_block_pool constructor signature and API table
- Add `~fixed_block_pool()` destructor row to API reference table
- Add try-catch error handling (std::bad_alloc, std::runtime_error) to allocate()
- Add #ifndef NDEBUG debug validation block to deallocate() code snippet
- Fix allocate_chunk_unlocked(): std::make_unique → new (matches source)
- Add pool_stats::hit_rate() method to struct documentation
- Replace CONTAINER_USE_MEMORY_POOL pseudocode with actual implementation
- Use pool_stats::hit_rate() in monitoring example instead of manual calc
@kcenon

kcenon commented Feb 9, 2026

Copy link
Copy Markdown
Owner Author

Test Plan Verification

1. GitHub Rendering Verification

  • Status: PASS
  • All markdown elements (tables, code blocks, ASCII diagrams, headings) render correctly

2. Cross-Reference with Source Code

  • Status: PASS (after fixes)
  • Code-reviewer agent performed 18 cross-reference checks
  • Initial run: 11 PASS, 7 FAIL
  • All 7 discrepancies fixed in commit ab6f847:
    1. Added explicit keyword to fixed_block_pool constructor signature
    2. Added ~fixed_block_pool() destructor to API reference table
    3. Added try-catch error handling (std::bad_alloc, std::runtime_error) to allocate() code snippet
    4. Added #ifndef NDEBUG debug validation block to deallocate() code snippet
    5. Fixed allocate_chunk_unlocked(): std::make_unique → new (matches source)
    6. Added pool_stats::hit_rate() method to struct documentation
    7. Replaced CONTAINER_USE_MEMORY_POOL pseudocode with actual implementation from source

3. Code Examples Accuracy

  • Status: PASS
  • All code examples now match source code in internal/memory_pool.h and internal/pool_allocator.h
  • pool_stats struct matches core/container/types.h including hit_rate() method
  • Monitoring example updated to use pool_stats::hit_rate() instead of manual calculation

@kcenon

kcenon commented Feb 9, 2026

Copy link
Copy Markdown
Owner Author

Test Plan Verification (Final)

1. GitHub Rendering Verification

  • Status: ✅ PASS
  • All 25 CI checks passed (including generate_docs)
  • Markdown tables, code blocks, ASCII diagrams, and headings render correctly
  • CI results:
    • CI (gcc, clang, msvc, macos): All PASS
    • Integration Tests (Debug/Release, macOS/Ubuntu): All PASS
    • Sanitizers (Address, Thread, UndefinedBehavior): All PASS
    • Static Analysis (Clang-Tidy, Cppcheck): All PASS
    • Security (Trivy, security-scan): All PASS
    • Coverage, SBOM, Linux ARM64, Performance Baseline: All PASS

2. Cross-Reference API Descriptions

  • Status: ✅ PASS
  • Code-reviewer agent performed comprehensive cross-reference (18 checks)
  • Initial review found 7 discrepancies → all fixed in commit ab6f847
  • Post-fix verification: All API signatures, method implementations, error handling, and struct definitions match source
  • Verified files: internal/memory_pool.h, internal/pool_allocator.h, core/container/types.h, CMakeLists.txt

3. Code Examples Accuracy

  • Status: ✅ PASS
  • All code examples use correct APIs and would compile
  • Constructor, allocate/deallocate, pool_allocator::instance(), helper functions all verified
  • pool_stats::hit_rate() method correctly documented and used in monitoring example

4. Size Class Thresholds Match Source

  • Status: ✅ PASS
  • small_threshold = 64: Matches pool_allocator.h:59
  • medium_threshold = 256: Matches pool_allocator.h:60
  • blocks_per_chunk = 1024: Matches pool_allocator.h:61
  • CONTAINER_USE_MEMORY_POOL: Matches CMakeLists.txt:48 (default: ON)

Overall Result: All 4 test plan items PASS ✅

@kcenon kcenon merged commit 87b614d into main Feb 9, 2026
25 checks passed
@kcenon kcenon deleted the docs/issue-366-document-memory-pool-and-allocator branch February 9, 2026 01:28
kcenon added a commit that referenced this pull request Apr 13, 2026
@kcenon
docs(advanced): document memory pool and allocator architecture (#370)
7e2a24e 
* docs(advanced): document memory pool and allocator architecture

Add comprehensive documentation for internal memory management:
- fixed_block_pool: intrusive free list, chunk growth, thread safety
- pool_allocator: thread-local singleton, size-class routing (small/medium/large)
- Integration with value_container via CONTAINER_USE_MEMORY_POOL
- Performance analysis: allocation throughput, fragmentation, cache locality
- Configuration: CMake options, pool parameters, pre-allocation strategy
- Best practices: when to use pool vs heap, monitoring, sizing recommendations

* docs: fix 7 source-code cross-reference discrepancies in MEMORY_MANAGEMENT.md

- Add `explicit` keyword to fixed_block_pool constructor signature and API table
- Add `~fixed_block_pool()` destructor row to API reference table
- Add try-catch error handling (std::bad_alloc, std::runtime_error) to allocate()
- Add #ifndef NDEBUG debug validation block to deallocate() code snippet
- Fix allocate_chunk_unlocked(): std::make_unique → new (matches source)
- Add pool_stats::hit_rate() method to struct documentation
- Replace CONTAINER_USE_MEMORY_POOL pseudocode with actual implementation
- Use pool_stats::hit_rate() in monitoring example instead of manual calc
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

[Task] docs: Document memory pool and allocator architecture

1 participant

@kcenon