198 lines
6.4 KiB
Markdown
198 lines
6.4 KiB
Markdown
# 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計算**
|
||
```c
|
||
size_t tiny_stride_for_class(int class_idx);
|
||
```
|
||
- C7 (1KB): `1024` (headerless)
|
||
- C0-C6: `class_size + 1` (1-byte header)
|
||
|
||
### 2️⃣ **Capacity計算**
|
||
```c
|
||
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取得**
|
||
```c
|
||
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計算**
|
||
```c
|
||
void* tiny_block_at_index(uint8_t* base, uint16_t index, size_t stride);
|
||
```
|
||
- `base + (index * stride)`
|
||
|
||
### 5️⃣ **境界検証**
|
||
```c
|
||
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: ビルド検証**
|
||
```bash
|
||
./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先生によるデバッグ**
|
||
```bash
|
||
# 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 │
|
||
└─────────────────┴─────────────────┴──────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## ✅ **受け入れ基準**
|
||
|
||
- [x] Box 3新設完了（`core/tiny_box_geometry.h`）
|
||
- [x] 全ファイルでstride/capacity/base計算をBox 3に統一
|
||
- [x] C7特殊処理（headerless）がBox 3で明示的
|
||
- [ ] Release buildコンパイル成功
|
||
- [ ] Debug buildコンパイル成功
|
||
- [ ] 256B (C5) 安定性維持（3/3 runs成功）
|
||
- [ ] 1KB (C7) SEGV修正（次フェーズ）
|
||
|
||
---
|
||
|
||
**Box理論により、コードの責任境界が明確になり、C7バグのデバッグが容易になりました！** 🎉
|