# SACS: Site-Aware Adaptive Cache System - 全体アーキテクチャ

**System Name**: SACS (Site-Aware Adaptive Cache System)
**Pronunciation**: サックス（サクサク動く！）
**Date**: 2025-10-21
**Phases**: 6.9 → 6.10 → 6.11 → 6.12
**発案者**: tomoaki（ユーザー）
**詳細設計**: ChatGPT Pro + Claude

---

## 🎯 **SACS とは**

### **定義**

Call-site profiling + ELO learning による **3層適応キャッシュシステム**

### **コンポーネント**

```
L1 TinySlab (Phase 6.12+):
  - サイズ範囲: 16B ～ 1KB
  - 8クラス（16/32/64/128/256/512/768/1024B）
  - TLS（スレッドローカル）でロックフリー
  - KEEP policy 固定（madvise なし）

L2 MidPool (Phase 6.9):
  - サイズ範囲: 2KB ～ 32KB
  - 5クラス（2/4/8/16/32KB）
  - 64 shards（site-based）
  - 64KB pages

L3 BigCache (Phase 6.4-6.8):
  - サイズ範囲: 1MB ～ 32MB
  - 10 size classes
  - W_MAX で上位クラス流用
  - Hot/Warm/Cold policy
```

### **最適化層**

```
Site Rules (Phase 6.10):
  - (call-site address, size_class) → route/policy/shard
  - O(1) 4-probe hash table
  - Top-K learning（上位 100 site のみ保持）
  - TTL 自然蒸発（30分）

Dynamic Thresholds (Phase 6.11):
  - W_MAX: {1.25, 1.5, 1.75}（浪費率上限）
  - hot_ms/warm_ms: {50/100/200, 600/900/1200}（Hot/Warm 境界）
  - BATCH_RANGE: {(64K,2M), (128K,4M), (256K,8M)}（batch 対象範囲）
  - ε-greedy 探索（ε=0.1）
  - CANARY 窓で採択（30-60秒）

ELO Selection (Phase 6.4-6.8):
  - 12 strategies（512KB ～ 32MB threshold）
  - Softmax selection based on ELO ratings
  - 戦略選択・レーティング更新
```

---

## 🏗️ **アーキテクチャ図**

### **割り当てフロー**

```
[Allocation Request] (size, site_id)
        ↓
    ┌───────────────────────┐
    │ Step 0: 例外早抜け    │  size >= 32MB → system mmap
    └───────────────────────┘
        ↓
    ┌───────────────────────┐
    │ Step 1: Site Rules    │  lookup_site_rule(site, class)
    │   (O(1) 4-probe)      │  → hit: route/policy/shard 即決
    └───────────────────────┘
        ↓ miss
    ┌───────────────────────┐
    │ Step 2: クラス既定    │  Dynamic Thresholds 適用
    │   (FrozenPolicy)      │  - W_MAX で上位クラス流用
    └───────────────────────┘  - hot/warm で policy 決定
        ↓
    ┌───────────────────────┐
    │ Step 3: ルーティング  │
    │  - L1 TinySlab        │  ≤ 1KB かつ TLS
    │  - L2 MidPool         │  2-32KB かつ pool[class]=on
    │  - L3 BigCache        │  1-32MB
    │  - system mmap        │  >= 32MB
    └───────────────────────┘
```

### **優先順位**

```
Site Rule ＞ クラス既定（FrozenPolicy）＞ 最終フォールバック
    ↑              ↑                        ↑
  Phase 6.10    Phase 6.11              Phase 6.4-6.8
```

---

## 📊 **Phase 別の進化**

### **Phase 6.4-6.8: ELO 基盤**

**実装内容**:
- BigCache（1-32MB の 10 クラス）
- ELO 学習（12 strategies）
- Batch madvise（2MB threshold）
- Hot/Warm/Cold policy

**成果**:
- VM scenario: +1.9% vs mimalloc（Phase 6.4）
- BigCache hit rate: 99.9%
- mmap 使用で batch madvise 発動

**問題点**:
- 中粒（2-32KB）の最適化不足
- mixed scenario: +66% vs mimalloc
- mir scenario: +52% vs mimalloc

---

### **Phase 6.9: L2 MidPool 基盤**

**実装内容**:
- 5クラス（2/4/8/16/32KB）
- 64 shards（site-based）
- 64KB pages
- 単純フリーリスト

**成果**:
- L2 Pool 実装完了
- 基盤構築

**問題点**:
- Pool hit 率 0%（Site Rules なし）
- 既存ベンチマークが Pool 範囲外（64KB/256KB/2MB）

---

### **Phase 6.9.1: Pool Header Integration**

**実装内容**:
- AllocHeader 追加（magic/method/size/alloc_site/class_bytes）
- ALLOC_METHOD_POOL enum 追加
- hakmem_pool.c リファクタリング
- 検証強化（magic/method チェック）

**成果**:
- SEGFAULT 防止
- malloc/mmap/pool 統一管理
- Build & Test 成功

**問題点**:
- memset(user_ptr, 0, class_size) が遅い（~200-400 ns）
- Site Rules なし（Pool hit 率 0% のまま）

---

### **Phase 6.10: Site Rules**（設計完了、実装待機）

**実装内容**:
- SiteRule 構造体（16B × 2048 = 32KB）
- O(1) 4-probe hash table
- Top-K learning（上位 100 site のみ）
- TTL 自然蒸発（30分）
- Adoption Gate（勝率 < 60% 不採用）

**期待される効果**:
- L2 Pool hit 率: 0% → 40%
- minor faults: -30%
- madvise calls: -50%

**ChatGPT 推奨の最適化**:
- non-empty ビットマップ（O(1) 空クラススキップ）
- branchless クラス決定（LUT化）
- memset 禁止（デバッグモードのみ）

---

### **Phase 6.11: Dynamic Thresholds**（設計完了、実装待機）

**実装内容**:
- W_MAX learning（3候補: 1.25/1.5/1.75）
- Hot/Warm/Cold 境界 learning（各3候補）
- BATCH_RANGE learning（3範囲）
- ε-greedy 探索（ε=0.1）
- CANARY 窓（30-60秒）
- Hysteresis（±1 step 制限）

**期待される効果**:
- L2 Pool hit 率: +20%（W_MAX 最適化）
- minor faults: -40%（hot/warm 境界最適化）
- madvise calls: -30%（BATCH_RANGE 最適化）

**オーバーヘッド**:
- FROZEN 時: ゼロ
- CANARY 窓: < 1ms（無視できる）

---

### **Phase 6.12: L1 TinySlab**（将来計画）

**実装内容**:
- 8クラス（16/32/64/128/256/512/768/1024B）
- TLS（スレッドローカル）
- KEEP policy 固定
- non-empty ビットマップ

**期待される効果**:
- 小サイズ（≤1KB）で 30-50% 高速化
- TLS でロック削減
- madvise なしで syscall 削減

---

## 🎯 **成功判定メトリクス**

### **Phase 6.10（Site Rules）目標**

| Metric | Target | Baseline (Phase 6.9.1) |
|--------|--------|------------------------|
| rule_hit_rate | > 40% | 0% |
| pool_mid_hit_rate | > 40% | 0% |
| minor_faults/sec | -30% | Phase 6.8 |
| madvise_calls/sec | -50% | Phase 6.8 |
| p99 (mixed) | < +20% | mimalloc |
| p99 (mir) | < +30% | mimalloc |

### **Phase 6.11（Dynamic Thresholds）目標**

| Metric | Target | Baseline (Phase 6.10) |
|--------|--------|----------------------|
| pool_mid_hit_rate | +20% | Phase 6.10 |
| minor_faults/sec | -40% | Phase 6.10 |
| madvise_calls/sec | -30% | Phase 6.10 |
| internal_waste (avg) | ≤ W_MAX | - |
| p99 (mixed) | < +15% | mimalloc |
| p99 (mir) | < +25% | mimalloc |

### **Phase 6.12（L1 TinySlab）目標**

| Metric | Target | Baseline (Phase 6.11) |
|--------|--------|----------------------|
| p99 (≤1KB allocs) | 30-50% faster | Phase 6.11 |
| TLS lock contention | ゼロ | Phase 6.11 |
| madvise_calls/sec | -10% | Phase 6.11 |

---

## 🎓 **論文への貢献**

### **論文タイトル案**

**"SACS: Site-Aware Adaptive Cache System with ELO-driven Dynamic Optimization"**

### **核心メッセージ: 職人芸 vs 自己進化最適化**

**Microsoft Research mimalloc の挑戦**:
- 固定・静的な職人芸（手動チューニング）
- 経験的パラメータのハードコード
- 環境変数での手動調整

**SACS/ELO の革新**:
- 自己進化・自動最適化
- ELO 一発で mimalloc の複雑な手動チューニングを自動化
- 使いながら最適解に進化する自動職人

---

## 🆚 **mimalloc vs SACS 比較**（ChatGPT Pro 分析）

| 領域 | mimalloc の方式 | SACS/ELO の方式 |
|------|----------------|-----------------|
| **サイズクラス分割** | 固定・静的（16/32/64/128…ハードコード） | 固定基準 + **ELOで人気クラスを厚めに動的配分** |
| **pool/thread-cache** | per-thread 固定構造 | 同等構造 + **ELOがsiteと頻度でshard分配最適化** |
| **madvise/FREE 制御** | 経験的チューニング + 環境変数 | **Hot/Warm/Cold + BATCH_RANGE学習**で自動制御 |
| **reuse/free ポリシー** | 静的（即reuse or free） | **ELOが再利用間隔でHot/Warm/Coldを進化的調整** |
| **大割当境界** | 固定閾値（例: 1MB） | **ELOで W_MAX と cutover を軽量探索** |
| **チューニング** | 手動 + 環境変数 | **自己学習（CANARY→FROZEN）**で常時ゼロコスト |

**結論**:
> mimalloc が「固定の最適解をハードコードした職人芸」なら、
> SACS/ELO は「使いながら最適解に進化する自動職人」。
> ELO 一発で Microsoft Research の"人手最適化"を自動化！

---

### **構造比較（概念図）**

```
mimalloc (Microsoft Research):
  ├─ small page (arena) - 固定サイズクラス
  ├─ page manager - 静的tcache
  └─ OS interface (mmap, madvise) - 経験的チューニング

SACS (ELO-driven):
  ├─ L1 TinySlab  (≤1KiB) - TLS最適化
  ├─ L2 MidPool   (2–32KiB, 5 classes, ELO配分)
  ├─ L3 BigCache  (1–32MB, batch+ELO)
  ├─ Site Rules   ((site,class)->route/policy/shard)
  └─ ELO Engine   (学習・閾値進化・凍結) ← ★核心
```

---

### **新規性**

1. **アドレス直結キャッシュの自動最適化**
   - 既存研究: サイズクラスのみ（tcmalloc/jemalloc/mimalloc）
   - SACS: call-site × size_class の 2D 最適化

2. **ELO による Site Rules 自動生成**
   - 手動チューニング不要
   - Top-K のみ保持で軽量（32KB）
   - TTL + Adoption Gate で安定性保証

3. **動的閾値学習**
   - W_MAX/hot_ms/warm_ms を自動学習
   - ε-greedy + CANARY 窓
   - FROZEN 時のオーバーヘッドゼロ

4. **3層合成アーキテクチャ**
   - Site Rule（局所最適）+ FrozenPolicy（全体最適）
   - L1/L2/L3 階層でサイズ全域カバー
   - フォールバックで安全性保証

5. **Microsoft Research vs 自己進化**（★論文の核心）
   - mimalloc の固定職人芸を ELO で自動化
   - 環境変数チューニング不要
   - ワークロード変化に自動適応

### **要旨**

```
Call-site profiling（Phase 6.0-6.9）の次のステップとして、
(site, class) → cache route の直接結びつけ（Site Rules）と、
ELO による動的閾値学習を実現。

32KB のオーバーヘッドで 40% の中粒性能改善、
FROZEN 時の実行オーバーヘッドはゼロ。

mimalloc/jemalloc の固定サイズクラスを超える、
自動適応型 3層キャッシュシステム（SACS）を提案。
```

---

## 🚀 **実装ロードマップ**

### **Phase 6.10.1: Site Rules MVP**（4週間）

**Week 1-2**:
- SiteRule 構造体実装（hakmem_site_rules.h/c）
- lookup_site_rule() 実装（O(1) 4-probe）
- non-empty ビットマップ追加

**Week 3**:
- hak_alloc_at() 統合（Site Rules ルート）
- branchless クラス決定（LUT化）
- memset 削除（デバッグモードのみ）

**Week 4**:
- 手動ルール設定（Top-10 site）
- ベンチマーク（mixed/mir で効果測定）
- 成功判定

---

### **Phase 6.10.2: ELO 学習自動化**（3週間）

**Week 1**:
- 各 (site, class) の使用頻度・再利用間隔記録

**Week 2**:
- Top-K（上位 100 site）のみ Site Rule 作成
- 勝率 > 60% で FROZEN へ

**Week 3**:
- ベンチマーク
- チューニング

---

### **Phase 6.10.3: TTL/Adoption Gate**（2週間）

**Week 1**:
- TTL（30分）で自然蒸発
- Adoption Gate（勝率 < 60% 不採用）

**Week 2**:
- 予算整合性チェック
- 安定性テスト

---

### **Phase 6.11.1: W_MAX 学習**（3週間）

**Week 1-2**:
- W_MAX 候補（1.25/1.5/1.75）
- ε-greedy 探索
- CANARY 窓実装

**Week 3**:
- ベンチマーク
- 効果測定

---

### **Phase 6.11.2: Hot/Warm/Cold 境界**（3週間）

同様の流れ

---

### **Phase 6.11.3: BATCH_RANGE**（2週間）

同様の流れ

---

### **Phase 6.12: L1 TinySlab**（4週間）

Phase 6.10/6.11 完了後に実施

---

## 📚 **関連ドキュメント**

- **Phase 6.10 詳細**: [PHASE_6.10_SITE_RULES.md](PHASE_6.10_SITE_RULES.md)
- **Phase 6.11 詳細**: [PHASE_6.11_DYNAMIC_THRESHOLDS.md](PHASE_6.11_DYNAMIC_THRESHOLDS.md)
- **Phase 6.9.1 実装**: [PHASE_6.9.1_POOL_HEADER_INTEGRATION.md](PHASE_6.9.1_POOL_HEADER_INTEGRATION.md)（未作成）
- **Phase 6.8 分析**: [PHASE_6.8_REGRESSION_ANALYSIS.md](PHASE_6.8_REGRESSION_ANALYSIS.md)

---

## 🎯 **核心メッセージ**

**tomoaki の洞察**:
1. 「アドレスその物を ELO だけどどう？」→ Site Rules
2. 「キャッシュの固定値その物を学習して動かせばいいんじゃにゃい？」→ Dynamic Thresholds
3. 「1KB以下は専用のシンプルなキャッシュプール」→ L1 TinySlab

**ChatGPT の詳細化**:
- Site Rules: O(1) 4-probe + Top-K + TTL
- Dynamic Thresholds: 3候補 + ε-greedy + CANARY
- 最適化: non-empty bitmap + branchless + memset禁止

**結果**: SACS（サックス）- サクサク動く適応型メモリアロケータ！

---

**Generated**: 2025-10-21
**発案者**: tomoaki（ユーザー）
**詳細設計**: ChatGPT Pro + Claude
**System Name**: SACS (Site-Aware Adaptive Cache System)