hakmem/docs/TINY_MODULARIZATION_SUMMARY.md

Hakmem Tiny Allocator - Modularization Quick Reference

Analysis Date: 2025-11-01
Full Report: TINY_MODULARIZATION_ANALYSIS.md

Current Status

hakmem_tiny.c: 2245 lines (was 4555 - 51% reduction achieved)
Extracted: 2136 lines into 9 modules
Target: Reduce to ~1000 lines (55% additional reduction possible)

Top 10 Largest Functions (1042 lines = 46% of file)

Function	Lines	%	Category
hak_tiny_init()	450	20%	Initialization
hak_tiny_trim()	116	5%	Lifecycle
tiny_tls_cache_drain()	90	4%	Lifecycle
tiny_slow_alloc_fast()	88	4%	Cold path
allocate_new_slab()	79	3.5%	Slab mgmt
ultra_refill_sll()	56	2.5%	Refill
sll_refill_small_from_ss()	45	2%	Refill
superslab_tls_bump_fast()	45	2%	Hot path
frontend_refill_fc()	44	2%	Refill
tiny_fast_refill_and_take()	39	1.7%	Refill

Priority Roadmap

PRIORITY 1: Hot Path Inline Extraction (417 lines, 19%)

Effort: 2-3 hours | Risk: LOW | When: Immediately

Create:
  core/hakmem_tiny_hot_pop.inc.h (84 lines)
  core/hakmem_tiny_fastcache.inc.h (53 lines)
  core/hakmem_tiny_refill.inc.h (280 lines)

Why first: Largest impact, lowest risk, no performance degradation

PRIORITY 2: Initialization Extraction (450 lines, 20%)

Effort: 3-4 hours | Risk: LOW | When: After Priority 1

Create:
  core/hakmem_tiny_init.inc (450 lines)
  
Optional split:
  core/hakmem_tiny_init_env.inc (74 lines)
  core/hakmem_tiny_init_superslab.inc (100 lines)
  core/hakmem_tiny_init_magazine.inc (150 lines)
  core/hakmem_tiny_init_workers.inc (126 lines)

Why second: Single largest function, cold path only

PRIORITY 3: Lifecycle Management (226 lines, 10%)

Effort: 2 hours | Risk: LOW | When: After Priority 2

Create:
  core/hakmem_tiny_lifecycle.inc (226 lines)
  
Contains:
  - hak_tiny_trim() (116 lines)
  - tiny_tls_cache_drain() (90 lines)
  - tiny_apply_mem_diet() (20 lines)

PRIORITY 4: Slab Management (142 lines, 6%)

Effort: 2-3 hours | Risk: MEDIUM | When: After Priority 3

Option A (Simple):
  core/hakmem_tiny_slab_mgmt.inc (142 lines)

Option B (Better, Recommended):
  core/hakmem_tiny_slab.h
  core/hakmem_tiny_slab.c

Contains: allocate_new_slab, release_slab, move_to_full/free_list

Cumulative Impact

After Phase	Lines Remaining	Reduction	Cumulative
Current	2245	-	0%
Phase 1 (hot path inline)	1828	-417	-19%
Phase 2 (init)	1378	-450	-39%
Phase 3 (lifecycle)	1152	-226	-49%
Phase 4 (slab mgmt)	1010	-142	-55%

Quick Extraction Commands

Phase 1: Hot Path Inline

# Create headers
touch core/hakmem_tiny_hot_pop.inc.h
touch core/hakmem_tiny_fastcache.inc.h
touch core/hakmem_tiny_refill.inc.h

# Extract functions (lines 407-493, 873-900, 584-623, 952-1234)
# Add includes after line 733 (after hotmag.inc.h)
# Test: make clean && make && ./bench_tiny_hot_hakmi

Phase 2: Initialization

# Create module
touch core/hakmem_tiny_init.inc

# Extract hak_tiny_init() (lines 1526-1976)
# Add include at line 1525
# Test: make clean && make && ./bench_random_mixed_hakmi

Phase 3: Lifecycle

# Create module
touch core/hakmem_tiny_lifecycle.inc

# Extract functions (lines 1985-2101, 2135-2225, 2226-2245)
# Add include after init.inc
# Test: HAKMEM_TINY_TRIM_SS=1 ./test_program

Phase 4: Slab Management

# Option A: Simple .inc
touch core/hakmem_tiny_slab_mgmt.inc

# Option B: Proper module (recommended)
touch core/hakmem_tiny_slab.h
touch core/hakmem_tiny_slab.c

# Extract functions (lines 1303-1325, 1327-1406, 1408-1431, 1479-1521)
# Test: Full benchmark suite

Validation After Each Phase

# Must pass all tests
make clean && make
make test

# Performance verification (< 2% variance allowed)
./bench_tiny_hot_hakmi
./bench_random_mixed_hakmi
./scripts/run_bench_suite.sh

# Memory efficiency check
./scripts/run_memory_efficiency.sh

File Organization After All Phases

core/hakmem_tiny.c                   ~1010 lines (55% reduction)

Hot path inline headers:
  hakmem_tiny_hot_pop.inc.h          +84 lines
  hakmem_tiny_fastcache.inc.h        +53 lines
  hakmem_tiny_refill.inc.h           +280 lines
  hakmem_tiny_hotmag.inc.h           147 lines (exists)
  hakmem_tiny_ultra_front.inc.h      52 lines (exists)

Backend includes:
  hakmem_tiny_init.inc               +450 lines
  hakmem_tiny_lifecycle.inc          +226 lines
  hakmem_tiny_slab_mgmt.inc          +142 lines
  hakmem_tiny_alloc.inc              198 lines (exists)
  hakmem_tiny_free.inc               814 lines (exists)
  hakmem_tiny_intel.inc              863 lines (exists)
  hakmem_tiny_background.inc         261 lines (exists)
  hakmem_tiny_slow.inc               36 lines (exists)
  hakmem_tiny_remote.inc             56 lines (exists)

Total modules: 40 files, ~8700 lines well-organized

Success Criteria

• Phase 0: 51% reduction achieved (4555→2245 lines)
• Phase 1: 19% additional reduction (2245→1828 lines)
• Phase 2: 20% additional reduction (1828→1378 lines)
• Phase 3: 10% additional reduction (1378→1152 lines)
• Phase 4: 6% additional reduction (1152→1010 lines)
• Final Goal: 55% total reduction (2245→1010 lines)
• No performance regression (< 2% variance)
• All tests pass
• Compilation time increase < 10%

Next Steps

1. Start with Priority 1 (hot path inline, lowest risk, highest impact)
2. Measure baseline performance before extraction
3. Extract one module at a time, test thoroughly
4. Commit after each successful extraction (git)
5. Document any issues or learnings in TINY_MODULARIZATION_LESSONS.md

Key Decisions

Q: Single .inc or multiple sub-modules for init (450 lines)?
A: Start with single .inc (simpler), split later if needed

Q: .inc file or proper .h/.c module for slab management?
A: Prefer proper module (.h/.c) for better encapsulation

Q: Flat or hierarchical directory structure?
A: Stay flat until 30+ files, then consider core/tiny/ subdirectory

Q: Performance regression tolerance?
A: < 2% variance acceptable, > 5% requires investigation

---

For detailed analysis, see TINY_MODULARIZATION_ANALYSIS.md