hakmem/PHASE2B_QUICKSTART.md

Phase 2b: Adaptive TLS Cache Sizing - Quick Start

Status: ✅ IMPLEMENTED (2025-11-08) Expected Impact: +3-10% performance, -30-50% memory

---

What Was Implemented

Adaptive TLS cache sizing that automatically grows/shrinks per-class cache based on usage:

• Hot classes (high usage) → grow to 2048 slots
• Cold classes (low usage) → shrink to 16 slots
• Initial capacity: 64 slots (down from 256)

---

Files Created

1. core/tiny_adaptive_sizing.h - Header with API and inline helpers
2. core/tiny_adaptive_sizing.c - Implementation of grow/shrink/adapt logic

Files Modified

1. core/tiny_alloc_fast.inc.h - Capacity check, refill clamping, tracking
2. core/hakmem_tiny_init.inc - Init call
3. core/hakmem_tiny.c - Header include
4. Makefile - Add tiny_adaptive_sizing.o to all build targets

Total: 319 new lines + 19 modified lines = 338 lines

---

How To Use

Build

# Full rebuild (recommended after pulling changes)
make clean && make larson_hakmem

# Or just rebuild adaptive sizing module
make tiny_adaptive_sizing.o

Run

# Default: Adaptive sizing enabled with logging
./larson_hakmem 10 8 128 1024 1 12345 4

# Disable adaptive sizing (use fixed 64 slots)
HAKMEM_ADAPTIVE_SIZING=0 ./larson_hakmem 10 8 128 1024 1 12345 4

# Enable adaptive sizing but suppress logs
HAKMEM_ADAPTIVE_LOG=0 ./larson_hakmem 10 8 128 1024 1 12345 4

---

Expected Logs

[ADAPTIVE] Adaptive sizing initialized (initial_cap=64, min=16, max=2048)
[TLS_CACHE] Grow class 4: 64 → 128 slots (grow_count=1)
[TLS_CACHE] Grow class 4: 128 → 256 slots (grow_count=2)
[TLS_CACHE] Grow class 4: 256 → 512 slots (grow_count=3)
[TLS_CACHE] Keep class 1 at 64 slots (usage=45.2%)
[TLS_CACHE] Shrink class 0: 64 → 32 slots (shrink_count=1)

Interpretation:

• Class 4 grows: High allocation rate → needs more cache
• Class 1 stable: Moderate usage → keep current size
• Class 0 shrinks: Low usage → reclaim memory

---

How It Works

1. Initialization

• All classes start at 64 slots (reduced from 256)
• Stats reset: high_water_mark=0, refill_count=0

2. Tracking (on every refill)

• Update high_water_mark if current count > previous peak
• Increment refill_count

3. Adaptation (every 10 refills or 1 second)

• Calculate usage ratio: high_water_mark / capacity
• If usage > 80%: Grow (capacity *= 2, max 2048)
• If usage < 20%: Shrink (capacity /= 2, min 16)
• Else: Keep current size (log usage %)

4. Enforcement

• Before refill: Check available_capacity = capacity - current_count
• If full: Skip refill (return 0)
• Else: Clamp refill_count = min(wanted, available)

---

Environment Variables

Variable	Default	Description
HAKMEM_ADAPTIVE_SIZING	1	Enable/disable adaptive sizing (1=on, 0=off)
HAKMEM_ADAPTIVE_LOG	1	Enable/disable adaptation logs (1=on, 0=off)

---

Testing Checklist

• Code compiles successfully (tiny_adaptive_sizing.o)
• Integration compiles (hakmem_tiny.o)
• Full build works (larson_hakmem) - Blocked by L25 pool error (unrelated)
• Logs show adaptive behavior (grow/shrink based on usage)
• Hot class (e.g., 4) grows to 512+ slots
• Cold class (e.g., 0) shrinks to 16-32 slots
• Performance improvement measured (+3-10% expected)
• Memory reduction measured (-30-50% expected)

---

Known Issues

⚠️ L25 Pool Build Error (Unrelated)

Error: hakmem_l25_pool.c:1097:36: error: 'struct <anonymous>' has no member named 'freelist' Impact: Blocks full larson_hakmem build Cause: L25 pool struct mismatch (NOT caused by Phase 2b) Workaround: Fix L25 pool separately OR use simpler benchmarks

Alternatives for Testing

1. Build only adaptive sizing module:

   make tiny_adaptive_sizing.o hakmem_tiny.o
   

2. Use simpler benchmarks (if available):

   make bench_tiny
   ./bench_tiny
   

3. Create minimal test (100-line standalone):

   #include "core/tiny_adaptive_sizing.h"
   // ... simple alloc/free loop to trigger adaptation
   

---

Next Steps

1. Fix L25 pool error (separate task)
2. Run Larson benchmark to verify behavior
3. Measure performance (+3-10% expected)
4. Measure memory (-30-50% expected)
5. Implement Phase 2b.1: SuperSlab integration for block return

---

Quick Reference

Key Functions

• adaptive_sizing_init() - Initialize all classes to 64 slots
• grow_tls_cache(class_idx) - Double capacity (max 2048)
• shrink_tls_cache(class_idx) - Halve capacity (min 16)
• adapt_tls_cache_size(class_idx) - Decide grow/shrink/keep
• update_high_water_mark(class_idx) - Track peak usage
• track_refill_for_adaptation(class_idx) - Called after every refill

Key Constants

• TLS_CACHE_INITIAL_CAPACITY = 64 (was 256)
• TLS_CACHE_MIN_CAPACITY = 16
• TLS_CACHE_MAX_CAPACITY = 2048
• GROW_THRESHOLD = 0.8 (80%)
• SHRINK_THRESHOLD = 0.2 (20%)
• ADAPT_REFILL_THRESHOLD = 10 refills
• ADAPT_TIME_THRESHOLD_NS = 1s

---

Full Report: See /mnt/workdisk/public_share/hakmem/PHASE2B_IMPLEMENTATION_REPORT.md Spec: See /mnt/workdisk/public_share/hakmem/PHASE2B_TLS_ADAPTIVE_SIZING.md