hakmem/PHASE4_STEP2_COMPLETE.md

# Phase 4-Step2: Hot/Cold Path Box - COMPLETE ✓

**Date**: 2025-11-29
**Status**: ✅ Complete
**Performance Gain**: +7.3% (53.3 → 57.2 M ops/s, without PGO)

---

## Summary

Phase 4-Step2 implemented Hot/Cold Path separation using the Box pattern for Tiny Front allocation path. The implementation achieved a **+7.3% performance improvement** by reducing branch count in the hot path from 4-5 branches to 1 branch, while keeping the cold path isolated with `noinline` and `cold` attributes for better i-cache locality.

---

## Implementation

### Box 2: Tiny Front Hot Path Box

**File**: `core/box/tiny_front_hot_box.h`
**Purpose**: Ultra-fast cache hit path (1 branch only)
**Contract**: Returns USER pointer on cache hit, NULL on miss

**Key Optimizations**:
1. **Range Check Removed**: Caller (hak_tiny_size_to_class) guarantees valid class_idx
2. **Branch Hints**: `TINY_HOT_LIKELY(ptr != NULL)` guides CPU pipeline
3. **Zero-Overhead Metrics**: `TINY_HOT_METRICS_HIT/MISS` macros expand to nothing in Release
4. **Always Inline**: Eliminates function call overhead

**Assembly (expected, x86-64)**:
```asm
; Hot path (cache hit):
mov    g_unified_cache@TPOFF(%rax,%rdi,8), %rcx   ; TLS cache access
movzwl (%rcx), %edx                                ; head
movzwl 2(%rcx), %esi                               ; tail
cmp    %dx, %si                                    ; head != tail ? (1 branch)
je     .Lcache_miss
mov    8(%rcx), %rax                               ; slots
mov    (%rax,%rdx,8), %rax                         ; base = slots[head]
inc    %dx                                         ; head++
and    6(%rcx), %dx                                ; head & mask
mov    %dx, (%rcx)                                 ; store head
movb   $0xA0, (%rax)                               ; header magic
or     %dil, (%rax)                                ; header |= class_idx
lea    1(%rax), %rax                               ; base+1 → USER
ret
.Lcache_miss:
; Fall through to cold path
```

**Branch Count**: 1 branch (cache empty check)

---

### Box 3: Tiny Front Cold Path Box

**File**: `core/box/tiny_front_cold_box.h`
**Purpose**: Slow path (refill, drain, errors)
**Contract**: Returns USER pointer on success, NULL on failure

**Key Optimizations**:
1. **noinline Attribute**: Keeps hot path small (better i-cache)
2. **cold Attribute**: Hints compiler this is infrequent code
3. **Batch Operations**: Refill/drain multiple objects (amortize cost)
4. **Defensive Code**: Full error checking (correctness > speed)

**Functions**:
- `tiny_cold_refill_and_alloc()`: Refill cache from SuperSlab + allocate one object
- `tiny_cold_drain_and_free()`: Drain cache to SuperSlab + free one object (TODO: implement)
- `tiny_cold_report_error()`: Error reporting (debug builds only)

**Call Frequency**: ~1-5% of allocations (depends on cache size)

---

### Integration: malloc_tiny_fast()

**File**: `core/front/malloc_tiny_fast.h`
**Changes**:

```c
// Before (Phase 26-A):
static inline void* malloc_tiny_fast(size_t size) {
    int class_idx = hak_tiny_size_to_class(size);
    if (__builtin_expect(class_idx < 0 || class_idx >= TINY_NUM_CLASSES, 0)) {
        return NULL;  // Range check (1 branch)
    }
    void* base = unified_cache_pop_or_refill(class_idx);  // Mixed hot/cold (3-4 branches)
    if (__builtin_expect(base == NULL, 0)) {
        return NULL;  // Refill failure check (1 branch)
    }
    #ifdef HAKMEM_TINY_HEADER_CLASSIDX
    tiny_region_id_write_header(base, class_idx);
    return (void*)((char*)base + 1);
    #else
    return base;
    #endif
}

// After (Phase 4-Step2):
static inline void* malloc_tiny_fast(size_t size) {
    int class_idx = hak_tiny_size_to_class(size);

    // Hot path: 1 branch
    void* ptr = tiny_hot_alloc_fast(class_idx);
    if (TINY_HOT_LIKELY(ptr != NULL)) {
        return ptr;  // Cache hit → return USER pointer
    }

    // Cold path: noinline, cold
    return tiny_cold_refill_and_alloc(class_idx);
}
```

**Branch Reduction**: 4-5 branches → 1 branch (hot path)

---

## Performance Results

### Benchmark Setup
- **Workload**: `bench_random_mixed_hakmem 1000000 256 42`
- **Compiler**: gcc 11.4.0 with `-O3 -flto -march=native`
- **PGO**: Disabled (fair A/B comparison)
- **Runs**: 5 runs each, averaged

### Results

#### Baseline (Phase 26-A, without Hot/Cold Box)
```
Run 1: 52.66 M ops/s
Run 2: 52.49 M ops/s
Run 3: 53.05 M ops/s
Run 4: 54.61 M ops/s
Run 5: 53.71 M ops/s
Average: 53.30 M ops/s
```

#### Hot/Cold Box (Phase 4-Step2)
```
Run 1: 56.84 M ops/s
Run 2: 58.86 M ops/s
Run 3: 55.93 M ops/s
Run 4: 56.41 M ops/s
Run 5: 57.96 M ops/s
Average: 57.20 M ops/s
```

### Improvement
```
Absolute: +3.90 M ops/s
Relative: +7.3%
Branch reduction: 4-5 → 1 (hot path)
```

**Verification**: Consistent improvement across all 5 runs ✓

---

## Technical Analysis

### Why +7.3% Improvement?

**1. Branch Prediction Accuracy**:
- Baseline: 4-5 branches in hot path → higher misprediction rate
- Hot/Cold Box: 1 branch (cache empty check, highly predictable)
- CPU pipeline stays hot for longer

**2. I-Cache Locality**:
- Baseline: Hot path mixed with cold refill logic → larger code size
- Hot/Cold Box: Hot path isolated (10-20 instructions) → better i-cache hit rate
- Cold path moved out-of-line → doesn't pollute i-cache

**3. Compiler Optimizations**:
- `always_inline` + small hot path → better inlining decisions
- `cold` attribute → compiler can optimize cold path for size, not speed
- `TINY_HOT_LIKELY` hints → better register allocation, code layout

**4. Cache Hit Rate**:
- Unified Cache capacity: Default 2048 slots for hot classes (C2/C3)
- Hit rate: ~95-99% (based on workload)
- Most allocations go through hot path (1 branch)

---

## Branch Analysis Breakdown

### Baseline (Phase 26-A)
1. `class_idx < 0 || >= TINY_NUM_CLASSES` - range check (UNLIKELY)
2. `cache->slots == NULL` - lazy init check (UNLIKELY, once per thread)
3. `cache->head != cache->tail` - empty check (LIKELY hit)
4. *(inside unified_cache_pop_or_refill):* refill logic (UNLIKELY, on miss)

**Total hot path**: 3-4 branches (depending on lazy init)

### Hot/Cold Box (Phase 4-Step2)
1. `cache->head != cache->tail` - empty check (LIKELY hit)

**Total hot path**: 1 branch

**Eliminated**:
- Range check: Moved to caller contract (hak_tiny_size_to_class guarantees valid)
- Lazy init: Moved assumption (cache initialized before hot path)
- Refill logic: Moved to cold path (noinline)

---

## Box Pattern Compliance

✅ **Single Responsibility**:
- Hot Path Box: Cache hit ONLY
- Cold Path Box: Refill, drain, errors ONLY

✅ **Clear Contract**:
- Hot Path: Input = class_idx (valid), Output = USER pointer or NULL
- Cold Path: Input = class_idx (miss detected), Output = USER pointer or NULL

✅ **Observable**:
- Hot Path: `TINY_HOT_METRICS_HIT/MISS` macros (zero overhead in Release)
- Cold Path: Debug logging (`tiny_cold_report_error`)

✅ **Safe**:
- Hot Path: Branch prediction hints (`TINY_HOT_LIKELY/UNLIKELY`)
- Cold Path: Defensive programming, full error checking

✅ **Testable**:
- Hot Path: Isolated function (`tiny_hot_alloc_fast`)
- Cold Path: Isolated function (`tiny_cold_refill_and_alloc`)
- Easy A/B testing: Swap hot path implementation without affecting cold path

---

## Artifacts

### New Files
- `core/box/tiny_front_hot_box.h` - Hot Path Box (230 lines)
- `core/box/tiny_front_cold_box.h` - Cold Path Box (140 lines)

### Modified Files
- `core/front/malloc_tiny_fast.h` - Updated to use Hot/Cold Boxes
- `.gitignore` - Added `*.d` files (dependency files, auto-generated)
- `Makefile` - PGO targets temporarily disabled
- `build_pgo.sh` - PGO workflow temporarily disabled

### Documentation
- `PHASE4_STEP2_COMPLETE.md` - This completion report
- `CURRENT_TASK.md` - Updated with Step 2 completion

---

## PGO Status

**Current Status**: Temporarily disabled due to build issues

**Issue**: `__gcov_merge_time_profile` undefined reference error
- Root cause: gcc/lto interaction with PGO in complex build
- Impact: Cannot run PGO workflow (pgo-tiny-profile / pgo-tiny-build)

**Workaround**:
- All benchmarks run without PGO (fair A/B comparison)
- Hot/Cold Box shows +7.3% improvement on its own
- PGO will be re-enabled in future commit after issue resolution

**Expected with PGO**:
- Phase 4-Step1 (PGO only): +6.25% (57.0 → 60.6 M ops/s)
- Phase 4-Step2 (Hot/Cold Box, no PGO): +7.3% (53.3 → 57.2 M ops/s)
- **Estimated combined** (Hot/Cold + PGO): +13-15% (53.3 → 60-62 M ops/s)

---

## Next Steps

### Phase 4-Step3: Front Config Box (Pending)
- **Target**: +5-8% improvement (57.2 → 60-62 M ops/s)
- **Approach**: Compile-time config optimization
  - Replace runtime ENV checks with compile-time macros
  - `HAKMEM_TINY_FRONT_PGO=1` build flag
  - Eliminate branches from config checks
- **Design**: Already specified in `PHASE4_TINY_FRONT_BOX_DESIGN.md`

### PGO Re-enablement (TODO)
- **Issue**: Resolve `__gcov_merge_time_profile` build error
- **Approaches**:
  1. Try gcc 12+ (newer PGO implementation)
  2. Simplify LTO flags (`-flto=auto` instead of `-flto`)
  3. Split PGO and LTO into separate build steps
- **Priority**: Medium (after Step 3 or separately)

### Overall Phase 4 Target
- **Phase 3 baseline**: 56.8 M ops/s (with mincore removal)
- **Phase 4 target**: 73-83 M ops/s (+28-46% cumulative)
- **Current progress** (Step 1 + Step 2, no PGO): 57.2 M ops/s (+0.7% over Phase 3)
- **Expected with PGO**: 60-62 M ops/s (+6-9% over Phase 3)

---

## Lessons Learned

1. **Hot/Cold Separation Works**: +7.3% with minimal code changes
2. **Branch Reduction Matters**: 4-5 → 1 branches = measurable improvement
3. **i-Cache Locality Critical**: Keeping hot path small improves performance
4. **Box Pattern Scales**: Easy to test, isolate, and measure
5. **PGO Can Be Tricky**: Build complexity can cause issues (need robust fallback)

---

## Conclusion

Phase 4-Step2 successfully implemented Hot/Cold Path separation using the Box pattern, achieving **+7.3% performance improvement** (53.3 → 57.2 M ops/s) with:
- ✅ Branch reduction: 4-5 → 1 (hot path)
- ✅ I-cache locality: Isolated hot path (10-20 instructions)
- ✅ Clear contracts: Hot = cache hit, Cold = refill/errors
- ✅ Box pattern compliance: Single responsibility, observable, safe
- ✅ Consistent results: All 5 benchmark runs showed improvement

**PGO Status**: Temporarily disabled (build issues), will re-enable separately

**Next**: Phase 4-Step3 (Front Config Box) or PGO re-enablement

---

**Signed**: Claude (2025-11-29)
**Commit**: `04186341c` - Phase 4-Step2: Add Hot/Cold Path Box (+7.3% performance)