hakmem/docs/archive/claude.md

hakmem - Claude向けクイックリファレンス

📚 主要ドキュメント

基本

• README.md - プロジェクト全体の概要
• docs/INDEX.md - ドキュメント索引

仕様・設定

• docs/specs/CURRENT_SPEC.md - 現在の実装仕様（SACS-3、学習、環境変数）
• docs/specs/ENV_VARS.md - 環境変数の一覧と意味（30以上のオプション）

ベンチマーク

• docs/benchmarks/README.md - 計測の流れ、保存場所、命名規則
• docs/benchmarks/2025-10-22_SWEEP_NOTES.md - 最新の計測要約

実装状況

• docs/status/IMPLEMENTATION_STATUS_2025_10_22.md - 実装状況
• PHASE_6.15_SUMMARY.md - Phase 6.15の要約（TLS最適化）

🚀 クイックスタート

ビルド

# 通常ビルド
make shared

# デバッグビルド（タイミング計測ON）
make debug

# ベンチマーク用（profiler組み込み）
make bench

基本的な使い方

1. プリセットモードで実行

# BALANCED モード（推奨）
HAKMEM_MODE=balanced LD_PRELOAD=./libhakmem.so ./your_app

# MINIMAL モード（ベースライン、最適化OFF）
HAKMEM_MODE=minimal LD_PRELOAD=./libhakmem.so ./your_app

# LEARNING モード（自動学習）
HAKMEM_MODE=learning LD_PRELOAD=./libhakmem.so ./your_app

2. タイミング計測

# 全カテゴリの実行時間を計測（終了時にstderrへ出力）
HAKMEM_TIMING=1 LD_PRELOAD=./libhakmem.so ./your_app

3. Profilerでホットパス分析

# サンプリングprofiler有効化（1/4096サンプリング）
HAKMEM_PROF=1 LD_PRELOAD=./libhakmem.so ./your_app

# サンプリング率変更（1/256に）
HAKMEM_PROF=1 HAKMEM_PROF_SAMPLE=8 LD_PRELOAD=./libhakmem.so ./your_app

4. 学習機能（自動キャッシュチューニング）

# 1秒ごとにヒット率を見てキャッシュ容量を自動調整
HAKMEM_LEARN=1 LD_PRELOAD=./libhakmem.so ./your_app

# パラメータ調整
HAKMEM_LEARN=1 \
  HAKMEM_TARGET_HIT_MID=0.70 \
  HAKMEM_LEARN_WINDOW_MS=500 \
  LD_PRELOAD=./libhakmem.so ./your_app

🔍 トレーシング・デバッグ機能

Debug Timing（詳細なタイミング計測）

• 有効化: HAKMEM_TIMING=1
• 測定項目: lock取得、リフィル、ドレイン、TLS操作など
• 出力: プログラム終了時にstderrへサイクル単位で統計出力

Sampling Profiler（低オーバーヘッド）

• 有効化: HAKMEM_PROF=1
• サンプリング率: HAKMEM_PROF_SAMPLE=N（1/2^N、デフォルト12=1/4096）
• カテゴリ: tiny_alloc, ace_alloc, pool_refill, l25_refillなど

Learning（自動最適化）

• 有効化: HAKMEM_LEARN=1
• 動作: バックグラウンドスレッドで1秒ごとにヒット率を計測してCAP調整
• パラメータ: 目標ヒット率、ステップ、予算制約など

⚙️ よく使う環境変数

モード設定

• HAKMEM_MODE=minimal|fast|balanced|learning|research

キャッシュ容量（手動設定）

• HAKMEM_CAP_MID=10,20,40,80,160 - Mid Pool (2/4/8/16/32KB)
• HAKMEM_CAP_LARGE=2,4,8,16,32 - Large Pool (64K/128K/256K/512K/1MB)

丸め許容（W_MAX）

• HAKMEM_WMAX_MID=1.4 - Midでの丸め許容率
• HAKMEM_WMAX_LARGE=1.4 - Largeでの丸め許容率

安全性

• HAKMEM_SAFE_FREE=1 - free()時にmincore()チェック（重い）

その他

• HAKMEM_THP=auto|on|off - Transparent Huge Pages
• HAKMEM_SHARD_MIX=1 - シャード分散強化

詳細は docs/specs/ENV_VARS.md を参照。

🧪 ベンチマーク

Larson（マルチスレッド負荷テスト）

# 基本実行（10秒、1/4スレッド）
scripts/run_larson.sh -d 10 -t 1,4

# burst プリセット（同時保持が多い、厳しめ）
scripts/run_larson.sh -d 10 -t 1,4 -p burst

# loop プリセット（局所性が高い、甘め）
scripts/run_larson.sh -d 10 -t 1,4 -p loop

mimalloc-bench

cd mimalloc-bench
./bench.sh

📊 アーキテクチャ

3層構造

• L0: Tiny Pool (≤1KB) - TLS Magazine + Slab
• L1: ACE層 (1KB～2MB)
  • Mid Pool (2～32KB) - TLSリング+LIFO
  • Large Pool (64KB～1MB) - bump-run方式
• L2: BigCache/mmap (≥2MB) - LRU + カーネルmmap

主要コンポーネント

• hakmem.c - メインアロケータ
• hakmem_ace.c - L1統合層（Mid/Large routing）
• hakmem_pool.c - Mid Pool（2～32KB）
• hakmem_l25_pool.c - Large Pool（64KB～1MB）
• hakmem_tiny.c - Tiny Pool（≤1KB）
• hakmem_policy.c - FrozenPolicy（RCUスナップショット）
• hakmem_learner.c - 自動学習（バックグラウンドCAP調整）
• hakmem_debug.c - Debug Timing
• hakmem_prof.c - Sampling Profiler

🎯 現在の課題（2025-10-24更新）

パフォーマンスギャップ

• hakmem vs mimalloc: 1Tで-41%、4Tで-48%の差
• 現状: 4.0M ops/sec (hakmem) vs 6.8M ops/sec (mimalloc)

特定された問題点（調査完了）

1. LD_PRELOADラッパーコンテキストの罠

• 原因: hak_in_wrapper()がTiny/Mid Poolをスキップ
• 影響: 小サイズ割り当て（10-1000バイト）が全てlibc mallocにフォールバック
• タイミング: fallback_malloc = 300 cycles (24.3%)

2. WRAP有効化の逆効果 ⚠️

HAKMEM_WRAP_TINY=1 HAKMEM_WRAP_L2=1を試した結果：

• パフォーマンス: 4.0M → 3.2M ops/sec (-20%悪化)
• 原因:
  • pool_get: 63 → 365 cycles (5.8倍！)
  • pool_alloc_tls_page: 10,915 cycles (重すぎる)
  • tiny_alloc: 131回のみ（5002回allocの2.6%しか使われていない）

3. 詳細な問題点

1. pool_alloc_tls_pageが激重: 10,915 cycles
2. Tiny Poolがほぼ未使用: larsonは10-110バイトなのに2.6%のみ
3. Mid Poolへの偏り: pool_get が7,290回（allocの1.5倍）

次の調査項目

• サイズ分布の確認（larsonの実際の割り当てサイズ）
• pool_alloc_tls_pageの最適化（なぜ重いか）
• Tiny Pool判定ロジックの見直し（なぜ使われないか）
• コード構造の見直し（ultrathink調査予定）

Phase 6.15以降、マルチスレッド性能とmimalloc比較に注力中：

• TLS最適化によりスケーラビリティ向上
• freeの処理最適化
• より詳細なタイミング計測

詳細は最新のPHASE_*.mdドキュメントを参照。