hakmem/docs/design/PHASE4_TINY_FRONT_BOX_DESIGN.md

# Phase 4: Tiny Front Optimization - Box Design Document

**Date**: 2025-11-29
**Author**: Claude Code
**Goal**: 2x throughput improvement via Box化 + PGO + Hot/Cold separation

---

## Design Philosophy

### Box化原則
1. **Single Responsibility**: 1 Box = 1明確な責務
2. **Clear Contracts**: 入力/出力/保証を明示
3. **Macro-Based Pointers**: 型安全、null check、統一API
4. **Testability**: 各Boxが独立してテスト可能
5. **Incremental**: 段階的実装・検証

### Pointer Safety Strategy
**全てのポインター操作をマクロで抽象化**:
- Null check統一
- 型キャスト安全性
- デバッグビルドでアサーション
- リリースビルドで最適化

---

## Box 1: PGO Profile Collection Box

### 責務
Tiny Front用PGOプロファイル収集を標準化・自動化

### ファイル構成
```
scripts/box/pgo_tiny_profile_box.sh     - メインスクリプト
scripts/box/pgo_tiny_profile_config.sh  - 設定（ワークロード定義）
```

### Contract

**Input**:
- Built binaries with `-fprofile-generate -flto`
- `bench_random_mixed_hakmem`
- `bench_tiny_hot_hakmem`

**Output**:
- `.gcda` profile data files
- Profile summary report

**Guarantees**:
- Deterministic execution (固定seed)
- Representative workload coverage
- Error detection & reporting

### Implementation

#### scripts/box/pgo_tiny_profile_box.sh
```bash
#!/bin/bash
# Box: PGO Profile Collection
# Contract: Execute representative Tiny workloads for PGO
# Usage: ./scripts/box/pgo_tiny_profile_box.sh

set -e

SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
source "${SCRIPT_DIR}/pgo_tiny_profile_config.sh"

echo "========================================="
echo "Box: PGO Profile Collection (Tiny Front)"
echo "========================================="

# Validate binaries exist
for bin in "${PGO_BINARIES[@]}"; do
    if [[ ! -x "$bin" ]]; then
        echo "ERROR: Binary not found or not executable: $bin"
        exit 1
    fi
done

# Clean old profile data
echo "[PGO_BOX] Cleaning old .gcda files..."
find . -name "*.gcda" -delete

# Execute workloads
echo "[PGO_BOX] Executing representative workloads..."

for workload in "${PGO_WORKLOADS[@]}"; do
    echo "[PGO_BOX] Running: $workload"
    eval "$workload"
done

# Verify profile data generated
GCDA_COUNT=$(find . -name "*.gcda" | wc -l)
if [[ $GCDA_COUNT -eq 0 ]]; then
    echo "ERROR: No .gcda files generated!"
    exit 1
fi

echo "[PGO_BOX] Profile collection complete"
echo "[PGO_BOX] Generated $GCDA_COUNT .gcda files"
echo "========================================="
```

#### scripts/box/pgo_tiny_profile_config.sh
```bash
#!/bin/bash
# Box: PGO Profile Configuration
# Purpose: Define representative workloads for Tiny Front

# Binaries to profile
PGO_BINARIES=(
    "./bench_random_mixed_hakmem"
    "./bench_tiny_hot_hakmem"
)

# Representative workloads (deterministic seeds)
PGO_WORKLOADS=(
    # Random mixed: Common case (medium working set)
    "./bench_random_mixed_hakmem 5000000 256 42"

    # Random mixed: Smaller working set (higher cache hit)
    "./bench_random_mixed_hakmem 5000000 128 42"

    # Random mixed: Larger working set (more diverse)
    "./bench_random_mixed_hakmem 5000000 512 42"

    # Tiny hot path: 16B allocations
    "./bench_tiny_hot_hakmem 16 100 60000"

    # Tiny hot path: 64B allocations
    "./bench_tiny_hot_hakmem 64 100 60000"
)
```

### Makefile Integration
```makefile
# PGO Tiny Profile Build
pgo-tiny-profile:
	@echo "Building PGO profile binaries..."
	$(MAKE) clean
	$(MAKE) CFLAGS+="-fprofile-generate -flto" \
	        LDFLAGS+="-fprofile-generate -flto" \
	        HAKMEM_BUILD_RELEASE=1 \
	        HAKMEM_TINY_FRONT_PGO=1 \
	        bench_random_mixed_hakmem bench_tiny_hot_hakmem

# PGO Tiny Optimized Build
pgo-tiny-build:
	@echo "Collecting PGO profile data..."
	./scripts/box/pgo_tiny_profile_box.sh
	@echo "Building PGO-optimized binaries..."
	$(MAKE) clean
	$(MAKE) CFLAGS+="-fprofile-use -flto" \
	        LDFLAGS+="-fprofile-use -flto" \
	        HAKMEM_BUILD_RELEASE=1 \
	        HAKMEM_TINY_FRONT_PGO=1 \
	        bench_random_mixed_hakmem

# PGO Full Workflow
pgo-tiny-full: pgo-tiny-profile pgo-tiny-build
	@echo "PGO optimization complete!"
	@echo "Testing optimized binary..."
	./bench_random_mixed_hakmem 1000000 256 42
```

---

## Box 2: Tiny Front Hot Path Box

### 責務
Ultra-fast allocation path（分岐数最小化、always_inline）

### ファイル構成
```
core/box/tiny_front_hot_box.h          - Hot path implementation
core/box/tiny_front_hot_box_macros.h   - Pointer safety macros
```

### Contract

**Preconditions**:
- `class_idx` validated (0-7)
- TLS initialized
- Not in slow path mode

**Guarantees**:
- Maximum 5-7 branches
- Always inlined
- Null-safe pointer operations
- PGO-optimized

**Performance**:
- Hit case: ~20-30 cycles
- Miss case: → Cold Box (~100-200 cycles)

### Pointer Safety Macros

#### core/box/tiny_front_hot_box_macros.h
```c
#ifndef TINY_FRONT_HOT_BOX_MACROS_H
#define TINY_FRONT_HOT_BOX_MACROS_H

#include <stdint.h>
#include <stddef.h>

// ========== Pointer Type Definitions ==========

// Opaque pointer types for type safety
typedef void* TinyHotPtr;       // User-facing allocation pointer
typedef void* TinySLLNode;      // SLL node pointer
typedef void* TinySlabBase;     // Slab base pointer

// ========== Pointer Safety Macros ==========

#if HAKMEM_BUILD_RELEASE
  // Release: No overhead
  #define TINY_HOT_PTR_CHECK(ptr)           (ptr)
  #define TINY_HOT_PTR_CAST(type, ptr)      ((type)(ptr))
  #define TINY_HOT_PTR_NULL                 NULL
  #define TINY_HOT_PTR_IS_NULL(ptr)         ((ptr) == NULL)
  #define TINY_HOT_PTR_IS_VALID(ptr)        ((ptr) != NULL)
#else
  // Debug: Assertions enabled
  #include <assert.h>
  #define TINY_HOT_PTR_CHECK(ptr) \
      ({ void* _p = (ptr); \
         assert(((uintptr_t)_p & 0x7) == 0 && "Pointer not 8-byte aligned"); \
         _p; })
  #define TINY_HOT_PTR_CAST(type, ptr) \
      ((type)TINY_HOT_PTR_CHECK(ptr))
  #define TINY_HOT_PTR_NULL                 NULL
  #define TINY_HOT_PTR_IS_NULL(ptr)         ((ptr) == NULL)
  #define TINY_HOT_PTR_IS_VALID(ptr) \
      ({ void* _p = (ptr); \
         _p != NULL && ((uintptr_t)_p & 0x7) == 0; })
#endif

// ========== SLL Operations Macros ==========

// Read next pointer from SLL node
#define TINY_HOT_SLL_NEXT(node) \
    TINY_HOT_PTR_CAST(TinySLLNode, tiny_nextptr_get(node))

// Write next pointer to SLL node
#define TINY_HOT_SLL_SET_NEXT(node, next) \
    tiny_nextptr_set((node), TINY_HOT_PTR_CHECK(next))

// Pop from TLS SLL (class-specific)
#define TINY_HOT_SLL_POP(class_idx) \
    TINY_HOT_PTR_CAST(TinyHotPtr, tls_sll_pop_inline(class_idx))

// Push to TLS SLL (class-specific)
#define TINY_HOT_SLL_PUSH(class_idx, ptr) \
    tls_sll_push_inline((class_idx), TINY_HOT_PTR_CHECK(ptr))

// ========== Likely/Unlikely Hints ==========

#define TINY_HOT_LIKELY(x)       __builtin_expect(!!(x), 1)
#define TINY_HOT_UNLIKELY(x)     __builtin_expect(!!(x), 0)

// ========== Branch Prediction Hints ==========

// Expected: SLL hit (80-90% of allocations)
#define TINY_HOT_EXPECT_HIT(ptr) \
    TINY_HOT_LIKELY(TINY_HOT_PTR_IS_VALID(ptr))

// Expected: SLL miss (10-20% of allocations)
#define TINY_HOT_EXPECT_MISS(ptr) \
    TINY_HOT_UNLIKELY(TINY_HOT_PTR_IS_NULL(ptr))

#endif // TINY_FRONT_HOT_BOX_MACROS_H
```

### Implementation

#### core/box/tiny_front_hot_box.h
```c
#ifndef TINY_FRONT_HOT_BOX_H
#define TINY_FRONT_HOT_BOX_H

#include "tiny_front_hot_box_macros.h"
#include "../tiny_next_ptr_box.h"  // tiny_nextptr_get/set
#include "../tls_sll_box.h"        // TLS SLL operations

// Forward declaration for cold path
void* tiny_front_cold_refill(int class_idx)
    __attribute__((noinline, cold));

// ========== Box: Tiny Front Hot Path ==========
// Contract: Ultra-fast allocation with 5-7 branches max
// Precondition: class_idx validated (0-7), TLS initialized
// Performance: ~20-30 cycles (hit), ~100-200 cycles (miss → cold)
// Optimization: always_inline + PGO + branch hints

__attribute__((always_inline))
static inline TinyHotPtr tiny_front_hot_alloc(int class_idx)
{
    // Branch 1: TLS SLL pop (expected: 80-90% hit)
    TinyHotPtr ptr = TINY_HOT_SLL_POP(class_idx);

    // Branch 2: Check if hit (optimized by PGO)
    if (TINY_HOT_EXPECT_HIT(ptr)) {
        // Fast path exit: ~20-30 cycles total
        return ptr;
    }

    // Branch 3: Miss → Cold path refill (10-20% of allocations)
    return TINY_HOT_PTR_CAST(TinyHotPtr, tiny_front_cold_refill(class_idx));
}

// ========== Box: Tiny Front Hot Free ==========
// Contract: Ultra-fast free with 3-5 branches max
// Precondition: ptr is valid Tiny allocation
// Performance: ~15-25 cycles

__attribute__((always_inline))
static inline void tiny_front_hot_free(TinyHotPtr ptr, int class_idx)
{
    // Branch 1: Null check (expected: rare)
    if (TINY_HOT_UNLIKELY(TINY_HOT_PTR_IS_NULL(ptr))) {
        return;
    }

    // Branch 2: Push to TLS SLL (expected: always succeeds)
    TINY_HOT_SLL_PUSH(class_idx, ptr);

    // Fast path exit: ~15-25 cycles total
}

#endif // TINY_FRONT_HOT_BOX_H
```

---

## Box 3: Tiny Front Cold Path Box

### 責務
低頻度allocation/free slow path（noinline, cold属性）

### ファイル構成
```
core/box/tiny_front_cold_box.h         - Cold path implementation
```

### Contract

**Called When**:
- TLS SLL miss (refill needed)
- Slow allocation path (debug, large size, etc.)

**Guarantees**:
- I-cache separated from hot path
- Heavy operations allowed
- Can call into ACE, learning, diagnostics

**Optimization**:
- `noinline` → Not inlined into hot path
- `cold` → Compiler puts in cold section

### Implementation

#### core/box/tiny_front_cold_box.h
```c
#ifndef TINY_FRONT_COLD_BOX_H
#define TINY_FRONT_COLD_BOX_H

#include <stddef.h>
#include "tiny_front_hot_box_macros.h"

// ========== Box: Tiny Front Cold Refill ==========
// Contract: Refill TLS SLL when empty
// Called: 10-20% of allocations (SLL miss)
// Performance: ~100-200 cycles (acceptable for miss case)
// Optimization: noinline, cold → separated from hot path

__attribute__((noinline, cold))
void* tiny_front_cold_refill(int class_idx)
{
    // Heavy refill logic
    // - May allocate new SuperSlab
    // - May trigger ACE learning
    // - May call into diagnostics

    // Call existing refill logic
    tiny_fast_refill_and_take(class_idx);

    // After refill, try pop again
    TinyHotPtr ptr = TINY_HOT_SLL_POP(class_idx);

    if (TINY_HOT_PTR_IS_VALID(ptr)) {
        return ptr;
    }

    // Refill failed → slow allocation
    return tiny_front_cold_slow_alloc(0, class_idx);  // size=0 (unknown)
}

// ========== Box: Tiny Front Cold Slow Alloc ==========
// Contract: Slowest allocation path (debug, diagnostics, ACE)
// Called: Rare (refill failure, special modes)
// Performance: ~500-1000+ cycles (acceptable for rare case)

__attribute__((noinline, cold))
void* tiny_front_cold_slow_alloc(size_t size, int class_idx)
{
    // Debug/diagnostic/ACE learning hooks
    // - Allocation site tracking
    // - Size class profiling
    // - Memory pressure monitoring

    // Call legacy slow path
    return hak_tiny_alloc_slow(size, class_idx);
}

// ========== Box: Tiny Front Cold Drain ==========
// Contract: Drain remote frees (batched, low frequency)
// Called: Background or on threshold
// Optimization: noinline, cold

__attribute__((noinline, cold))
void tiny_front_cold_drain_remote(int class_idx)
{
    // Drain remote free lists into TLS SLL
    // - Batch processing for efficiency
    // - May trigger ACE rebalancing

    tiny_remote_drain_to_sll(class_idx);
}

#endif // TINY_FRONT_COLD_BOX_H
```

---

## Box 4: Tiny Front Config Box

### 責務
Tiny Front設定の一元管理（コンパイル時/実行時切り替え）

### ファイル構成
```
core/box/tiny_front_config_box.h       - Configuration management
core/hakmem_build_flags.h              - Build flag definitions (existing)
```

### Contract

**Compile-time Mode (PGO builds)**:
- `HAKMEM_TINY_FRONT_PGO=1`
- All runtime checks → compile-time constants
- Unused branches eliminated by compiler

**Runtime Mode (normal builds)**:
- Backward compatible
- ENV variable checks as before
- Full feature set available

### Implementation

#### core/box/tiny_front_config_box.h
```c
#ifndef TINY_FRONT_CONFIG_BOX_H
#define TINY_FRONT_CONFIG_BOX_H

// ========== Build Flag Definitions ==========
// Location: core/hakmem_build_flags.h

#ifndef HAKMEM_TINY_FRONT_PGO
#  define HAKMEM_TINY_FRONT_PGO 0
#endif

// ========== PGO Mode: Fixed Configuration ==========

#if HAKMEM_TINY_FRONT_PGO
  // PGO build: Fix configuration for profiling/optimization
  // All runtime checks become compile-time constants

  #define TINY_FRONT_ULTRA_SLIM_ENABLED    0
  #define TINY_FRONT_HEAP_V2_ENABLED       0
  #define TINY_FRONT_SFC_ENABLED           1
  #define TINY_FRONT_FASTCACHE_ENABLED     0
  #define TINY_FRONT_UNIFIED_GATE_ENABLED  1
  #define TINY_FRONT_METRICS_ENABLED       0
  #define TINY_FRONT_DIAG_ENABLED          0

  // Optimization: Constant folding eliminates dead branches
  // Example:
  //   if (TINY_FRONT_HEAP_V2_ENABLED) { ... }
  //   → Compiler eliminates entire block (0 is constant false)

#else
  // Normal build: Runtime configuration (backward compatible)
  // Checks ENV variables or config state

  #define TINY_FRONT_ULTRA_SLIM_ENABLED    ultra_slim_mode_enabled()
  #define TINY_FRONT_HEAP_V2_ENABLED       tiny_heap_v2_enabled()
  #define TINY_FRONT_SFC_ENABLED           sfc_cascade_enabled()
  #define TINY_FRONT_FASTCACHE_ENABLED     tiny_fastcache_enabled()
  #define TINY_FRONT_UNIFIED_GATE_ENABLED  front_gate_unified_enabled()
  #define TINY_FRONT_METRICS_ENABLED       tiny_metrics_enabled()
  #define TINY_FRONT_DIAG_ENABLED          tiny_diag_enabled()

#endif // HAKMEM_TINY_FRONT_PGO

// ========== Configuration Helpers ==========

// Check if running in PGO-optimized build
static inline int tiny_front_is_pgo_build(void)
{
    return HAKMEM_TINY_FRONT_PGO;
}

// Get effective configuration (for diagnostics)
static inline void tiny_front_config_report(void)
{
#if !HAKMEM_BUILD_RELEASE
    fprintf(stderr, "[TINY_FRONT_CONFIG]\n");
    fprintf(stderr, "  PGO Build: %d\n", HAKMEM_TINY_FRONT_PGO);
    fprintf(stderr, "  Ultra SLIM: %d\n", TINY_FRONT_ULTRA_SLIM_ENABLED);
    fprintf(stderr, "  Heap V2: %d\n", TINY_FRONT_HEAP_V2_ENABLED);
    fprintf(stderr, "  SFC: %d\n", TINY_FRONT_SFC_ENABLED);
    fprintf(stderr, "  FastCache: %d\n", TINY_FRONT_FASTCACHE_ENABLED);
    fprintf(stderr, "  Unified Gate: %d\n", TINY_FRONT_UNIFIED_GATE_ENABLED);
#endif
}

#endif // TINY_FRONT_CONFIG_BOX_H
```

#### Update to core/hakmem_build_flags.h
```c
// Add around line 190:

// HAKMEM_TINY_FRONT_PGO:
//   0 = Normal build with runtime configuration (default)
//   1 = PGO-optimized build with compile-time configuration
//       Eliminates runtime branches for maximum performance.
//       Use with: make HAKMEM_TINY_FRONT_PGO=1 pgo-tiny-build
#ifndef HAKMEM_TINY_FRONT_PGO
#  define HAKMEM_TINY_FRONT_PGO 0
#endif
```

---

## Integration: Refactor tiny_alloc_fast()

### Before (複雑な1関数、15-20分岐)
```c
void* tiny_alloc_fast(size_t size) {
    // Ultra SLIM check
    if (ultra_slim_mode_enabled()) { ... }

    // Size to class
    int class_idx = hak_tiny_size_to_class(size);

    // Metrics
    if (tiny_metrics_enabled()) { tiny_sizeclass_hist_hit(class_idx); }

    // Heap V2 check
    if (tiny_heap_v2_enabled()) { ... }

    // FastCache check
    if (tiny_fastcache_enabled()) { ... }

    // SFC cascade
    if (sfc_cascade_enabled()) { ... }

    // TLS SLL pop
    void* ptr = tls_sll_pop(class_idx);
    if (ptr) return ptr;

    // Refill logic (複雑)
    ...
}
```

### After (Box化、3-5分岐のみ)
```c
// Include new boxes
#include "core/box/tiny_front_config_box.h"
#include "core/box/tiny_front_hot_box.h"
#include "core/box/tiny_front_cold_box.h"

void* tiny_alloc_fast(size_t size) {
    // Branch 1: Ultra SLIM mode check (compile-time constant in PGO)
    if (TINY_FRONT_ULTRA_SLIM_ENABLED) {
        return tiny_ultra_slim_alloc(size);  // Separate path
    }

    // Branch 2: Size to class (always needed)
    int class_idx = hak_tiny_size_to_class(size);

    // Branch 3: Hot path (inlined, 2-3 branches inside)
    return tiny_front_hot_alloc(class_idx);

    // Total branches in PGO build: 2-3
    // (Ultra SLIM = 0 → eliminated, hot_alloc inlined)
}
```

**PGO最適化後の実効分岐数**: **2-3分岐のみ**！

---

## Testing Strategy

### Step 1: PGO Workflow Test
```bash
# Build profile version
make pgo-tiny-profile

# Collect profiles (automated)
./scripts/box/pgo_tiny_profile_box.sh

# Build optimized version
make pgo-tiny-build

# Benchmark
./bench_random_mixed_hakmem 1000000 256 42
./bench_tiny_hot_hakmem

# Expected: +5-10% improvement
```

### Step 2: Hot/Cold Separation Test
```bash
# Build with hot/cold boxes
make clean
make HAKMEM_TINY_FRONT_PGO=1 bench_random_mixed_hakmem

# Benchmark
./bench_random_mixed_hakmem 1000000 256 42

# Expected: +10-15% improvement (cumulative +15-25%)
```

### Step 3: Config Box Test
```bash
# PGO build (compile-time config)
make clean
make HAKMEM_TINY_FRONT_PGO=1 pgo-tiny-full

# Normal build (runtime config)
make clean
make bench_random_mixed_hakmem

# Both should work, PGO should be faster
```

### Regression Testing
```bash
# Ensure backward compatibility
HAKMEM_TINY_ULTRA_SLIM=1 ./bench_random_mixed_hakmem 100000 256
HAKMEM_TINY_HEAP_V2=1 ./bench_random_mixed_hakmem 100000 256

# All existing ENV vars should work in normal builds
```

---

## Performance Expectations

### Branch Reduction
- **Before**: 15-20 branches in `tiny_alloc_fast()`
- **After (PGO)**: 2-3 branches (most eliminated by compiler)
- **Gain**: ~40-60% reduction in branch misses

### Instruction Count
- **Before**: ~167M instructions (1M ops)
- **After**: ~120-140M instructions
- **Gain**: ~16-28% reduction

### Throughput
- **Phase 3**: 56.8M ops/s
- **Phase 4.1 (PGO)**: 60-62M ops/s (+5-10%)
- **Phase 4.2 (Hot/Cold)**: 68-75M ops/s (+10-15%)
- **Phase 4.3 (Config)**: 73-83M ops/s (+5-8%)

**Total Improvement**: +28-46% → **2倍に迫る**

---

## Implementation Schedule

### Week 1: PGO Workflow
- Day 1-2: PGO scripts + Makefile
- Day 3: Profile collection + benchmarking
- Day 4: Documentation + review

### Week 2: Hot/Cold Separation
- Day 1-2: Hot Box + macros
- Day 3-4: Cold Box + refactor
- Day 5: Testing + PGO re-optimization

### Week 3: Config Box + Polish
- Day 1-2: Config Box implementation
- Day 3: Integration testing
- Day 4-5: Final benchmarks + documentation

---

## Success Criteria

✅ **Code Quality**:
- All pointer operations use macros
- Clear contracts in each Box
- Zero regression in existing features

✅ **Performance**:
- bench_random_mixed: 73-83M ops/s (vs 56.8M baseline)
- bench_tiny_hot: 100-115M ops/s (vs 81M baseline)
- No regression in other benchmarks

✅ **Maintainability**:
- Hot/Cold separation clear
- PGO workflow documented
- Backward compatible

---

Generated: 2025-11-29
Phase: 4 Design
Next: Implementation (Week 1 start)