hakmem/docs/archive/BOX3_REFACTORING.md

Box 3 Refactoring Complete - Geometry & Capacity Calculator

📦 概要

Box理論に基づき、Stride/Capacity/Slab Base計算を単一の責任Boxに集約しました。

---

🎯 Box 3の責任

新設ファイル: core/tiny_box_geometry.h

責任範囲:

1. Stride計算: Block size + header（C7はheaderless）
2. Capacity計算: Usable bytes / stride（Slab 0は特殊容量）
3. Slab Base計算: Slab 0の2048オフセット処理
4. 境界検証: Linear carveのFail-Fastガード

---

📋 提供API

1️⃣ Stride計算

size_t tiny_stride_for_class(int class_idx);

• C7 (1KB): 1024 (headerless)
• C0-C6: class_size + 1 (1-byte header)

2️⃣ Capacity計算

uint16_t tiny_capacity_for_slab(int slab_idx, size_t stride);

• Slab 0: SUPERSLAB_SLAB0_USABLE_SIZE / stride
• Slab 1+: SUPERSLAB_SLAB_USABLE_SIZE / stride

3️⃣ Slab Base取得

uint8_t* tiny_slab_base_for_geometry(SuperSlab* ss, int slab_idx);

• Slab 0: ss + SLAB_SIZE * 0 + SUPERSLAB_SLAB0_DATA_OFFSET
• Slab 1+: ss + SLAB_SIZE * slab_idx

4️⃣ Block Address計算

void* tiny_block_at_index(uint8_t* base, uint16_t index, size_t stride);

• base + (index * stride)

5️⃣ 境界検証

int tiny_carve_guard(int slab_idx, uint16_t carved, size_t stride, uint32_t reserve);
int tiny_carve_guard_verbose(...);  // Debug版（詳細ログ付き）

---

🔧 修正したファイル

✅ Box 2 (Refill Dispatcher)

• core/hakmem_tiny_refill.inc.h
  • ❌ Before: size_t bs = g_tiny_class_sizes[c] + ((c != 7) ? 1 : 0); （4箇所重複）
  • ✅ After: size_t bs = tiny_stride_for_class(c);
  • ❌ Before: uint8_t* base = tiny_slab_base_for(...);
  • ✅ After: uint8_t* base = tiny_slab_base_for_geometry(...);

✅ Box 2 - P0 Optimized Path

• core/hakmem_tiny_refill_p0.inc.h
  • 2箇所のstride計算を統一
  • Slab base/limit計算をBox 3委譲

✅ Box 4 (SuperSlab Manager)

• core/tiny_superslab_alloc.inc.h
  • Linear alloc, Freelist alloc, Retry pathをBox 3使用
  • Debug guardsをBox 3のAPIに置き換え

✅ Box 5 (SuperSlab Primitives)

• core/superslab/superslab_inline.h
  • tiny_slab_base_for() → Box 3へ委譲する薄いwrapperに変更
  • 後方互換性のためwrapperは維持

---

🐛 C7 (1KB) バグ修正への寄与

問題: メインパス（Legacy refill）でC7のみSEGV発生

仮説: Box境界が曖昧だったため、C7特有の処理が漏れていた

処理	Before（分散）	After（集約）
Stride計算	各ファイルで個別実装（7箇所）	Box 3の1箇所のみ
Slab base計算	各ファイルで重複（5箇所）	Box 3の1箇所のみ
Capacity計算	各ファイルで独自実施	Box 3の1箇所のみ
C7 headerless処理	(class_idx != 7) ? 1 : 0 が散在	Box 3で明示的に扱う

期待される効果:

1. C7の特殊処理が明示的になる → バグが入りにくい
2. 単一の真実の源により、修正が1箇所で済む
3. 境界検証が統一される → Debug時のFail-Fastが確実

---

📊 コード削減効果

• 重複コード削除: 約80行（stride/capacity/base計算の重複）
• Box 3新設: 約200行（集約+ドキュメント）
• ネット増: +120行（可読性・保守性の大幅向上と引き換え）

---

🚀 次のステップ

Phase 1: ビルド検証

./build.sh release bench_fixed_size_hakmem
./build.sh debug bench_fixed_size_hakmem

Phase 2: C7デバッグ

Box 3により、以下が容易になります：

1. Stride/Capacity計算の検証

   • tiny_stride_for_class(7) が正しく 1024 を返すか
   • tiny_capacity_for_slab(0, 1024) が正しい容量を返すか

2. Slab Base計算の検証

   • tiny_slab_base_for_geometry(ss, 0) が正しいオフセットを適用するか

3. 境界検証の有効化

   • Debug buildで tiny_carve_guard_verbose() の詳細ログ出力

Phase 3: Task先生によるデバッグ

# Debug build with verbose guards
./build.sh debug bench_fixed_size_hakmem

# Run C7 with fail-fast level 2
HAKMEM_TINY_REFILL_FAILFAST=2 \
./bench_fixed_size_hakmem 200000 1024 128

---

📝 Box理論の勝利

Before (Box境界曖昧):

[ hakmem_tiny_refill.inc.h ]
  ├─ stride計算 × 3
  ├─ slab_base計算 × 3
  └─ capacity計算（implicit）

[ tiny_superslab_alloc.inc.h ]
  ├─ stride計算 × 2
  ├─ slab_base計算 × 2
  └─ capacity計算（implicit）

[ hakmem_tiny_refill_p0.inc.h ]
  ├─ stride計算 × 2
  └─ slab_base計算 × 2

After (Box 3で集約):

┌─────────────────────────────┐
│ Box 3: Geometry Calculator  │
│  ├─ stride_for_class()      │ ← Single Source of Truth
│  ├─ capacity_for_slab()     │ ← C7特殊処理を明示
│  ├─ slab_base_for_geometry()│ ← Slab 0オフセット処理
│  ├─ block_at_index()        │ ← 統一されたアドレス計算
│  └─ carve_guard_verbose()   │ ← Fail-Fast検証
└─────────────────────────────┘
         ↑
         │ (呼び出し)
         │
┌────────┴────────┬─────────────────┬──────────────────┐
│ Box 2: Refill   │ Box 2: P0 Path  │ Box 4: SuperSlab │
│ (Legacy)        │ (Optimized)     │ Manager          │
└─────────────────┴─────────────────┴──────────────────┘

---

✅ 受け入れ基準

• Box 3新設完了（core/tiny_box_geometry.h）
• 全ファイルでstride/capacity/base計算をBox 3に統一
• C7特殊処理（headerless）がBox 3で明示的
• Release buildコンパイル成功
• Debug buildコンパイル成功
• 256B (C5) 安定性維持（3/3 runs成功）
• 1KB (C7) SEGV修正（次フェーズ）

---

Box理論により、コードの責任境界が明確になり、C7バグのデバッグが容易になりました！ 🎉