hakmem/docs/analysis/POOL_HOT_PATH_BOTTLENECK.md

# Pool Hot Path Bottleneck Analysis

## Executive Summary

**Root Cause**: Pool allocator is 100x slower than expected due to **pthread_mutex_lock in the hot path** (line 267 of `core/box/pool_core_api.inc.h`).

**Current Performance**: 434,611 ops/s
**Expected Performance**: 50-80M ops/s
**Gap**: ~100x slower

## Critical Finding: Mutex in Hot Path

### The Smoking Gun (Line 267)
```c
// core/box/pool_core_api.inc.h:267
pthread_mutex_t* lock = &g_pool.freelist_locks[class_idx][shard_idx].m;
pthread_mutex_lock(lock);  // 💀 FULL KERNEL MUTEX IN HOT PATH
```

**Impact**: Every allocation that misses ALL TLS caches falls into this mutex lock:
- **Mutex overhead**: 100-500 cycles (kernel syscall)
- **Contention overhead**: 1000+ cycles under MT load
- **Cache invalidation**: 50-100 cycles from cache line bouncing

## Detailed Bottleneck Breakdown

### Pool Allocator Hot Path (hak_pool_try_alloc)
```c
Line 234-236: TC drain check       // ~20-30 cycles
Line 236:     TLS ring check       // ~10-20 cycles
Line 237:     TLS LIFO check       // ~10-20 cycles
Line 240-256: Trylock probe loop   // ~100-300 cycles (3 attempts!)
Line 258-261: Active page checks   // ~30-50 cycles (3 pages!)
Line 267:     pthread_mutex_lock   // 💀 100-500+ cycles
Line 280:     refill_freelist      // ~1000+ cycles (mmap)
```

**Total worst case**: 1500-2500 cycles per allocation

### Tiny Allocator Hot Path (tiny_alloc_fast)
```c
Line 205: Load TLS head         // 1 cycle
Line 206: Check NULL            // 1 cycle
Line 238: Update head = *next   // 2-3 cycles
Return                          // 1 cycle
```

**Total**: 5-6 cycles (300x faster!)

## Performance Analysis

### Cycle Cost Breakdown

| Operation | Pool (cycles) | Tiny (cycles) | Ratio |
|-----------|---------------|---------------|-------|
| TLS cache check | 60-100 | 2-3 | 30x slower |
| Trylock probes | 100-300 | 0 | ∞ |
| Mutex lock | 100-500 | 0 | ∞ |
| Atomic operations | 50-100 | 0 | ∞ |
| Random generation | 10-20 | 0 | ∞ |
| **Total Hot Path** | **320-1020** | **5-6** | **64-170x slower** |

### Why Tiny is Fast

1. **Single TLS freelist**: Direct pointer pop (3-4 instructions)
2. **No locks**: Pure TLS, zero synchronization
3. **No atomics**: Thread-local only
4. **Simple refill**: Batch from SuperSlab when empty

### Why Pool is Slow

1. **Multiple cache layers**: Ring + LIFO + Active pages (complex checks)
2. **Trylock probes**: Up to 3 mutex attempts before main lock
3. **Full mutex lock**: Kernel syscall in hot path
4. **Atomic remote lists**: Memory barriers and cache invalidation
5. **Per-allocation RNG**: Extra cycles for sampling

## Root Causes

### 1. Over-Engineered Architecture
Pool has 5 layers of caching before hitting the mutex:
- TC (Thread Cache) drain
- TLS ring
- TLS LIFO
- Active pages (3 of them!)
- Trylock probes

Each layer adds branches and cycles, yet still falls back to mutex!

### 2. Mutex-Protected Freelist
The core freelist is protected by **64 mutexes** (7 classes × 8 shards + extra), but this still causes massive contention under MT load.

### 3. Complex Shard Selection
```c
// Line 238-239
int shard_idx = hak_pool_get_shard_index(site_id);
int s0 = choose_nonempty_shard(class_idx, shard_idx);
```
Requires hash computation and nonempty mask checking.

## Proposed Fix: Lock-Free Pool Allocator

### Solution 1: Copy Tiny's Approach (Recommended)
**Effort**: 4-6 hours
**Expected Performance**: 40-60M ops/s

Replace entire Pool hot path with Tiny-style TLS freelist:
```c
void* hak_pool_try_alloc_fast(size_t size, uintptr_t site_id) {
    int class_idx = hak_pool_get_class_index(size);

    // Simple TLS freelist (like Tiny)
    void* head = g_tls_pool_head[class_idx];
    if (head) {
        g_tls_pool_head[class_idx] = *(void**)head;
        return (char*)head + HEADER_SIZE;
    }

    // Refill from backend (batch, no lock)
    return pool_refill_and_alloc(class_idx);
}
```

### Solution 2: Remove Mutex, Use CAS
**Effort**: 8-12 hours
**Expected Performance**: 20-30M ops/s

Replace mutex with lock-free CAS operations:
```c
// Instead of pthread_mutex_lock
PoolBlock* old_head;
do {
    old_head = atomic_load(&g_pool.freelist[class_idx][shard_idx]);
    if (!old_head) break;
} while (!atomic_compare_exchange_weak(&g_pool.freelist[class_idx][shard_idx],
                                        &old_head, old_head->next));
```

### Solution 3: Increase TLS Cache Hit Rate
**Effort**: 2-3 hours
**Expected Performance**: 5-10M ops/s (partial improvement)

- Increase POOL_L2_RING_CAP from 64 to 256
- Pre-warm TLS caches at init (like Tiny Phase 7)
- Batch refill 64 blocks at once

## Implementation Plan

### Quick Win (2 hours)
1. Increase `POOL_L2_RING_CAP` to 256
2. Add pre-warming in `hak_pool_init()`
3. Test performance

### Full Fix (6 hours)
1. Create `pool_fast_path.inc.h` (copy from tiny_alloc_fast.inc.h)
2. Replace `hak_pool_try_alloc` with simple TLS freelist
3. Implement batch refill without locks
4. Add feature flag for rollback safety
5. Test MT performance

## Expected Results

With proposed fix (Solution 1):
- **Current**: 434,611 ops/s
- **Expected**: 40-60M ops/s
- **Improvement**: 92-138x faster
- **vs System**: Should achieve 70-90% of System malloc

## Files to Modify

1. `core/box/pool_core_api.inc.h`: Replace lines 229-286
2. `core/hakmem_pool.h`: Add TLS freelist declarations
3. Create `core/pool_fast_path.inc.h`: New fast path implementation

## Success Metrics

✅ Pool allocation hot path < 20 cycles
✅ No mutex locks in common case
✅ TLS hit rate > 95%
✅ Performance > 40M ops/s for 8-32KB allocations
✅ MT scaling without contention