52386401b3
Major Features: - Debug counter infrastructure for Refill Stage tracking - Free Pipeline counters (ss_local, ss_remote, tls_sll) - Diagnostic counters for early return analysis - Unified larson.sh benchmark runner with profiles - Phase 6-3 regression analysis documentation Bug Fixes: - Fix SuperSlab disabled by default (HAKMEM_TINY_USE_SUPERSLAB) - Fix profile variable naming consistency - Add .gitignore patterns for large files Performance: - Phase 6-3: 4.79 M ops/s (has OOM risk) - With SuperSlab: 3.13 M ops/s (+19% improvement) This is a clean repository without large log files. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
300 lines
11 KiB
Markdown
300 lines
11 KiB
Markdown
# 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
|
||
```
|
||
|
||
---
|
||
|
||
**質問・フィードバック**: このドキュメントで分からないことがあれば、お気軽に聞いてください！
|