hakmem/SOURCE_MAP.md

# hakmem ソースコードマップ

**最終更新**: 2025-11-01 (Mid Range MT 実装完了)

このガイドは、hakmem アロケータのソースコード構成を説明します。

**📢 最新情報**:
- ✅ **Mid Range MT 完了**: mimalloc風 per-thread allocator 実装（95-99 M ops/sec）
- ✅ **P0実装完了**: Tiny Pool リフィル最適化で +5.16% 改善
- 🎯 **ハイブリッド案**: 8-32KB (Mid MT) + 64KB以上 (学習ベース)
- 📋 **詳細**: `MID_MT_COMPLETION_REPORT.md`, `P0_SUCCESS_REPORT.md` 参照

---

## 📂 ディレクトリ構造概要

```
hakmem/
├── core/              # 🔥 メインソースコード (アロケータ実装)
├── docs/              # 📚 ドキュメント
│   ├── analysis/      # 性能分析、ボトルネック調査
│   ├── benchmarks/    # ベンチマーク結果
│   ├── design/        # 設計ドキュメント、アーキテクチャ
│   └── archive/       # 古いドキュメント、フェーズレポート
├── perf_data/         # 📊 perf プロファイリングデータ
├── scripts/           # 🔧 ベンチマーク実行スクリプト
├── bench_*.c          # 🧪 ベンチマークプログラム (ルート)
└── *.md               # 重要なプロジェクトドキュメント (ルート)
```

---

## 🔥 コアソースコード (`core/`)

### 主要アロケータ実装 (3つのメインプール)

#### 1. Tiny Pool (≤1KB) - 最も重要 ✅ P0最適化完了
**メインファイル**: `core/hakmem_tiny.c` (1,081行, Phase 2D後)
- 超小型オブジェクト用高速アロケータ
- 6-7層キャッシュ階層 (TLS Magazine, Mini-Mag, Bitmap Scan, etc.)
- **✅ P0最適化**: リフィルバッチ化で +5.16% 改善（`hakmem_tiny_refill_p0.inc.h`）
- **インクルードモジュール** (Phase 2D-4 で分離):
  - `hakmem_tiny_alloc.inc` - 高速アロケーション (ホットパス)
  - `hakmem_tiny_free.inc` - 高速フリー (ホットパス)
  - `hakmem_tiny_refill.inc.h` - Magazine/Slab リフィル
  - `hakmem_tiny_slab_mgmt.inc` - Slab ライフサイクル管理
  - `hakmem_tiny_init.inc` - 初期化・構成
  - `hakmem_tiny_lifecycle.inc` - スレッド終了処理
  - `hakmem_tiny_background.inc` - バックグラウンド処理
  - `hakmem_tiny_intel.inc` - 統計・デバッグ
  - `hakmem_tiny_fastcache.inc.h` - Fast Head (SLL)
  - `hakmem_tiny_hot_pop.inc.h` - Magazine pop (インライン)
  - `hakmem_tiny_hotmag.inc.h` - Hot Magazine (インライン)
  - `hakmem_tiny_ultra_front.inc.h` - Ultra Bump Shadow
  - `hakmem_tiny_remote.inc` - リモートフリー
  - `hakmem_tiny_slow.inc` - スロー・フォールバック

**補助モジュール**:
- `hakmem_tiny_magazine.c/.h` - TLS Magazine (2048 items)
- `hakmem_tiny_superslab.c/.h` - SuperSlab 管理
- `hakmem_tiny_tls_ops.h` - TLS 操作ヘルパー
- `hakmem_tiny_mini_mag.h` - Mini-Magazine (32-64 items)
- `hakmem_tiny_stats.c/.h` - 統計収集
- `hakmem_tiny_bg_spill.c/.h` - バックグラウンド Spill
- `hakmem_tiny_remote_target.c/.h` - リモートフリー処理
- `hakmem_tiny_registry.c` - レジストリ (O(1) Slab 検索)
- `hakmem_tiny_query.c` - クエリ API

#### 2. Mid Range MT Pool (8-32KB) - 中型アロケーション ✅ 実装完了
**メインファイル**: `core/hakmem_mid_mt.c/.h` (533行 + 276行)
- mimalloc風 per-thread segment アロケータ
- 3サイズクラス (8KB, 16KB, 32KB)
- 4MB chunks（mimalloc 同様）
- TLS lock-free allocation
- **✅ 性能達成**: 95-99 M ops/sec（目標100-120Mの80-96%）
- **vs System**: 1.87倍高速
- **詳細**: `MID_MT_COMPLETION_REPORT.md`, `docs/design/MID_RANGE_MT_DESIGN.md`
- **ベンチマーク**: `scripts/run_mid_mt_bench.sh`, `scripts/MID_MT_BENCH_README.md`

**旧実装（アーカイブ）**: `core/hakmem_pool.c` (2,486行)
- 4層構造 (TLS Ring, TLS Active Pages, Global Freelist, Page Allocation)
- MT性能で mimalloc の 38%（-62%）← Mid MT で解決済み

#### 3. L2.5 Pool (64KB-1MB) - 超大型アロケーション
**メインファイル**: `core/hakmem_l25_pool.c` (1,195行)
- 超大型オブジェクト用アロケータ
- **設定**: `POOL_L25_RING_CAP=16`

---

### 学習層・適応層（ハイブリッド案での位置づけ）

hakmem の独自機能 (mimalloc にはない):

- `hakmem_ace.c/.h` - ACE (Adaptive Cache Engine)
- `hakmem_elo.c/.h` - ELO レーティングシステム (12戦略)
- `hakmem_ucb1.c` - UCB1 Multi-Armed Bandit
- `hakmem_learner.c/.h` - 学習エンジン
- `hakmem_evo.c/.h` - 進化的アルゴリズム
- `hakmem_policy.c/.h` - ポリシー管理

**🎯 ハイブリッド案での役割**:
- **≤1KB (Tiny)**: 学習不要（P0で静的最適化完了）
- **8-32KB (Mid)**: mimalloc風に移行（学習層バイパス）
- **≥64KB (Large)**: 学習層が主役（ELO戦略選択が効果的）

→ 学習層は Large Pool（64KB以上）に集中、MT性能と学習を両立

---

### コア機能・ヘルパー

- `hakmem.c/.h` - メインエントリーポイント (malloc/free/realloc API)
- `hakmem_config.c/.h` - 環境変数設定
- `hakmem_internal.h` - 内部共通定義
- `hakmem_debug.c/.h` - デバッグ機能
- `hakmem_prof.c/.h` - プロファイリング
- `hakmem_sys.c/.h` - システムコール
- `hakmem_syscall.c/.h` - システムコールラッパー
- `hakmem_batch.c/.h` - バッチ操作
- `hakmem_bigcache.c/.h` - ビッグキャッシュ
- `hakmem_whale.c/.h` - Whale (超大型) アロケーション
- `hakmem_super_registry.c/.h` - SuperSlab レジストリ
- `hakmem_p2.c/.h` - P2 アルゴリズム
- `hakmem_site_rules.c/.h` - サイトルール
- `hakmem_sizeclass_dist.c/.h` - サイズクラス分布
- `hakmem_size_hist.c/.h` - サイズヒストグラム

---

## 🧪 ベンチマークプログラム (ルート)

### 主要ベンチマーク

| ファイル | 対象プール | 目的 | サイズ範囲 |
|---------|-----------|------|-----------|
| `bench_tiny_hot.c` | Tiny Pool | 超高速パス (ホットマガジン) | 8-64B |
| `bench_random_mixed.c` | Tiny Pool | ランダムミックス (現実的) | 8-128B |
| `bench_mid_large.c` | L2 Pool | 中型・大型 (シングルスレッド) | 8-32KB |
| `bench_mid_large_mt.c` | L2 Pool | 中型・大型 (マルチスレッド) | 8-32KB |

### その他のベンチマーク

- `bench_tiny.c` - Tiny Pool 基本ベンチ
- `bench_tiny_mt.c` - Tiny Pool マルチスレッド
- `bench_comprehensive.c` - 総合ベンチ
- `bench_fragment_stress.c` - フラグメンテーションストレス
- `bench_realloc_cycle.c` - realloc サイクル
- `bench_allocators.c` - アロケータ比較

**実行方法**: `scripts/run_*.sh` を使用

---

## 📊 性能プロファイリングデータ (`perf_data/`)

- `perf_mid_large_baseline.data` - L2 Pool ベースライン
- `perf_mid_large_qw.data` - Quick Wins 後
- `perf_random_mixed_*.data` - Tiny Pool プロファイル
- `perf_tiny_hot_*.data` - Tiny Hot プロファイル

**使い方**:
```bash
# プロファイル実行
perf record -o perf_data/output.data ./bench_*

# 結果表示
perf report -i perf_data/output.data
```

---

## 📚 ドキュメント (`docs/`)

### `docs/analysis/` - 性能分析
- `CHATGPT_PRO_ULTRATHINK_RESPONSE.md` - ⭐ ChatGPT Pro からの設計レビュー回答 (2025-11-01)
- `*ANALYSIS*.md` - 性能分析レポート
- `BOTTLENECK*.md` - ボトルネック調査
- `CHATGPT*.md` - ChatGPT との議論

### `docs/benchmarks/` - ベンチマーク結果
- `BENCH_RESULTS_*.md` - 日次ベンチマーク結果
- 最新: `BENCH_RESULTS_2025_10_29.md`

### `docs/design/` - 設計ドキュメント
- `*ARCHITECTURE*.md` - アーキテクチャ設計
- `*DESIGN*.md` - 設計ドキュメント
- `*PLAN*.md` - 実装計画
- 例: `MEM_EFFICIENCY_PLAN.md`, `MIMALLOC_STYLE_HOTPATH_PLAN.md`

### `docs/archive/` - アーカイブ
- 古いフェーズレポート、過去の設計書
- Phase 2A-2C のレポート等

---

## 🔧 スクリプト (`scripts/`)

### ベンチマーク実行
- `run_tiny_hot_sweep.sh` - Tiny Hot パラメータスイープ
- `run_mid_large_triad.sh` - Mid/Large 3種比較
- `run_random_mixed_*.sh` - Random Mixed ベンチ

### プロファイリング
- `prof_sweep.sh` - プロファイリングスイープ
- `hakmem-profile-run.sh` - hakmem プロファイル実行

### その他
- `bench_*.sh` - 各種ベンチマークスクリプト
- `kill_bench.sh` - ベンチマーク強制終了

---

## 📄 重要なルートドキュメント

| ファイル | 内容 |
|---------|------|
| `README.md` | プロジェクト概要 |
| `SOURCE_MAP.md` | 📍 **このファイル** - ソースコード構成ガイド |
| `IMPLEMENTATION_ROADMAP.md` | ⭐ **実装ロードマップ** (ChatGPT Pro推奨) |
| `QUESTION_FOR_CHATGPT_PRO.md` | ✅ アーキテクチャレビュー質問 (回答済み) |
| `ENV_VARS.md` | 環境変数リファレンス |
| `QUICK_REFERENCE.md` | クイックリファレンス |
| `DOCS_INDEX.md` | ドキュメント索引 |

---

## 🔍 コードを読む順序 (推奨)

### 初めて読む人向け

1. **README.md** - プロジェクト全体を理解
2. **core/hakmem.c** - エントリーポイント (malloc/free API)
3. **core/hakmem_tiny.c** - Tiny Pool のメインロジック
   - `hakmem_tiny_alloc.inc` - アロケーションホットパス
   - `hakmem_tiny_free.inc` - フリーホットパス
4. **core/hakmem_pool.c** - L2 Pool (中型・大型)
5. **QUESTION_FOR_CHATGPT_PRO.md** - 現在の課題と設計方針

### ホットパス最適化を理解したい人向け

1. **core/hakmem_tiny_alloc.inc** - Tiny アロケーション (7層キャッシュ)
2. **core/hakmem_tiny_hotmag.inc.h** - Hot Magazine (インライン)
3. **core/hakmem_tiny_fastcache.inc.h** - Fast Head SLL
4. **core/hakmem_tiny_ultra_front.inc.h** - Ultra Bump Shadow
5. **core/hakmem_pool.c** - L2 Pool TLS Ring

---

## 🚧 現在の状態 (2025-11-01)

### ✅ 最近の完了項目
- ✅ Phase 2D-4: hakmem_tiny.c を 4555行 → 1081行に削減 (76%減)
- ✅ モジュール分離によるコード整理
- ✅ ルートディレクトリ整理 (docs/, perf_data/ 等)
- ✅ **P0実装完了**: Tiny Pool リフィルバッチ化（+5.16%）
  - `core/hakmem_tiny_refill_p0.inc.h` 新規作成
  - IPC: 4.71 → 5.35 (+13.6%)
  - L1キャッシュミス: -80%

### 📊 ベンチマーク結果（P0実装後）
- ✅ **Tiny Hot 32B**: 215M vs mimalloc 182M (+18% 勝利 🎉)
- ⚠️ **Random Mixed**: 22.5M vs mimalloc 25.1M (-10% 負け)
- ❌ **mid_large_mt**: 46-47M vs mimalloc 122M (-62% 惨敗 ← 最大の課題)

### 🎯 次のステップ（ハイブリッド案）
**Phase 1: Mid Range MT最適化**（最優先、1週間）
- 8-32KB: per-thread segment（mimalloc風）実装
- 目標: 100-120 M ops/s（現状46Mの2.6倍）
- 学習層への影響: なし（64KB以上は無変更）

**Phase 2: ChatGPT Pro P1-P2**（中優先、3-5日）
- Quick補充粒度可変化
- Remote Freeしきい値最適化
- 期待: Random Mixed で +3-5%

詳細: `NEXT_STEP_ANALYSIS.md`, `P0_SUCCESS_REPORT.md`, `3LAYER_FAILURE_ANALYSIS.md`

---

## 🛠️ ビルド方法

```bash
# 基本ビルド
make

# PGO ビルド (推奨)
./build_pgo.sh

# 共有ライブラリ (LD_PRELOAD用)
./build_pgo_shared.sh

# ベンチマーク実行
./scripts/run_tiny_hot_sweep.sh
```

---

**質問・フィードバック**: このドキュメントで分からないことがあれば、お気軽に聞いてください！