hakmem/docs/analysis/SMALLOBJECT_SEGMENT_V4_DESIGN.md

# SmallObject Segment v4 設計メモ (PF2 草稿)

## 目的と背景
- Mixed 16–1024B で mimalloc の 70〜80% に近づくため、small-object 向けの pf/OS レイヤをまとめて削る。
- C7/C6 v4 が揃った状態を前提に、Superslab 配置と Segment 分割を見直し、触る Superslab 数と VMA 数を減らす。
- まだ実装は行わず、箱の分割とパラメータの置き場所を決める段階。

## 現状のレイアウト（把握用）
- Superslab サイズは既存の Tiny/Superslab のまま（4KiB ページ上で C1〜C7 を混載）。
- C5〜C7 のページが混在し、Mixed では 1M ops あたりに跨る Superslab が多い。
- pf としては `mmap/madvise/munmap` の回数が小さくない。C7-only v4 でも minor-faults がボトルネック側に寄りつつある。

## small-object 専用 Segment 案（方向性）
- Superslab を small-object 専用に 2MiB/4MiB 単位でまとめ、C5〜C7 をできるだけ同一 Segment 内に詰める。
- Mixed で触る Superslab の種類を減らし、TLB/pf を削る。
- Box 化のイメージ:
  - **SmallSegmentBox_v4**: Segment の取得/解放と page carving を担当。SuperslabBox/OS を内側で呼ぶ。
  - **SmallSegmentEnvBox_v4**: ENV で Segment サイズやポリシーを決定（例: `HAKMEM_SMALL_SEGMENT_V4_SIZE=2M/4M`）。
  - **SmallSegmentStatsBox**: 触った Segment 数、mmap/madvise 回数、ページ再利用回数をカウントし、PF 調査用にダンプ。
- HotBox_v4 からは ColdIface を通して Segment Box に触れるだけにし、ホットパスは segment/pf を意識しない。

## 今後のフェーズ
- **PF2（今回）**: 現状の pf/OS ベースラインを v4 状態で取り直し、Segment Box の箱だけ追加（挙動不変）。
- **PF3**: SmallSegmentBox_v4 を実装し、C7/C6 v4 で small-object 専用 Segment を試す A/B を実施。
- **PF4**: Segment サイズ/ポリシーのチューニングと pf/OS スタッツの可視化強化。成功したら ENV プリセットに反映。

## PF3 進捗メモ
- smallsegment_v4_box をホットコードに接続し、ENV `HAKMEM_SMALL_SEGMENT_V4_ENABLED` で Tiny v1 経由と segment 経由を切替可能にした（現段階は Tiny v1 lease を薄くラップする構造）。
- Mixed 16–1024B（v4 強制、ws=400, iters=1M）で A/B:
  - OFF: 28.89M ops/s, page-faults=6,744
  - ON : 28.85M ops/s, page-faults=6,746
- pf/ops はまだ変化なし。次フェーズで実際の small-object 専用 mmap/segment carve を入れて再 A/B する。

## メモ
- C5 v4 はまだ研究箱（C5-heavy 専用）。Mixed では C5 v1 を維持する予定。
- C6 v4 は C6-heavy で +4〜5% が見えており、Mixed ではデフォルト OFF（研究箱）。
- PF 系の変更はすべて ENV ゲート付きにし、既存の Mixed/C6-heavy 健康診断がいつでも通る状態を維持する。