hakmem/docs/analysis/FREE_INC_SUMMARY.md

hakmem_tiny_free.inc 構造分析 - クイックサマリー

ファイル概要

hakmem_tiny_free.inc は HAKMEM メモリアロケータのメイン Free パスを実装する大規模ファイル

統計	値
総行数	1,711
実コード行	1,348 (78.7%)
関数数	10個
最大関数	hak_tiny_free_with_slab() - 558行
複雑度	CC 28 (CRITICAL)

---

主要責務ベークダウン

hak_tiny_free_with_slab (558行, 34.2%)  ← HOTTEST - CC 28
  ├─ SuperSlab mode handling (64行)
  ├─ Same-thread TLS push (72行)
  └─ Magazine/SLL/Publisher paths (413行) ← 複雑でテスト困難

hak_tiny_free_superslab (305行, 18.7%)  ← CRITICAL PATH - CC 16
  ├─ Validation & safety checks (30行)
  ├─ Same-thread freelist push (79行)
  └─ Remote/cross-thread queue (159行)

superslab_refill (308行, 24.1%)  ← OPTIMIZATION TARGET - CC 18
  ├─ Mid-size simple refill (36行)
  ├─ SuperSlab adoption (163行)
  └─ Fresh allocation (70行)

hak_tiny_free (135行, 8.3%)  ← ENTRY POINT - CC 12
  ├─ Mode selection (BENCH, ULTRA, NORMAL)
  └─ Class resolution & dispatch

Other (127行, 7.7%)
  ├─ Helper functions (65行) - drain, remote guard
  ├─ SuperSlab alloc helpers (84行)
  └─ Shutdown (30行)

---

関数リスト（重要度順）

🔴 CRITICAL (テスト困難、複雑)

1. hak_tiny_free_with_slab() (558行)

   • 複雑度: CC 28 ← NEEDS REFACTORING
   • 責務: Free path の main router
   • 課題: Magazine/SLL/Publisher が混在

2. superslab_refill() (308行)

   • 複雑度: CC 18
   • 責務: SuperSlab adoption & allocation
   • 最適化: P0 で O(n) → O(1) 化予定

3. hak_tiny_free_superslab() (305行)

   • 複雑度: CC 16
   • 責務: SuperSlab free (same/remote)
   • 課題: Remote queue sentinel validation が複雑

🟡 HIGH (重要だが理解可能)

4. superslab_alloc_from_slab() (84行)

   • 複雑度: CC 4
   • 責務: Single slab block allocation

5. hak_tiny_alloc_superslab() (151行)

   • 複雑度: CC ~8
   • 責務: SuperSlab-based allocation entry

6. hak_tiny_free() (135行)

   • 複雑度: CC 12
   • 責務: Global free entry point (routing only)

🟢 LOW (シンプル)

7. tiny_drain_to_sll_budget() (10行) - ENV config
8. tiny_drain_freelist_to_sll_once() (16行) - SLL splicing
9. tiny_remote_queue_contains_guard() (21行) - Duplicate detection
10. hak_tiny_shutdown() (30行) - Cleanup

---

主要な複雑性源

1. hak_tiny_free_with_slab() の複雑度 (CC 28)

if (!slab) {
    // SuperSlab path (64行)
    // ├─ SuperSlab lookup
    // ├─ Validation (HAKMEM_SAFE_FREE)
    // └─ if remote → hak_tiny_free_superslab()
}
// 複数の TLS キャッシュパス (72行)
// ├─ Fast path (g_fast_enable)
// ├─ TLS List (g_tls_list_enable)
// ├─ HotMag (g_hotmag_enable)
// └─ ...
// Magazine/SLL/Publisher paths (413行)
// ├─ TinyQuickSlot?
// ├─ TLS SLL?
// ├─ Magazine?
// ├─ Background spill?
// ├─ SuperRegistry spill?
// └─ Publisher fallback?

課題: Policy cascade (複数パスの判定フロー)が線形に追加されている

2. superslab_refill() の複雑度 (CC 18)

┌─ Mid-size simple refill (class >= 4)?
├─ SuperSlab adoption?
│  ├─ Cool-down check
│  ├─ First-fit or Best-fit scoring
│  ├─ Slab acquisition
│  └─ Binding
└─ Fresh allocation
   ├─ SuperSlab allocate
   └─ Refcount management

課題: Adoption vs allocation decision が複雑 (Future P0 optimization target)

3. hak_tiny_free_superslab() の複雑度 (CC 16)

├─ Validation (bounds, magic, size_class)
├─ if (same-thread)
│  ├─ Direct freelist push
│  ├─ remote guard check
│  └─ MidTC integration
└─ else (remote)
   ├─ Remote queue enqueue
   ├─ Sentinel validation
   └─ Bulk refill coordination

課題: Same vs remote path が大きく分岐

---

分割提案（優先度順）

Phase 1: Magazine/SLL を分離 (413行)

新ファイル: tiny_free_magazine.inc.h

メリット:

• Policy cascade を独立ファイルに隔離
• Magazine は environment-based (on/off可能)
• テスト時に mock 可能
• スパイル改善時の影響を限定

Before: hak_tiny_free_with_slab() CC 28 → 413行
After:  hak_tiny_free_with_slab() CC ~8
        + tiny_free_magazine.inc.h CC ~10

---

Phase 2: SuperSlab allocation を分離 (394行)

新ファイル: tiny_superslab_alloc.inc.h

含める関数:

• superslab_refill() (308行)
• superslab_alloc_from_slab() (84行)
• hak_tiny_alloc_superslab() (151行)
• Adoption helpers

メリット:

• Allocation は free と直交
• P0 optimization (O(n)→O(1)) に集中
• Registry logic を明確化

---

Phase 3: SuperSlab free を分離 (305行)

新ファイル: tiny_superslab_free.inc.h

含める関数:

• hak_tiny_free_superslab() (305行)
• Remote queue management
• Sentinel validation

メリット:

• Remote queue logic は pure
• Cross-thread free を focused に
• Debugging (ROUTE_MARK) が簡単

---

分割後の構成

Current (1ファイル)

hakmem_tiny_free.inc (1,711行)
├─ Helpers & includes
├─ hak_tiny_free_with_slab (558行) ← MONOLITH
├─ SuperSlab alloc/refill (394行)
├─ SuperSlab free (305行)
├─ Main entry (135行)
└─ Shutdown (30行)

After refactoring (4ファイル)

hakmem_tiny_free.inc (450行) ← THIN ROUTER
├─ Helpers & includes
├─ hak_tiny_free (dispatch only)
├─ hak_tiny_shutdown
└─ #include directives (3個)

tiny_free_magazine.inc.h (400行)
├─ TinyQuickSlot
├─ TLS SLL push
├─ Magazine push/spill
├─ Background spill
└─ Publisher fallback

tiny_superslab_alloc.inc.h (380行) ← P0 OPTIMIZATION HERE
├─ superslab_refill (with nonempty_mask O(n)→O(1))
├─ superslab_alloc_from_slab
└─ hak_tiny_alloc_superslab

tiny_superslab_free.inc.h (290行)
├─ hak_tiny_free_superslab
├─ Remote queue management
└─ Sentinel validation

---

実装手順

Step 1: バックアップ

cp core/hakmem_tiny_free.inc core/hakmem_tiny_free.inc.bak

Step 2-4: 3ファイルに分割

Lines 208-620  → core/tiny_free_magazine.inc.h
Lines 626-1019 → core/tiny_superslab_alloc.inc.h
Lines 1171-1475 → core/tiny_superslab_free.inc.h

Step 5: Makefile update

hakmem_tiny_free.inc は #include で 3ファイルを参照
→ dependency に追加

Step 6: 検証

make clean && make
./larson_hakmem 2 8 128 1024 1 12345 4
# スコア変化なし を確認

---

分割前後の改善指標

指標	Before	After	改善
ファイル数	1	4	+300% (関心分離)
avg CC	14.4	8.2	-43%
max CC	28	16	-43%
max func size	558行	308行	-45%
理解難易度	★★★★☆	★★★☆☆	-1段階
テスト容易性	★★☆☆☆	★★★★☆	+2段階

---

関連最適化

P0 Optimization (Already in CLAUDE.md)

• File: tiny_superslab_alloc.inc.h (after split)
• Location: superslab_refill() lines ~785-947
• Optimization: O(n) linear scan → O(1) ctz using nonempty_mask
• Expected: CPU 29.47% → 25.89% (-12%)

P1 Opportunities (After split)

1. Magazine policy tuning (dedicated file で容易)
2. SLL fast path 最適化 (isolation で実験容易)
3. Publisher fallback 削減 (cache hit rate 改善)

---

ドキュメント参照

• Full Analysis: /mnt/workdisk/public_share/hakmem/STRUCTURAL_ANALYSIS.md
• Related: CLAUDE.md (Phase 6-2.1 P0 optimization)
• History: HISTORY.md (Past refactoring lessons)

---

実施推奨度

★★★★★ STRONGLY RECOMMENDED

理由:

1. hak_tiny_free_with_slab の CC 28 は危険域
2. Magazine/SLL paths は独立policy (隔離が自然)
3. P0 optimization が superslab_refill に focused
4. テスト時の mock 可能性が大幅向上
5. Future maintenance が容易に