hakmem/docs/TINY_MODULARIZATION_ANALYSIS.md

# Hakmem Tiny Allocator Modularization Analysis

## Executive Summary

**Current State:** 2245 lines in hakmem_tiny.c (reduced from 4555 lines - 51% reduction achieved)
**Recent Extractions:** 2136 lines successfully extracted into 4 .inc modules
**Analysis Date:** 2025-11-01
**Recommendation:** Continue phased modularization with focus on initialization, slab management, and hot-path inlining

---

## 1. Current File Organization

### 1.1 Main Module (hakmem_tiny.c)
**Size:** 2245 lines

**Largest Functions:**
1. `hak_tiny_init()` - 450 lines (20% of file!) - INITIALIZATION
2. `hak_tiny_trim()` - 116 lines (5%) - LIFECYCLE
3. `tiny_tls_cache_drain()` - 90 lines (4%) - LIFECYCLE
4. `tiny_slow_alloc_fast()` - 88 lines (4%) - COLD PATH
5. `allocate_new_slab()` - 79 lines (3.5%) - SLAB MANAGEMENT
6. `ultra_refill_sll()` - 56 lines (2.5%) - REFILL
7. `sll_refill_small_from_ss()` - 45 lines (2%) - REFILL
8. `superslab_tls_bump_fast()` - 45 lines (2%) - HOT PATH
9. `frontend_refill_fc()` - 44 lines (2%) - REFILL
10. `tiny_fast_refill_and_take()` - 39 lines (1.7%) - REFILL

**Top 10 Total:** 1042 lines (46% of remaining file!)

### 1.2 Successfully Extracted Modules

| File | Lines | Purpose | Type |
|------|-------|---------|------|
| hakmem_tiny_intel.inc | 863 | Intelligence/telemetry engine | Backend |
| hakmem_tiny_free.inc | 814 | Free path with remote/magazine handling | Hot path |
| hakmem_tiny_background.inc | 261 | Background workers and event queue | Backend |
| hakmem_tiny_alloc.inc | 198 | Wrapper-context allocation | Cold path |
| hakmem_tiny_tls_ops.h | 251 | TLS list operations (inline) | Hot path |
| hakmem_tiny_hotmag.inc.h | 147 | Hot magazine operations | Hot path |
| hakmem_tiny_ultra_front.inc.h | 52 | Ultra-fast frontend tier | Hot path |
| hakmem_tiny_slow.inc | 36 | Slow path stubs | Cold path |
| hakmem_tiny_remote.inc | 56 | Remote free queue handling | Backend |

### 1.3 Supporting Infrastructure Modules

| File | Lines | Purpose | Type |
|------|-------|---------|------|
| hakmem_tiny_superslab.{h,c} | 215+484 | SuperSlab allocator | Core backend |
| hakmem_tiny_magazine.{h,c} | 45+144 | Magazine data structures | Core |
| hakmem_tiny_stats.{h,c} | 277+251 | Statistics batching | Observability |
| hakmem_tiny_tls_list.h | 131 | TLS free list helpers | Core |
| hakmem_tiny_batch_refill.h | 232 | Batch refill logic | Hot path |
| hakmem_tiny_mini_mag.h | 148 | Mini-magazine helpers | Hot path |

### 1.4 API/Query Modules (Small)

| File | Lines | Purpose |
|------|-------|---------|
| hakmem_tiny_stats_api.h | 23 | Stats query API |
| hakmem_tiny_query_api.h | 18 | General query API |
| hakmem_tiny_rss_api.h | 9 | RSS utilities |
| hakmem_tiny_registry_api.h | 32 | Registry API |
| hakmem_tiny_{rss,query,registry}.c | 28+72+63 | API implementations |

---

## 2. Detailed Function Analysis

### 2.1 Initialization Section (470+ lines, 21%)

**Primary Function:** `hak_tiny_init()` (450 lines)

**Breakdown:**
- Lines 1526-1600: Environment variable parsing (74 lines)
  - Registry, wrapper mode, remote drain, mem diet, magazine caps
- Lines 1600-1700: SuperSlab initialization (100 lines)
  - Capacity setup, queue initialization, background workers
- Lines 1700-1850: Magazine initialization (150 lines)
  - Per-class magazine setup, TLS initialization
- Lines 1850-1976: Backend worker spawning (126 lines)
  - Intelligence engine, background refill workers

**Extraction Opportunity:**
- `hakmem_tiny_init_env.inc` - 74 lines (env parsing)
- `hakmem_tiny_init_superslab.inc` - 100 lines (SS setup)
- `hakmem_tiny_init_magazine.inc` - 150 lines (mag setup)
- `hakmem_tiny_init_workers.inc` - 126 lines (workers)
- **Total extraction potential: 450 lines → 4 modules**

### 2.2 Lifecycle Management (206 lines, 9%)

**Functions:**
- `hak_tiny_trim()` - 116 lines (1985-2101)
- `tiny_tls_cache_drain()` - 90 lines (2135-2225)

**Purpose:** Memory reclamation, cleanup, trim operations

**Extraction Opportunity:**
- `hakmem_tiny_lifecycle.inc` - 206 lines
- Could include `tiny_apply_mem_diet()` (20 lines) as well
- **Total: 226 lines**

### 2.3 Slab Management (120 lines, 5.3%)

**Functions:**
- `allocate_new_slab()` - 79 lines (1327-1406)
- `release_slab()` - 23 lines (1408-1431)
- `move_to_full_list()` - 20 lines (1479-1499)
- `move_to_free_list()` - 20 lines (1501-1521)

**Extraction Opportunity:**
- `hakmem_tiny_slab_mgmt.inc` - 142 lines
- Or move to `hakmem_tiny_slab.{h,c}` as a proper module (better)

### 2.4 Registry Operations (22 lines, 1%)

**Function:**
- `registry_lookup()` - 22 lines (1303-1325)

**Note:** Already has hakmem_tiny_registry.c/h infrastructure
**Action:** Move this function to hakmem_tiny_registry.c

### 2.5 Hot Path Inline Functions (200+ lines, 9%)

**Per-Class Hot Pop Functions (84 lines):**
- `tiny_hot_pop_class0/1/2/3()` - 21 lines each × 4 = 84 lines

**Extraction Opportunity:**
- These are `always_inline` hot-path functions
- Should extract to `hakmem_tiny_hot_pop.inc.h` (inline header)
- Similar to existing `hakmem_tiny_hotmag.inc.h` pattern

**Fast Path Helpers (100+ lines):**
- `tiny_fast_pop()` - 17 lines (377-394)
- `tiny_fast_push()` - 13 lines (394-407)
- `fastcache_pop()` - 8 lines (873-881)
- `fastcache_push()` - 7 lines (881-888)
- `quick_pop()` - 8 lines (892-900)

**Extraction Opportunity:**
- `hakmem_tiny_fastcache.inc.h` - inline hot-path helpers

### 2.6 Refill Operations (184 lines, 8.2%)

**Functions:**
- `ultra_refill_sll()` - 56 lines (1178-1234)
- `sll_refill_small_from_ss()` - 45 lines (952-997)
- `superslab_tls_bump_fast()` - 45 lines (1016-1061)
- `frontend_refill_fc()` - 44 lines (1063-1107)
- `tiny_fast_refill_and_take()` - 39 lines (584-623)
- `quick_refill_from_sll()` - 18 lines (918-936)
- `quick_refill_from_mag()` - 11 lines (938-949)
- `bulk_mag_to_sll_if_room()` - 22 lines (1133-1155)

**Extraction Opportunity:**
- `hakmem_tiny_refill.inc.h` - 280+ lines
- These are mostly inline functions used in hot paths
- Should be header-based for inlining

### 2.7 TLS Operations and Helpers (100+ lines, 4.5%)

**Functions:**
- `tiny_tls_refresh_params()` - 24 lines (352-376)
- `tiny_tls_bind_slab()` - 7 lines (318-325)
- `tiny_tls_default_refill()` - 7 lines (325-332)
- `tiny_tls_default_spill()` - 8 lines (332-340)
- `tiny_tls_publish_targets()` - 7 lines (340-347)
- `tiny_tls_request_trim()` - 5 lines (347-352)

**Note:** Some of this overlaps with hakmem_tiny_tls_ops.h
**Action:** Consolidate into existing TLS ops module

### 2.8 Miscellaneous Helpers (50+ lines)

**Functions:**
- `tiny_slow_alloc_fast()` - 88 lines (495-583) - COLD PATH
- `tiny_optional_push()` - 27 lines (777-804)
- `hak_tiny_alloc_superslab_try_fast()` - 16 lines (900-916)
- `hak_thread_id16()` - 4 lines (837-841)
- `eventq_push_ex()` - 26 lines (843-869)
- Various small inline helpers

---

## 3. Proposed Modularization Plan

### Phase 1: Initialization Extraction (HIGH PRIORITY)
**Goal:** Extract 450-line `hak_tiny_init()` function

**Strategy A: Multi-file split (Recommended)**
```
core/tiny/init/
  hakmem_tiny_init.c           - Main init orchestrator (50 lines)
  hakmem_tiny_init_env.inc     - Environment parsing (74 lines)
  hakmem_tiny_init_superslab.inc - SuperSlab setup (100 lines)
  hakmem_tiny_init_magazine.inc - Magazine setup (150 lines)
  hakmem_tiny_init_workers.inc  - Worker spawning (126 lines)
```

**Strategy B: Single large module (Simpler)**
```
core/hakmem_tiny_init.inc     - All initialization (450 lines)
```

**Benefit:** Reduces main file by 20%
**Risk:** Low - initialization is cold path, one-time execution
**Priority:** HIGH - largest function

### Phase 2: Lifecycle Management (MEDIUM PRIORITY)
**Goal:** Extract trim and cleanup operations

```
core/hakmem_tiny_lifecycle.inc
  - hak_tiny_trim() (116 lines)
  - tiny_tls_cache_drain() (90 lines)
  - tiny_apply_mem_diet() (20 lines)
  Total: 226 lines (10% reduction)
```

**Benefit:** Cleaner separation of concerns
**Risk:** Low - cold path, called rarely
**Priority:** MEDIUM

### Phase 3: Slab Management Module (MEDIUM PRIORITY)
**Goal:** Consolidate slab lifecycle into proper module

**Option A: Keep as .inc**
```
core/hakmem_tiny_slab_mgmt.inc
  - allocate_new_slab() (79 lines)
  - release_slab() (23 lines)
  - move_to_full_list() (20 lines)
  - move_to_free_list() (20 lines)
  Total: 142 lines (6% reduction)
```

**Option B: Promote to proper module (Recommended)**
```
core/hakmem_tiny_slab.h        - Slab API and inline helpers
core/hakmem_tiny_slab.c        - Slab management implementation
```

**Benefit:** Better encapsulation, testability
**Risk:** Low-medium - called from multiple paths, need careful header management
**Priority:** MEDIUM

### Phase 4: Hot Path Inline Extraction (HIGH PRIORITY)
**Goal:** Extract inline hot-path functions to headers for readability

**4A: Hot Pop Functions**
```
core/hakmem_tiny_hot_pop.inc.h
  - tiny_hot_pop_class0/1/2/3() (84 lines)
```

**4B: Fast Cache Operations**
```
core/hakmem_tiny_fastcache.inc.h
  - fastcache_pop/push() (15 lines)
  - quick_pop() (8 lines)
  - tiny_fast_pop/push() (30 lines)
  Total: 53 lines
```

**4C: Refill Operations**
```
core/hakmem_tiny_refill.inc.h
  - ultra_refill_sll() (56 lines)
  - sll_refill_small_from_ss() (45 lines)
  - superslab_tls_bump_fast() (45 lines)
  - frontend_refill_fc() (44 lines)
  - Other refill helpers (90 lines)
  Total: 280 lines (12% reduction)
```

**Benefit:** Maintains performance (inlining), improves readability
**Risk:** LOW - these are already inline functions
**Priority:** HIGH - significant line count reduction (417 lines total)

### Phase 5: Registry Consolidation (LOW PRIORITY)
**Goal:** Move registry_lookup() to existing registry module

```
Move: registry_lookup() (22 lines) → hakmem_tiny_registry.c
```

**Benefit:** Logical grouping, minimal benefit
**Risk:** Very low
**Priority:** LOW - only 22 lines

---

## 4. Proposed Folder Structure

### Option A: Flat with Subdirectories (Recommended)
```
core/
  hakmem_tiny.c                    # Main orchestrator (900 lines after phase 1-4)
  hakmem_tiny.h                    # Main header
  
  # Hot path inline headers (included in tiny.c)
  hakmem_tiny_hotmag.inc.h         # ✓ Exists (147 lines)
  hakmem_tiny_ultra_front.inc.h    # ✓ Exists (52 lines)
  hakmem_tiny_hot_pop.inc.h        # NEW (84 lines) - Phase 4A
  hakmem_tiny_fastcache.inc.h      # NEW (53 lines) - Phase 4B
  hakmem_tiny_refill.inc.h         # NEW (280 lines) - Phase 4C
  
  # Backend implementation includes
  hakmem_tiny_alloc.inc            # ✓ Exists (198 lines)
  hakmem_tiny_free.inc             # ✓ Exists (814 lines)
  hakmem_tiny_intel.inc            # ✓ Exists (863 lines)
  hakmem_tiny_background.inc       # ✓ Exists (261 lines)
  hakmem_tiny_slow.inc             # ✓ Exists (36 lines)
  hakmem_tiny_remote.inc           # ✓ Exists (56 lines)
  hakmem_tiny_init.inc             # NEW (450 lines) - Phase 1
  hakmem_tiny_lifecycle.inc        # NEW (226 lines) - Phase 2
  hakmem_tiny_slab_mgmt.inc        # NEW (142 lines) - Phase 3
  
  # Supporting modules (proper .h/.c pairs)
  hakmem_tiny_superslab.{h,c}      # ✓ Exists
  hakmem_tiny_magazine.{h,c}       # ✓ Exists
  hakmem_tiny_stats.{h,c}          # ✓ Exists
  hakmem_tiny_tls_list.h           # ✓ Exists
  hakmem_tiny_slab.{h,c}           # NEW - Phase 3 Option B
  ...
```

### Option B: Hierarchical Subdirectories (Future)
```
core/tiny/
  tiny.c                           # Main file
  tiny.h                           # Main header
  
  frontend/                        # Hot path allocation
    hot_pop.inc.h
    fastcache.inc.h
    ultra_front.inc.h
    hotmag.inc.h
    refill.inc.h
    
  backend/                         # Slow path/management
    alloc.inc
    free.inc
    slab_mgmt.inc
    lifecycle.inc
    init.inc
    background.inc
    intel.inc
    remote.inc
    
  core/                            # Core infrastructure
    superslab.{h,c}
    magazine.{h,c}
    slab.{h,c}
    tls_list.h
    stats.{h,c}
    
  api/                             # Public APIs
    stats_api.h
    query_api.h
    registry_api.h
    rss_api.h
```

**Recommendation:** Start with Option A (flat), migrate to Option B when module count exceeds 30 files.

---

## 5. Module Boundary Analysis

### 5.1 Natural Module Boundaries

**Frontend (Hot Path - Inline Headers):**
- Ultra-fast tier: Bump allocator, hot magazines
- Fast tier: FastCache, Quick slots
- Per-class specialization: Hot pop functions
- Refill operations: SLL refill, mag refill, SS bump

**Backend (Cold Path - .inc Files):**
- Initialization: Environment, setup, workers
- Lifecycle: Trim, drain, cleanup
- Slab management: Allocation, release, list operations
- Intelligence: Telemetry, events, background workers
- Remote operations: Cross-thread free handling

**Core Infrastructure (Proper Modules):**
- SuperSlab: Large-scale memory management
- Magazine: Per-class caching
- TLS Lists: Thread-local free lists
- Statistics: Performance metrics

**APIs (Small Modules):**
- Query interface
- Stats interface
- Registry interface

### 5.2 Dependency Graph

```
hakmem_tiny.c
  ├─ [includes frontend inline headers]
  │  ├─ hakmem_tiny_hot_pop.inc.h       (NEW)
  │  ├─ hakmem_tiny_fastcache.inc.h     (NEW)
  │  ├─ hakmem_tiny_refill.inc.h        (NEW)
  │  ├─ hakmem_tiny_hotmag.inc.h        (existing)
  │  └─ hakmem_tiny_ultra_front.inc.h   (existing)
  │
  ├─ [includes backend .inc files]
  │  ├─ hakmem_tiny_init.inc            (NEW)
  │  ├─ hakmem_tiny_lifecycle.inc       (NEW)
  │  ├─ hakmem_tiny_slab_mgmt.inc       (NEW)
  │  ├─ hakmem_tiny_alloc.inc           (existing)
  │  ├─ hakmem_tiny_free.inc            (existing)
  │  ├─ hakmem_tiny_intel.inc           (existing)
  │  ├─ hakmem_tiny_background.inc      (existing)
  │  ├─ hakmem_tiny_slow.inc            (existing)
  │  └─ hakmem_tiny_remote.inc          (existing)
  │
  └─ [depends on core modules]
     ├─ hakmem_tiny_superslab.h/c
     ├─ hakmem_tiny_magazine.h/c
     ├─ hakmem_tiny_slab.h/c            (NEW)
     ├─ hakmem_tiny_stats.h/c
     └─ hakmem_tiny_tls_list.h
```

---

## 6. Line Count Projections

### Current State
```
hakmem_tiny.c: 2245 lines
```

### After Phase 1 (Init Extraction)
```
hakmem_tiny.c: 1795 lines (-450, -20%)
hakmem_tiny_init.inc: +450 lines
```

### After Phase 2 (Lifecycle)
```
hakmem_tiny.c: 1569 lines (-226, -10% additional)
hakmem_tiny_lifecycle.inc: +226 lines
```

### After Phase 3 (Slab Management)
```
hakmem_tiny.c: 1427 lines (-142, -6% additional)
hakmem_tiny_slab_mgmt.inc: +142 lines
```

### After Phase 4 (Hot Path Inline)
```
hakmem_tiny.c: 1010 lines (-417, -18% additional)
hakmem_tiny_hot_pop.inc.h: +84 lines
hakmem_tiny_fastcache.inc.h: +53 lines
hakmem_tiny_refill.inc.h: +280 lines
```

### Final Result After All Phases
```
hakmem_tiny.c: ~1010 lines (55% reduction from 2245)
```

**Remaining in main file:**
- Core allocation/free orchestration logic
- Global state declarations
- Wrapper integration
- Forward declarations
- Helper macros

---

## 7. Benefits and Risks

### Benefits

**Maintainability:**
- Easier to locate and modify specific functionality
- Reduced cognitive load (1000-line files vs 2200-line files)
- Clear separation of hot path vs cold path

**Performance:**
- No degradation expected - inline functions stay inline
- Cold path extractions have zero performance impact
- Compiler still sees all code after #include

**Testability:**
- Modules can be tested in isolation (with proper mocking)
- Easier to benchmark specific subsystems

**Documentation:**
- Each module can have focused documentation
- Clearer API boundaries

### Risks

**Compilation:**
- Increased include complexity
- Potential circular dependency issues (mitigated by careful ordering)
- Build time may increase slightly (more files to parse)

**Debugging:**
- Stack traces may show file:line from .inc files
- Need to ensure debug info includes correct file paths
- (Risk is minimal - modern debuggers handle this well)

**Refactoring Overhead:**
- Need to move forward declarations carefully
- May expose hidden dependencies
- Requires thorough testing after extraction

**Cognitive Overhead:**
- Developers need to know which file contains what
- Could make code harder to follow if module boundaries are unclear
- (Mitigated by clear naming conventions and documentation)

---

## 8. Priority Ranking for Next Phases

### PRIORITY 1: Hot Path Inline Extraction (Phase 4)
**Why:** High impact (417 lines), low risk, maintains performance
**When:** Immediately
**Effort:** 2-3 hours
**Files:**
- hakmem_tiny_hot_pop.inc.h (84 lines)
- hakmem_tiny_fastcache.inc.h (53 lines)
- hakmem_tiny_refill.inc.h (280 lines)

### PRIORITY 2: Initialization Extraction (Phase 1)
**Why:** Largest function (450 lines), cold path, clear boundary
**When:** After Phase 4
**Effort:** 3-4 hours
**Files:**
- hakmem_tiny_init.inc (450 lines)
- OR split into 4 sub-modules (init_env, init_superslab, init_magazine, init_workers)

### PRIORITY 3: Lifecycle Management (Phase 2)
**Why:** Good size reduction (226 lines), clean separation
**When:** After Phase 1
**Effort:** 2 hours
**Files:**
- hakmem_tiny_lifecycle.inc (226 lines)

### PRIORITY 4: Slab Management (Phase 3)
**Why:** Logical grouping, moderate size (142 lines)
**When:** After Phase 2
**Effort:** 2-3 hours
**Files:**
- hakmem_tiny_slab_mgmt.inc OR hakmem_tiny_slab.{h,c}

### PRIORITY 5: Registry Consolidation (Phase 5)
**Why:** Small cleanup, logical grouping
**When:** Any time
**Effort:** 15 minutes
**Files:**
- Move registry_lookup() to hakmem_tiny_registry.c

---

## 9. Recommended Action Plan

### Week 1: Hot Path Inline Extraction
```bash
# Create new inline header files
touch core/hakmem_tiny_hot_pop.inc.h
touch core/hakmem_tiny_fastcache.inc.h
touch core/hakmem_tiny_refill.inc.h

# Extract functions (use sed/awk scripts)
# Add #include statements to hakmem_tiny.c
# Compile and test
# Verify performance (run benchmarks)
```

### Week 2: Initialization Extraction
```bash
# Create init module
touch core/hakmem_tiny_init.inc

# Extract hak_tiny_init() function
# Add #include at appropriate location
# Test initialization path thoroughly
```

### Week 3: Lifecycle and Slab Management
```bash
# Create lifecycle module
touch core/hakmem_tiny_lifecycle.inc

# Create slab management module
touch core/hakmem_tiny_slab_mgmt.inc

# Extract functions
# Compile and test
```

### Week 4: Testing and Documentation
```bash
# Run full benchmark suite
# Update documentation
# Create module dependency diagram
# Write migration guide
```

---

## 10. Success Metrics

### Quantitative
- [ ] hakmem_tiny.c reduced below 1200 lines (46% reduction)
- [ ] No performance regression in hot benchmarks (< 2% variance)
- [ ] All tests pass
- [ ] Compilation time increase < 10%

### Qualitative
- [ ] Code is easier to navigate and understand
- [ ] Module boundaries are clear and logical
- [ ] Documentation accurately reflects new structure
- [ ] Team members can easily locate functionality

---

## Appendix A: Full File Inventory

```
Current tiny-related files (31 files):

Headers (inline/interface):
  hakmem_tiny.h (327 lines)
  hakmem_tiny_superslab.h (215 lines)
  hakmem_tiny_magazine.h (45 lines)
  hakmem_tiny_batch_refill.h (232 lines)
  hakmem_tiny_stats.h (277 lines)
  hakmem_tiny_stats_api.h (23 lines)
  hakmem_tiny_query_api.h (18 lines)
  hakmem_tiny_rss_api.h (9 lines)
  hakmem_tiny_registry_api.h (32 lines)
  hakmem_tiny_tls_list.h (131 lines)
  hakmem_tiny_remote_target.h (25 lines)
  hakmem_tiny_bg_spill.h (52 lines)
  hakmem_tiny_mini_mag.h (148 lines)
  hakmem_tiny_tls_ops.h (251 lines)

Inline implementation headers (.inc.h):
  hakmem_tiny_hotmag.inc.h (147 lines)
  hakmem_tiny_ultra_front.inc.h (52 lines)
  hakmem_tiny_bg_bin.inc.h (37 lines)

Include-only backend modules (.inc):
  hakmem_tiny_intel.inc (863 lines)
  hakmem_tiny_free.inc (814 lines)
  hakmem_tiny_background.inc (261 lines)
  hakmem_tiny_alloc.inc (198 lines)
  hakmem_tiny_remote.inc (56 lines)
  hakmem_tiny_slow.inc (36 lines)

Implementation files (.c):
  hakmem_tiny.c (2245 lines) ← MAIN FILE
  hakmem_tiny_superslab.c (484 lines)
  hakmem_tiny_magazine.c (144 lines)
  hakmem_tiny_stats.c (251 lines)
  hakmem_tiny_rss.c (28 lines)
  hakmem_tiny_query.c (72 lines)
  hakmem_tiny_registry.c (63 lines)
  hakmem_tiny_remote_target.c (40 lines)
  hakmem_tiny_bg_spill.c (83 lines)

TOTAL: ~8,700 lines across 31 files
MAIN: 2,245 lines (26% of total)
```

---

## Appendix B: Extraction Script Templates

### B.1 Extract Function to .inc File

```bash
#!/bin/bash
# extract_function.sh <source_file> <function_name> <target_inc>

SOURCE="$1"
FUNCTION="$2"
TARGET="$3"

# Find function start and end lines
START=$(grep -n "^${FUNCTION}(" "$SOURCE" | cut -d: -f1)
# Find matching closing brace (simple version - may need improvement)
END=$(awk "NR>=$START && /^}$/ {print NR; exit}" "$SOURCE")

# Extract function
sed -n "${START},${END}p" "$SOURCE" > "$TARGET"

# Remove from source (leave comment)
sed -i "${START},${END}c\\
// EXTRACTED TO $TARGET\\
// See $TARGET for implementation
" "$SOURCE"

echo "Extracted $FUNCTION ($((END-START+1)) lines) to $TARGET"
```

### B.2 Create Inline Header Template

```bash
#!/bin/bash
# create_inline_header.sh <module_name>

MODULE="$1"
HEADER="hakmem_tiny_${MODULE}.inc.h"

cat > "core/$HEADER" << 'EOF'
#ifndef HAKMEM_TINY_${MODULE^^}_INC_H
#define HAKMEM_TINY_${MODULE^^}_INC_H

// Module: ${MODULE}
// Purpose: [Description]
// Type: Inline hot-path functions
// Phase: [Phase number]

// Forward declarations (if needed)

// Inline function implementations

#endif // HAKMEM_TINY_${MODULE^^}_INC_H
EOF

echo "Created core/$HEADER"
```

---

## Appendix C: Performance Validation Checklist

After each extraction phase, run:

```bash
# 1. Compilation check
make clean && make

# 2. Unit tests
make test

# 3. Hot-path benchmarks
./bench_tiny_hot_hakmi
./bench_tiny_hot_mi
./bench_random_mixed_hakmi
./bench_random_mixed_mi

# 4. Memory efficiency
./scripts/run_memory_efficiency.sh

# 5. Full benchmark suite
./scripts/run_bench_suite.sh

# 6. Verify no regressions
# Compare results with baseline (before extraction)
```

---

END OF REPORT