hakmem/CURRENT_TASK.md

Current Task: Phase E1-CORRECT - 最下層ポインターBox実装

Date: 2025-11-13
Status: 🔧 In Progress
Priority: CRITICAL

---

🎯 Goal

Phase E1-CORRECT において、tiny freelist next ポインタのレイアウト仕様と API を物理制約込みで厳密に統一し、
C7/C0 特殊ケースや直接 *(void**) アクセス起因の SEGV を構造的に排除する。

---

✅ 正式仕様（決定版）

HAKMEM_TINY_HEADER_CLASSIDX フラグ有無と size class ごとに next の格納オフセットを厳密定義する。

1. ヘッダ有効時 (HAKMEM_TINY_HEADER_CLASSIDX != 0)

各クラスの物理レイアウトと next オフセット:

• Class 0:

  • 物理: [1B header][7B payload] (合計 8B)
  • 制約: offset 1 に 8B pointer は入らない (1 + 8 = 9B > 8B) → 不可能
  • 仕様:
    • freelist 中は header を上書きして next を base + 0 に格納
    • free 中 header不要のため問題なし
  • next offset: 0

• Class 1〜6:

  • 物理: [1B header][payload >= 8B]
  • 仕様:
    • header は保持
    • freelist next は header 直後の base + 1 に格納
  • next offset: 1

• Class 7:

  • 大きなブロック / もともと特殊扱いだった領域
  • 実装と互換性・余裕を考慮し、freelist next は base + 0 扱いとするのが合理的
  • next offset: 0

まとめ:

• HAKMEM_TINY_HEADER_CLASSIDX != 0 のとき:
  • Class 0,7 → next_off = 0
  • Class 1〜6 → next_off = 1

2. ヘッダ無効時 (HAKMEM_TINY_HEADER_CLASSIDX == 0)

• 全クラス:
  • header なし
  • freelist next は従来通り base + 0
  • next offset: 常に 0

---

📦 Box / API 統一方針

重複・矛盾していた Box API / tiny_nextptr 実装を以下の方針で統一する。

Authoritative Logic

単一の「next offset 計算」と「安全な load/store」を真実として定義:

• size_t tiny_next_off(int class_idx):
  • #if HAKMEM_TINY_HEADER_CLASSIDX
    • return (class_idx == 0 || class_idx == 7) ? 0 : 1;
  • #else
    • return 0;
• void* tiny_next_load(const void* base, int class_idx)
• void tiny_next_store(void* base, int class_idx, void* next)

この3つを中心に全ての next アクセスを集約する。

box/tiny_next_ptr_box.h

• tiny_nextptr.h をインクルード、もしくは同一ロジックを使用し、 「Box API」としての薄いラッパ/マクロを提供:

例（最終イメージ）:

• static inline void tiny_next_write(int class_idx, void* base, void* next)
  • 中で tiny_next_store(base, class_idx, next) を呼ぶ
• static inline void* tiny_next_read(int class_idx, const void* base)
  • 中で tiny_next_load(base, class_idx) を呼ぶ
• #define TINY_NEXT_WRITE(cls, base, next) tiny_next_write((cls), (base), (next))
• #define TINY_NEXT_READ(cls, base) tiny_next_read((cls), (base))

ポイント:

• API は class_idx と base pointer を明示的に受け取る。
• next offset の分岐 (0 or 1) は API 内だけに閉じ込め、呼び出し元での条件分岐は禁止。
• *(void**) による直接アクセスは禁止（grep で検出対象）。

---

🚫 禁止事項

• Phase E1-CORRECT 以降のコードで以下を使用することは禁止:
  • *(void**)ptr などの直接 next 読み書き
  • class_idx == 7 ? 0 : 1 など、ローカルに next offset を決めるロジック
  • ALL classes offset 1 前提のコメントや実装

これらは順次削除・修正対象。

---

🔍 現状の問題と対策

以前の問題点

• tiny_nextptr.h が「ALL classes → offset 1」として実装されていた時期があり、
  • Class 0 に対して offset 1 書き込み → 即時 SEGV
  • Class 7 や一部 call site での不整合も誘発
• box/tiny_next_ptr_box.h と tiny_nextptr.h が別仕様になり、
  • どちらが正しいか不明瞭な状態で混在していた

対策（このドキュメントが指示すること）

1. 正式仕様を上記の通り固定（Class 0,7 → 0 / Class 1〜6 → 1）。
2. tiny_nextptr.h をこの仕様に合わせて修正する。
3. box/tiny_next_ptr_box.h を tiny_nextptr.h ベースの Box API として整理する。
4. 全ての tiny/TLS/fastcache/refill/SLL 関連コードから、直接 offset 計算と *(void**) を排除し、 tiny_next_* / TINY_NEXT_* API 経由に統一する。
5. grep による監査:
   • grep -R '\*\(void\*\*\)' core/ で違反箇所検出
   • 残存している場合は順次修正

---

✅ Success Criteria

• 10K〜100K iterations のストレステストで全サイズ (C0〜C7) SEGV 0件
• Class 0 に対する offset1 アクセスが存在しない (grep/レビューで確認)
• Class 7 の next アクセスも Box API 経由で一貫 (offset0扱い)
• すべての next アクセスパスが:
  • 「仕様: next_off(class_idx)」に従う tiny_next_* 経由のみで記述されている
• 将来のリファクタ時も、この CURRENT_TASK.md を見れば 「next はどこにあり、どうアクセスすべきか」が一意に判断できる状態

---

📌 実装タスクまとめ（開発者向け）

• tiny_nextptr.h を上記仕様（0/1 mixed: C0,7→0 / C1-6→1）に修正
• box/tiny_next_ptr_box.h を tiny_nextptr.h ベースのラッパとして整理
• 既存コードから next オフセット直書きロジックを撤廃し、Box API に統一
• *(void**) の直接使用箇所を grep で洗い、必要なものを tiny_next_* に置換
• Release/Debug ビルド + 長時間テストで安定性確認
• ドキュメント・コメントから「ALL classes offset 1」系の誤記を除去