hakmem/docs/archive/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 プロファイル

使い方:

# プロファイル実行
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

---

🛠️ ビルド方法

# 基本ビルド
make

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

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

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

---

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