hakmem/docs/analysis/SFC_ROOT_CAUSE_ANALYSIS.md

SFC (Super Front Cache) 動作不許容原因 - 詳細分析報告書

Executive Summary

SFC が動作しない根本原因は「refill ロジックの未実装」です。

• 症状: SFC_ENABLE=1 でも性能が 4.19M → 4.19M で変わらない
• 根本原因: malloc() path で SFC キャッシュを refill していない
• 影響: SFC が常に空のため、すべてのリクエストが fallback path に流れる
• 修正予定工数: 4-6時間

---

1. 調査内容と検証結果

1.1 malloc() SFC Path の実行流 (core/hakmem.c Line 1301-1315)

コード：

if (__builtin_expect(g_sfc_enabled && g_initialized && size <= TINY_FAST_THRESHOLD, 1)) {
    // Step 1: size-to-class mapping
    int cls = hak_tiny_size_to_class(size);
    if (__builtin_expect(cls >= 0, 1)) {
        // Step 2: Pop from cache
        void* ptr = sfc_alloc(cls);
        if (__builtin_expect(ptr != NULL, 1)) {
            return ptr;  // SFC HIT
        }
        
        // Step 3: SFC MISS
        // コメント: "Fall through to Box 5-OLD (no refill to avoid infinite recursion)"
        // ⚠️ **ここが問題**: refill がない
    }
}

// Step 4: Fallback to Box Refactor (HAKMEM_TINY_PHASE6_BOX_REFACTOR)
#ifdef HAKMEM_TINY_PHASE6_BOX_REFACTOR
if (__builtin_expect(g_initialized && size <= TINY_FAST_THRESHOLD, 1)) {
    int cls = hak_tiny_size_to_class(size);
    void* head = g_tls_sll_head[cls];  // ← 旧キャッシュ (SFC ではない)
    if (__builtin_expect(head != NULL, 1)) {
        g_tls_sll_head[cls] = *(void**)head;
        return head;
    }
    void* ptr = hak_tiny_alloc_fast_wrapper(size);  // ← refill はここで呼ばれる
    if (__builtin_expect(ptr != NULL, 1)) {
        return ptr;
    }
}
#endif

分析：

• ✅ Step 1-2: hak_tiny_size_to_class(), sfc_alloc() は正しく実装されている
• ✅ Step 2: sfc_alloc() の計算ロジックは正常 (inline pop は 3-4 instruction)
• ⚠️ Step 3: SFC MISS 時に refill を呼ばない
• ❌ Step 4: 全てのリクエストが Box Refactor fallback に流れる

1.2 SFC キャッシュの初期値と補充

根本原因を追跡：

sfc_alloc() 実装 (core/tiny_alloc_fast_sfc.inc.h Line 75-95):

static inline void* sfc_alloc(int cls) {
    void* head = g_sfc_head[cls];  // ← TLS変数（初期値 NULL）
    
    if (__builtin_expect(head != NULL, 1)) {
        g_sfc_head[cls] = *(void**)head;
        g_sfc_count[cls]--;
        #if HAKMEM_DEBUG_COUNTERS
            g_sfc_stats[cls].alloc_hits++;
        #endif
        return head;
    }
    
    #if HAKMEM_DEBUG_COUNTERS
        g_sfc_stats[cls].alloc_misses++;  // ← **常にここに到達**
    #endif
    return NULL;  // ← **ほぼ 100% の確率で NULL**
}

問題：

• g_sfc_head[cls] は TLS 変数で、初期値は NULL
• malloc() 側で refill しないので、常に NULL のまま
• 結果：alloc_hits = 0%, alloc_misses = 100%

1.3 SFC refill スタブ関数の実態

sfc_refill() 実装 (core/hakmem_tiny_sfc.c Line 149-158):

int sfc_refill(int cls, int target_count) {
    if (cls < 0 || cls >= TINY_NUM_CLASSES) return 0;
    if (!g_sfc_enabled) return 0;
    (void)target_count;

    #if HAKMEM_DEBUG_COUNTERS
        g_sfc_stats[cls].refill_calls++;
    #endif

    return 0;  // ← **固定値 0**
    // コメント: "Actual refill happens inline in hakmem.c"
    // ❌ **嘘**: hakmem.c に実装がない
}

問題：

• 戻り値が常に 0
• hakmem.c の malloc() path から呼ばれていない
• コメントは意図の説明だが、実装がない

1.4 DEBUG_COUNTERS がコンパイルされるか？

テスト実行：

$ make clean && make larson_hakmem EXTRA_CFLAGS="-DHAKMEM_DEBUG_COUNTERS=1"
$ HAKMEM_SFC_ENABLE=1 HAKMEM_SFC_DEBUG=1 HAKMEM_SFC_STATS_DUMP=1 \
  timeout 10 ./larson_hakmem 2 8 128 1024 1 12345 4 2>&1 | tail -50

結果：

[SFC] Initialized: enabled=1, default_cap=128, default_refill=64
[ELO] Initialized 12 strategies ...
[Batch] Initialized ...
[DEBUG] superslab_refill NULL detail: ... (OOM エラーで途中終了)

結論：

• ✅ DEBUG_COUNTERS は正しくコンパイルされている
• ✅ sfc_init() は正常に実行されている
• ⚠️ メモリ不足で途中終了（別の問題か）
• ❌ SFC 統計情報は出力されない

1.5 free() path の動作

free() SFC path (core/hakmem.c Line 911-941):

TinySlab* tiny_slab = hak_tiny_owner_slab(ptr);
if (tiny_slab) {
    if (__builtin_expect(g_sfc_enabled, 1)) {
        pthread_t self_pt = pthread_self();
        if (__builtin_expect(pthread_equal(tiny_slab->owner_tid, self_pt), 1)) {
            int cls = tiny_slab->class_idx;
            if (__builtin_expect(cls >= 0 && cls < TINY_NUM_CLASSES, 1)) {
                int pushed = sfc_free_push(cls, ptr);
                if (__builtin_expect(pushed, 1)) {
                    return;  // ✅ Push成功（g_sfc_head[cls] に追加）
                }
                // ... spill logic
            }
        }
    }
}

分析：

• ✅ free() は正しく sfc_free_push() を呼ぶ
• ✅ sfc_free_push() は g_sfc_head[cls] にノードを追加する
• ❌ しかし malloc() が g_sfc_head[cls] を読まない
• 結果：free() で追加されたノードは使われない

1.6 Fallback Path (Box Refactor) が全リクエストを処理

実行フロー：

1. malloc() → SFC path
   - sfc_alloc() → NULL (キャッシュ空)
   - → fall through (refill なし)

2. malloc() → Box Refactor path (FALLBACK)
   - g_tls_sll_head[cls] をチェック
   - miss → hak_tiny_alloc_fast_wrapper() → refill → superslab_refill
   - **この経路が 100% のリクエストを処理している**

3. free() → SFC path
   - sfc_free_push() → g_sfc_head[cls] に追加
   - しかし malloc() が g_sfc_head を読まないので無意味

結論: SFC は「存在しないキャッシュ」状態

---

2. 検証結果：サイズ境界値は問題ではない

2.1 TINY_FAST_THRESHOLD の確認

定義 (core/tiny_fastcache.h Line 27):

#define TINY_FAST_THRESHOLD 128

Larson テストのサイズ範囲：

• デフォルト: min_size=10, max_size=500
• テスト実行: ./larson_hakmem 2 8 128 1024 1 12345 4
  • min_size=8, max_size=128 ✅

結論: ほとんどのリクエストが 128B 以下 → SFC 対象

2.2 hak_tiny_size_to_class() の動作

実装 (core/hakmem_tiny.h Line 244-247):

static inline int hak_tiny_size_to_class(size_t size) {
    if (size == 0 || size > TINY_MAX_SIZE) return -1;
    return g_size_to_class_lut_1k[size];  // LUT lookup
}

検証：

• size=1 → class=0
• size=8 → class=0
• size=128 → class=10
• ✅ すべて >= 0 (有効なクラス)

結論: クラス計算は正常

---

3. 性能データ：SFC の効果なし

3.1 実測値

テスト条件: larson_hakmem 2 8 128 1024 1 12345 4
           (min_size=8, max_size=128, threads=4, duration=2sec)

結果:
├─ SFC_ENABLE=0 (デフォルト):  4.19M ops/s  ← Box Refactor
├─ SFC_ENABLE=1:  4.19M ops/s  ← SFC + Box Refactor
└─ 差分: 0% (全く同じ)

3.2 理由の分析

性能が変わらない理由:

1. SFC alloc() が 100% NULL を返す
   → g_sfc_head[cls] が常に NULL

2. malloc() が fallback (Box Refactor) に流れる
   → SFC ではなく g_tls_sll_head から pop

3. SFC は「実装されているが使われていないコード」
   → dead code 状態

---

4. 根本原因の特定

最有力候補：SFC refill ロジックが実装されていない

証拠チェックリスト：

#	項目	状態	根拠
1	sfc_alloc() の inline pop	✅ OK	tiny_alloc_fast_sfc.inc.h: 3-4命令
2	sfc_free_push() の実装	✅ OK	hakmem.c line 919: g_sfc_head に push
3	sfc_init() 初期化	✅ OK	ログ出力: enabled=1, cap=128
4	size <= 128B フィルタ	✅ OK	hak_tiny_size_to_class(): class >= 0
5	SFC refill ロジック	❌ なし	hakmem.c line 1301-1315: fall through (refill呼ばない)
6	sfc_refill() 関数呼び出し	❌ なし	malloc() path から呼ばれていない
7	refill batch処理	❌ なし	Magazine/SuperSlab から補充ロジックなし

根本原因の詳細：

// hakmem.c Line 1301-1315
if (g_sfc_enabled && g_initialized && size <= TINY_FAST_THRESHOLD) {
    int cls = hak_tiny_size_to_class(size);
    if (cls >= 0) {
        void* ptr = sfc_alloc(cls);  // ← sfc_alloc() は NULL を返す
        if (ptr != NULL) {
            return ptr;  // ← この分岐に到達しない
        }
        
        // ⚠️ ここから下がない：refill ロジック欠落
        // コメント: "SFC MISS: Fall through to Box 5-OLD"
        // 問題: fall through する = 何もしない = cache が永遠に空
    }
}

// その後、Box Refactor fallback に全てのリクエストが流れる
// → SFC は事実上「無効」

---

5. 設計上の問題点

5.1 Box Theory の過度な解釈

設計意図（コメント）：

"Box 5-NEW never calls lower boxes on alloc"
"This maintains clean Box boundaries"

実装結果：

• refill を呼ばない
• → キャッシュが永遠に空
• → SFC は never hits

問題：

• 無限再帰を避けるなら、refill深度カウントで制限すべき
• 「全く refill しない」は過度に保守的

5.2 スタブ関数による実装遅延

sfc_refill() の実装状況：

int sfc_refill(int cls, int target_count) {
    ...
    return 0;  // ← Fixed zero
}
// コメント: "Actual refill happens inline in hakmem.c"
// しかし hakmem.c に実装がない

問題：

• コメントだけで実装なし
• スタブ関数が fixed zero を返す
• 呼ばれていない

5.3 テスト不足

テストの盲点：

• SFC_ENABLE=1 でも性能が変わらない
• → SFC が動作していないことに気づかなかった
• 本来なら性能低下 (fallback cost) か性能向上 (SFC hit) かのどちらか

---

6. 詳細な修正方法

Phase 1: SFC refill ロジック実装 (推定4-6時間)

目標：

• SFC キャッシュを定期的に補充
• Magazine または SuperSlab から batch refill
• 無限再帰防止: refill_depth <= 1

実装案：

// core/hakmem.c - malloc() に追加
if (__builtin_expect(g_sfc_enabled && g_initialized && size <= TINY_FAST_THRESHOLD, 1)) {
    int cls = hak_tiny_size_to_class(size);
    if (__builtin_expect(cls >= 0, 1)) {
        // Try SFC fast path
        void* ptr = sfc_alloc(cls);
        if (__builtin_expect(ptr != NULL, 1)) {
            return ptr;  // SFC HIT
        }
        
        // SFC MISS: Refill from Magazine
        // ⚠️ **新しいロジック**:
        int refill_count = 32;  // batch size
        int refilled = sfc_refill_from_magazine(cls, refill_count);
        
        if (refilled > 0) {
            // Retry after refill
            ptr = sfc_alloc(cls);
            if (__builtin_expect(ptr != NULL, 1)) {
                return ptr;  // SFC HIT (after refill)
            }
        }
        
        // Refill failed or retried: fall through to Box Refactor
    }
}

実装ステップ：

1. Magazine refill ロジック

   • Magazine から free blocks を抽出
   • SFC キャッシュに追加
   • 実装場所: hakmem_tiny_magazine.c または hakmem.c

2. Cycle detection

   static __thread int sfc_refill_depth = 0;
   
   if (sfc_refill_depth > 1) {
       // Too deep, avoid infinite recursion
       goto fallback;
   }
   sfc_refill_depth++;
   // ... refill logic
   sfc_refill_depth--;
   

3. Batch size tuning

   • 初期値: 32 blocks per class
   • Environment variable で調整可能

Phase 2: A/B テストと検証 (推定2-3時間)

# SFC OFF
HAKMEM_SFC_ENABLE=0 ./larson_hakmem 2 8 128 1024 1 12345 4
# 期待: 4.19M ops/s (baseline)

# SFC ON
HAKMEM_SFC_ENABLE=1 ./larson_hakmem 2 8 128 1024 1 12345 4
# 期待: 4.6-4.8M ops/s (+10-15% improvement)

# Debug dump
HAKMEM_SFC_ENABLE=1 HAKMEM_SFC_STATS_DUMP=1 \
./larson_hakmem 2 8 128 1024 1 12345 4 2>&1 | grep "SFC Statistics" -A 20

期待される結果：

=== SFC Statistics (Box 5-NEW) ===
Class 0 (16 B): allocs=..., hit_rate=XX%, refills=..., cap=128
...
=== SFC Summary ===
Total allocs: ...
Overall hit rate: >90% (target)
Refill frequency: <0.1% (target)
Refill calls: ...

Phase 3: 自動チューニング (オプション、2-3日)

// Per-class hotness tracking
struct {
    uint64_t alloc_miss;
    uint64_t free_push;
    double miss_rate;  // miss / push
    int hotness;       // 0=cold, 1=warm, 2=hot
} sfc_class_info[TINY_NUM_CLASSES];

// Dynamic capacity adjustment
if (sfc_class_info[cls].hotness == 2) {  // hot
    increase_capacity(cls);  // 128 → 256
    increase_refill_count(cls);  // 64 → 96
}

---

7. リスク評価と推奨アクション

リスク分析

リスク	確度	影響	対策
Infinite recursion	中	crash	refill_depth counter
Performance regression	低	-5%	fallback path は生きている
Memory overhead	低	+KB	TLS cache 追加
Fragmentation increase	低	+%	magazine refill と相互作用

推奨アクション

優先度1（即実施）

• Phase 1: SFC refill 実装 (4-6h)
  • refill_from_magazine() 関数追加
  • cycle detection ロジック追加
  • hakmem.c の malloc() path 修正

優先度2（その次）

• Phase 2: A/B test (2-3h)
  • SFC_ENABLE=0 vs 1 性能比較
  • DEBUG_COUNTERS で統計確認
  • メモリオーバーヘッド測定

優先度3（将来）

• Phase 3: 自動チューニング (2-3d)
  • Hotness tracking
  • Per-class adaptive capacity

---

8. 付録：完全なコード追跡

malloc() Call Flow

malloc(size)
  ↓
[1] g_sfc_enabled && g_initialized && size <= 128?
  YES ↓
  [2] cls = hak_tiny_size_to_class(size)
    ✅ cls >= 0
    [3] ptr = sfc_alloc(cls)
      ❌ return NULL (g_sfc_head[cls] is NULL)
      [3-END] Fall through
  ❌ No refill!
  ↓
[4] #ifdef HAKMEM_TINY_PHASE6_BOX_REFACTOR
  YES ↓
  [5] cls = hak_tiny_size_to_class(size)
    ✅ cls >= 0
    [6] head = g_tls_sll_head[cls]
      ✅ YES (初期値あり)
      ✓ RETURN head
      OR
      ❌ NULL → hak_tiny_alloc_fast_wrapper()
         → Magazine/SuperSlab refill
  ↓
[RESULT] 100% of requests processed by Box Refactor

free() Call Flow

free(ptr)
  ↓
tiny_slab = hak_tiny_owner_slab(ptr)
  ✅ found
  ↓
[1] g_sfc_enabled?
  YES ↓
  [2] same_thread(tiny_slab->owner_tid)?
    YES ↓
    [3] cls = tiny_slab->class_idx
      ✅ valid (0 <= cls < TINY_NUM_CLASSES)
      [4] pushed = sfc_free_push(cls, ptr)
        ✅ Push to g_sfc_head[cls]
        [RETURN] ← **但し malloc() がこれを読まない**
        OR
        ❌ cache full → sfc_spill()
    NO → [5] Cross-thread path
  ↓
[RESULT] SFC に push されるが活用されない

---

結論

最終判定

SFC が動作しない根本原因: malloc() path に refill ロジックがない

症状と根拠：

1. ✅ SFC 初期化: sfc_init() は正常に実行
2. ✅ free() path: sfc_free_push() も正常に実装
3. ❌ malloc() refill: 実装されていない
4. ❌ sfc_alloc() が常に NULL を返す
5. ❌ 全リクエストが Box Refactor fallback に流れる
6. ❌ 性能: SFC_ENABLE=0/1 で全く同じ (0% improvement)

修正予定

Phase	作業	工数	期待値
1	refill ロジック実装	4-6h	SFC が動作開始
2	A/B test 検証	2-3h	+10-15% 確認
3	自動チューニング	2-3d	+15-20% 到達

今すぐできること

1. 応急処置: make larson_hakmem 時に -DHAKMEM_SFC_ENABLE=0 を固定
2. 詳細ログ: HAKMEM_SFC_DEBUG=1 で初期化確認
3. 実装開始: Phase 1 refill ロジック追加