hakmem/docs/analysis/SMALLOBJECT_V7_DESIGN.md

## SmallObjectHeap v7 / HAKMEM v3 コア設計メモ（2025-12-11）

このドキュメントは、ULTRA + MID v3 + V6 世代の上に新しく載せる
**SmallObjectHeap v7（= HAKMEM v3 small/mid コア）** の設計方針をまとめたものです。
当面は設計・型スケルトンのみで、挙動は一切変更しません。

---

## 1. 位置づけと層構造（Box Theory）

### 1-1. 既存世代のまとめ

- L0: ULTRA lanes（現行）
  - C4–C7 ULTRA。C7 は 2MiB Segment + 64KiB Page + TLS freelist（C7 ULTRA Box）。
  - Mixed / C7-only で十分な性能が出ており、**FROZEN（完成世代）** とみなす。
- L1: HotBox v2 世代
  - Tiny front v3 + TinyHeap v1（小クラス）。
  - MID v3（257–768B の mid/smallmid を TLS heap で扱う）。
  - V6 C6-only headerless core（RegionId + Segment + TLS lane）の研究箱。
- L2: Segment / Superslab / Warm / Remote
- L3: Policy/Learner + Stats + ENV（ACE/ELO/CAP 等）

この世代では、各帯に特化した箱（ULTRA / MID v3 / V6）を積み上げることで
Mixed 16–1024B を ~30M → ~44M ops/s まで底上げしたが、
small〜mid を一体で見る「共通の SmallObject コア」は存在しない。

### 1-2. v7 世代の狙い

v7 は L1 に新しく追加する **SmallObjectHotBox_v7** として設計する：

```text
Front (size→class→route LUT)
  |
  +-- L0: ULTRA lanes (C4–C7, FROZEN)
  |
  +-- L1: SmallObjectHotBox_v7      ← NEW small/mid コア
  |
  +-- L1': TinyHeap v1 / MID v3 / V6 (fallback/legacy)
  |
  +-- L2: SegmentBox_v7 / ColdIface_v7
  |
  +-- L3: PolicyBox_v7 / RegionIdBox / PageStatsBox
```

目的:
- small（例: 16〜1KiB or 16〜2KiB）と mid の一部を **1 個の thread-local heap + segment** で扱う土台を作る。
- ULTRA 世代（C4–C7）は L0 としてそのまま残す（C7 ULTRA は独立 box）。
- headerless/v6 の実験で得た「RegionId + Segment + TLS lane + PageStats」の物理層パターンをコア側に反映する。

---

## 2. 型設計（SmallHeapCtx_v7 / SmallSegment_v7）

v7 の基本構造は v6/V3 の経験を統合したものとする。

### 2-1. SmallPageMeta_v7

Hot path で頻繁に触るフィールドと Stats 用フィールドを分離する。

```c
// Hot line: alloc/free で触るフィールド
typedef struct SmallPageMeta_v7 {
    // ---- hot fields (cache line 0 想定) ----
    void     *free_list;   // LIFO freelist: block -> next
    uint32_t  used;        // 現在の使用スロット数
    uint32_t  capacity;    // この page にある block スロット数

    uint16_t  class_idx;   // サイズクラス (C0..C?)
    uint16_t  flags;       // HOT/PARTIAL/FULL/REMOTE_PENDING 等
    uint16_t  page_idx;    // Segment 内 index (0..N-1)
    uint16_t  reserved0;   // アラインメント用

    struct SmallSegment_v7 *segment; // Segment への back pointer

    // ---- cold fields (Stats/Policy, cache line 1〜) ----
    uint64_t alloc_count;        // 累積 alloc 数
    uint64_t free_count;         // 累積 free 数
    uint64_t remote_free_count;  // 累積 remote free 数

    uint16_t live_current;       // 現在の live
    uint16_t peak_live;          // lifetime 最大 live
    uint16_t remote_burst_max;   // 一度の drain で吸い上げた remote の最大
    uint16_t reserved1;

    uint32_t epoch_first_alloc;  // coarse epoch (L3 用)
    uint32_t epoch_last_free;    // 同上
} SmallPageMeta_v7;
```

設計ポイント:
- Hot path (alloc/free) では `free_list / used / capacity / class_idx` だけを触る。
- Stats/Learner は L2 retire 時に cold fields を `SmallPageStatsV7` にまとめて L3 に渡す。
- `segment` を持たせて退役時の SegmentBox 更新を簡単にする（必要であれば将来削る）。

### 2-2. SmallClassHeap_v7 / SmallHeapCtx_v7

各クラスの現在/部分/満杯ページと、小さな TLS magazine を持つ。

```c
typedef struct SmallClassHeap_v7 {
    SmallPageMeta_v7 *current;       // いま alloc に使っている page
    SmallPageMeta_v7 *partial_head;  // まだ空きのあるページ
    SmallPageMeta_v7 *full_head;     // FULL 判定のページ（Cold 側に寄せる用）

    void    *local_freelist;         // オプション: mini-ULTRA (class ローカル TLS)
    uint16_t local_freelist_count;
    uint16_t local_freelist_cap;

    uint16_t class_idx;
    uint16_t flags;                  // class 側のポリシーフラグ (ULTRA禁止など)
} SmallClassHeap_v7;

#define HAK_SMALL_NUM_CLASSES_V7  /* 例: 16〜24 */

typedef struct SmallHeapCtx_v7 {
    SmallClassHeap_v7 cls[HAK_SMALL_NUM_CLASSES_V7];
} SmallHeapCtx_v7;
```

設計ポイント:
- v7 第1版では `local_freelist` は無効 (`cap=0`) にしておき、必要なクラスだけ Learner で有効化してもよい。
- クラス数は最初は「small側（16〜1KiB or 2KiB）をカバーする程度」に抑え、
  mid を扱う `MidHeapCtx_v7` は別箱とする（後述）。

### 2-3. SmallSegment_v7

ULTRA の 2MiB/64KiB パターンをベースに、small v7 用 SegmentBox を定義する。

```c
#define SMALL_SEGMENT_SIZE_V7   (2u * 1024u * 1024u)  // 2MiB
#define SMALL_PAGE_SIZE_V7      (64u * 1024u)         // 64KiB
#define SMALL_PAGES_PER_SEG_V7  (SMALL_SEGMENT_SIZE_V7 / SMALL_PAGE_SIZE_V7)

typedef struct SmallSegment_v7 {
    uintptr_t   base;           // 実データ領域の先頭アドレス
    uint32_t    num_pages;      // 実際に使うページ数
    uint32_t    owner_tid;      // 所有スレッド id

    uint32_t    flags;          // SEGMENT_IN_USE / RETIRED 等
    uint32_t    region_kind;    // REGION_SMALL_V7 / REGION_ULTRA / REGION_POOL 等
    uint32_t    segment_idx;    // RegionIdBox 上の index
    uint32_t    free_page_head; // free page stack head
    uint32_t    free_page_count;

    SmallPageMeta_v7 page_meta[SMALL_PAGES_PER_SEG_V7];
} SmallSegment_v7;
```

設計ポイント:
- `ptr & ~(SEG_SIZE-1)` で Segment に直行し、  
  `(ptr - base) >> PAGE_SHIFT` で `page_idx` を求めて `page_meta[page_idx]` に行ける O(1) 構造。
- small/mid/pool で Segment geometry を変えたい場合も、API は共通で持てる（SegmentBox_v7 small / mid 用の 2 種類も可）。

---

## 3. RegionIdBox / header / class 判定方針（v7 世代）

### 3-1. header の扱い

v6 C6-only headerless 実験から：
- header 完全削除は「Region lookup コスト」で相殺されがちで、劇的な改善には繋がらないケースが多い。
- ただし RegionId + Segment + page_meta.class_idx のパターンは  
  ptr→segment→page_meta→class を O(1) にする物理層として非常に有用。

v7 では次の方針とする：

1. ヘッダは **薄く残す**（Fail-Fast／legacy/pool bridge／デバッグ用）。
2. small/mid の fast path では、できるだけ header を触らない。
   - C7 ULTRA / 一部 hot クラス（将来の C6 ULTRA lane など）は完全 headerless も許可。
   - SmallHeapCtx_v7 の core は「carve/refill 時に 1 回だけ書く」程度に抑える。
3. free 時の class 判定は：
   - front/gate の hint（size→class / header） + RegionIdBox + page_meta.class_idx を併用。
   - v7 small pathでは、最終的には `page_meta.class_idx` を真とし、hint は OBSERVE 検証用とする。

### 3-2. RegionIdBox API

small/mid/pool 共通の ptr 分類箱として RegionIdBox_v7 を定義する：

```c
typedef enum {
    REGION_UNKNOWN = 0,
    REGION_SMALL_V7,
    REGION_ULTRA,
    REGION_MID_V7,
    REGION_POOL_V3,
    REGION_LARGE,
} region_kind_t;

typedef struct RegionLookupResult_v7 {
    region_kind_t kind;
    union {
        struct {
            SmallSegment_v7 *segment;
            uint16_t         page_idx;
        } small_v7;
        struct {
            void *segment;  // C7 ULTRA / mid v7 / pool v3 等
        } other;
    } u;
} RegionLookupResult_v7;

static inline RegionLookupResult_v7
region_id_lookup_v7(void *ptr);
```

small v7 free path（fast path）:

```c
RegionLookupResult_v7 lk = region_id_lookup_v7(ptr);
if (likely(lk.kind == REGION_SMALL_V7)) {
    SmallPageMeta_v7* page =
        &lk.u.small_v7.segment->page_meta[lk.u.small_v7.page_idx];
    uint8_t class_idx = page->class_idx;
    small_heap_free_fast_v7(ctx, page, class_idx, ptr);
} else {
    // ULTRA / MID / POOL / LEGACY へ bridge
}
```

移行モード:
- Phase OBSERVE: header-based class と page_meta.class_idx を比較して log/assert。挙動はまだ v2 世代のまま。
- Phase FROZEN: small v7 管理ページでは header を見ず、RegionId + page_meta.class_idx だけで動かす。

---

## 4. mid/pool との関係（SmallHeapCtx_v7 vs MidHeapCtx_v7）

v7 世代では small と mid を同じ物理層（RegionIdBox + SegmentBox + PageStatsBox）に乗せつつ、
HotBox は別箱に分けるのが現実的：

```text
RegionIdBox / SegmentBox_v7 / PageStatsBox
    |
    +--> SmallHeapCtx_v7  (small: 16〜1KiB or 2KiB)
    |
    +--> MidHeapCtx_v7    (mid: 2〜16KiB or 2〜32KiB)
    |
    +--> PoolCtx_v3/v7    (さらに大きい / 特殊用途)
```

方針:
- **共通化するもの**:
  - RegionIdBox（ptr→region_kind + segment/page_idx）
  - Segment geometry API（small 用と mid 用に派生しても良い）
  - PageStats 基本構造（class_idx / alloc/free/remote / live/peak など）
- **専用箱にするもの**:
  - SmallHeapCtx_v7（small 特有の TLS/prefetch/クラス配置）
  - MidHeapCtx_v7（mid 特有の page サイズ・クラス分割・remote ポリシー）
  - PoolCtx_v3/v7（巨大オブジェクト／特殊用途）

橋渡し:
- RegionIdBox で kind != REGION_SMALL_V7 を検出したときのみ、
  mid/pool の bridge_box（`small_mid_bridge_free()` 等）に渡す。
- small core / mid core / pool core は互いを直接呼ばず、「bridge 1 箇所」で繋ぐ。

---

## 5. フェーズ分割（v7-0 / v7-1 / v7-2 の指針）

いきなり small/mid 全体を v7 にするのではなく、C6-only small 帯から段階的に導入する。

### Phase v7-0: 型とインフラだけ追加（挙動一切変更なし）

目的:
- struct と設計 doc だけ追加し、ビルドと Box 理論上の位置づけを固める。

タスク:
- `SmallPageMeta_v7` / `SmallClassHeap_v7` / `SmallHeapCtx_v7` / `SmallSegment_v7` struct をヘッダに追加。
- RegionIdBox に `REGION_SMALL_V7` と `RegionLookupResult_v7` を追加（実装はまだダミーで OK）。
- ENV:
  - `HAKMEM_SMALL_HEAP_V7_ENABLED=0`
  - `HAKMEM_SMALL_HEAP_V7_CLASSES=0x0`
  - front/gate は v7 に一切 route しない。

### Phase v7-1: C6-only v7 stub（route だけ v7 に向ける）

目的:
- front/gate・ENV・RegionIdBox の配線が壊れていないか確認する。

タスク:
- `TINY_ROUTE_SMALL_HEAP_V7` を route kind に追加。
- プロファイル: C6-only v7 stub モード（`CLASSES=0x40` など）を追加。
- `small_heap_alloc_fast_v7_stub(size, ci)` / `small_heap_free_fast_v7_stub(ptr, ci)` を実装し、
  中身は即座に v2 世代（MID v3 / V6 / pool v1）にフォールバックするだけにする。
- RegionIdBox は OBSERVE モードで `region_id_lookup_v7(ptr)` を呼んで統計取得のみ（挙動不変）。

### Phase v7-2: C6-only v7 本実装（small帯だけ）

目的:
- C6-only の alloc/free を SmallHeapCtx_v7 + SmallSegment_v7 で本当に回し、  
  C6-heavy / Mixed で v3/V6/v2 本線と比較する。

タスク:
- SegmentBox_v7 と ColdIface_v7 を実装し、C6 pages の refill/retire を Segment v7 経由にする。
- `small_heap_alloc_fast_v7(size, ci)` / `small_heap_free_fast_v7(ptr, ci)` を実装：
  - alloc: current→partial→cold_refill の順で page/freelist を消費。
  - free: RegionIdBox で small_v7 page を特定し、page_meta.free_list に push（必要時 retire）。
- プロファイル:
  - C6-only v7 ON（他クラスは ULTRA + MID v3 + V6 のまま）。
- ベンチ:
  - C6-heavy / Mixed で v7 vs MID v3 vs V6 vs v2 本線を測り、  
    C6-only v7 の価値を評価（十分なら次の v7 拡張フェーズへ）。

---

## 6. まとめ

- v2 世代（ULTRA + MID v3 + V6 C6-only）は、Box Theory に沿ってかなりやり切った世代とみなし、ここで一度締める。
- v3 世代（SmallObjectHeap v7）は、「small〜mid を 1 個の SmallHeapCtx + Segment + RegionIdBox で扱う」第2章として設計する。
- まずは C6-only small 帯から v7 を導入し、ULTRA/MID v3 を壊さない形で徐々に適用範囲を広げていく。