hakmem/docs/TINY_MODULARIZATION_SUMMARY.md

# Hakmem Tiny Allocator - Modularization Quick Reference

**Analysis Date:** 2025-11-01  
**Full Report:** [TINY_MODULARIZATION_ANALYSIS.md](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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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

```bash
# 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

- [x] 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](TINY_MODULARIZATION_ANALYSIS.md)