john/McRogueFace
1
0
Fork 0
Code Issues 32 Pull requests Projects Releases Wiki Activity

Memory Pool for Entities #117

New issue
Open
opened 2025-07-12 19:04:58 +00:00 by john · 2 comments
john commented 2025-07-12 19:04:58 +00:00
Owner
Copy link

Implement memory pooling for entity allocation/deallocation.
Definition of Done:

  • Pre-allocated pool for common entity counts
  • Reduced allocation overhead
  • No memory fragmentation
  • Configurable pool sizes
Implement memory pooling for entity allocation/deallocation. Definition of Done: - Pre-allocated pool for common entity counts - Reduced allocation overhead - No memory fragmentation - Configurable pool sizes
john commented 2025-12-28 04:25:05 +00:00
Author
Owner
Copy link

Benchmark Results (commit fcc0376)

Added tests/benchmarks/entity_scale_benchmark.py to establish baseline metrics.

Current Performance (2,000 entities on 100×100 grid)

Operation Time Rate
Entity Creation 26.4ms 75,738/sec
Direct Iteration 0.23ms 8.5M reads/sec
EntityCollection Iteration 13.6ms 147k reads/sec

Key Finding: EntityCollection Overhead

Direct C++ iteration (via list(grid.entities) then loop): 0.23ms
EntityCollection iteration (via for e in grid.entities): 13.6ms

The 60× slowdown comes from Python wrapper object creation on each access. Each call to __next__ in the iterator:

  1. Advances the C++ iterator
  2. Allocates a new PyUIEntityObject
  3. Copies the shared_ptr
  4. Returns to Python

Projected Gains with Memory Pool

Scenario Current With Pool Speedup
Creation (10k entities) ~130ms ~20ms 6×
Iteration (direct) 2.3ms ~0.5ms 5×

Mechanism: Pre-allocate entity memory in contiguous blocks. Reduces malloc overhead and improves CPU cache utilization.

Additional Finding

The EntityCollection overhead suggests a secondary optimization: batch access APIs that return data without per-entity Python object creation. For example:

  • grid.entity_positions() → numpy array of (x, y) pairs
  • grid.entities_in_rect(x, y, w, h) → filtered list

This would complement the memory pool by reducing Python/C++ boundary crossings.

## Benchmark Results (commit fcc0376) Added `tests/benchmarks/entity_scale_benchmark.py` to establish baseline metrics. ### Current Performance (2,000 entities on 100×100 grid) | Operation | Time | Rate | |-----------|------|------| | Entity Creation | 26.4ms | 75,738/sec | | Direct Iteration | 0.23ms | 8.5M reads/sec | | EntityCollection Iteration | 13.6ms | 147k reads/sec | ### Key Finding: EntityCollection Overhead **Direct C++ iteration** (via `list(grid.entities)` then loop): 0.23ms **EntityCollection iteration** (via `for e in grid.entities`): 13.6ms The **60× slowdown** comes from Python wrapper object creation on each access. Each call to `__next__` in the iterator: 1. Advances the C++ iterator 2. Allocates a new `PyUIEntityObject` 3. Copies the `shared_ptr` 4. Returns to Python ### Projected Gains with Memory Pool | Scenario | Current | With Pool | Speedup | |----------|---------|-----------|---------| | Creation (10k entities) | ~130ms | ~20ms | **6×** | | Iteration (direct) | 2.3ms | ~0.5ms | **5×** | **Mechanism**: Pre-allocate entity memory in contiguous blocks. Reduces malloc overhead and improves CPU cache utilization. ### Additional Finding The EntityCollection overhead suggests a secondary optimization: **batch access APIs** that return data without per-entity Python object creation. For example: - `grid.entity_positions()` → numpy array of (x, y) pairs - `grid.entities_in_rect(x, y, w, h)` → filtered list This would complement the memory pool by reducing Python/C++ boundary crossings.
john commented 2025-12-28 05:45:50 +00:00
Author
Owner
Copy link

Current Performance Assessment

After implementing #159 (iterator fix) and #115 (SpatialHash), the benchmark shows:

Metric Current Performance
Entity Creation 80,000 entities/sec (25ms for 2000)
Iteration 9.6M reads/sec
Range Query 0.003ms (via SpatialHash)
N×N Visibility 1ms for 2000 entities

Analysis

The entity creation rate of 80k/sec is likely sufficient for roguelike games where:

  • Level generation creates hundreds, not thousands, of entities
  • Runtime spawning is infrequent (enemies spawn one at a time)
  • The 25ms for 2000 entities is a one-time level load cost

Bottleneck Investigation

The entity creation overhead comes from:

  1. std::make_shared<UIEntity>() - heap allocation
  2. Python wrapper allocation via tp_alloc
  3. PythonObjectCache registration
  4. UISprite construction

A C++ memory pool would help with #1 but not #2-4 which dominate.

Recommendation

Given the significant gains from #115 (104× speedup on N×N) and the acceptable creation rate, I recommend:

  1. Deferring full pool implementation unless specific bottleneck is identified
  2. Considering bulk API (grid.create_entities(positions)) for level generation if needed
  3. Re-evaluate after real-world profiling in actual game scenarios
## Current Performance Assessment After implementing #159 (iterator fix) and #115 (SpatialHash), the benchmark shows: | Metric | Current Performance | |--------|---------------------| | Entity Creation | 80,000 entities/sec (25ms for 2000) | | Iteration | 9.6M reads/sec | | Range Query | 0.003ms (via SpatialHash) | | N×N Visibility | 1ms for 2000 entities | ### Analysis The entity creation rate of 80k/sec is likely sufficient for roguelike games where: - Level generation creates hundreds, not thousands, of entities - Runtime spawning is infrequent (enemies spawn one at a time) - The 25ms for 2000 entities is a one-time level load cost ### Bottleneck Investigation The entity creation overhead comes from: 1. `std::make_shared<UIEntity>()` - heap allocation 2. Python wrapper allocation via `tp_alloc` 3. PythonObjectCache registration 4. UISprite construction A C++ memory pool would help with #1 but not #2-4 which dominate. ### Recommendation Given the significant gains from #115 (104× speedup on N×N) and the acceptable creation rate, I recommend: 1. **Deferring full pool implementation** unless specific bottleneck is identified 2. **Considering bulk API** (`grid.create_entities(positions)`) for level generation if needed 3. **Re-evaluate after real-world profiling** in actual game scenarios
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
master
threedee
emscripten-mcrogueface
rogueliketutorial25
alpha_presentable
alpha_streamline_2
alpha_streamline_1
interpreter_mode
grid_entity_integration
reprs_and_member_names
break_up_ui_h
standardize_font_handling
standardize_vector_handling
standardize_color_handling
standardize_texture_handling
raii_pyobjects
rebase-for-7DRL_Feb-2024
engjam_uicollection
engjam_ui_overhaul
0.2.3-prerelease-7drl2026-emscripten
Labels
Clear labels   
Alpha Release Requirement

This issue is a blocker to 0.1 Alpha release of McRogueFace.

  
Bugfix

   
Demo Target

Functionality to demonstrate; Depends on new features, but this issue isn't for writing them.

  
Documentation

   
Major Feature

Significant time and effort required.

  
Minor Feature

Some effort required to create or overhaul functionality.

  
priority:tier1-active

Current development focus - critical path to v1.0

  
priority:tier2-foundation

Important foundation work - not blocking v1.0

  
priority:tier3-future

Future features - deferred until after v1.0

  
priority:tier4-deferred

   
Refactoring & Cleanup

no new functionality, just improving the codebase.

  
system:animation

Animation and property interpolation

  
system:documentation

Documentation infrastructure

  
system:grid

Grid system and spatial containers

  
system:input

Input handling and events

  
system:performance

Performance optimization and profiling

  
system:procgen

Procedural Generation (Noise, BSP, Heightmap)

  
system:python-binding

Python/C++ binding layer

  
system:rendering

Rendering pipeline and visuals

  
system:ui-hierarchy

UI component hierarchy and composition

  
Tiny Feature

quick and easy - a few lines or with little interconnection around the codebase

  
workflow:blocked

Blocked by other work - waiting on dependencies

  
workflow:needs-benchmark

Needs performance testing and benchmarks

  
workflow:needs-documentation

Needs documentation before or after implementation

No labels
Alpha Release Requirement
Bugfix
Demo Target
Documentation
Major Feature
Minor Feature
priority:tier1-active
priority:tier2-foundation
priority:tier3-future
priority:tier4-deferred
Refactoring & Cleanup
system:animation
system:documentation
system:grid
system:input
system:performance
system:procgen
system:python-binding
system:rendering
system:ui-hierarchy
Tiny Feature
workflow:blocked
workflow:needs-benchmark
workflow:needs-documentation
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
john/McRogueFace#117
No description provided.