hakmem/docs/design/REFACTOR_PLAN.md

HAKMEM Tiny Allocator スーパーリファクタリング計画

執行サマリー

現状

• hakmem_tiny.c (1584行): 複数の .inc ファイルをアグリゲートする器
• hakmem_tiny_free.inc (1470行): 最大級の混合ファイル
  • Free パス (33-558行)
  • SuperSlab Allocation (559-998行)
  • SuperSlab Free (999-1369行)
  • Query API (commented-out, extracted to hakmem_tiny_query.c)

問題点:

1. 単一のメガファイル (1470行)
2. Free + Allocation が混在
3. 責務が不明確
4. Static inline の嵌套が深い

目標

「箱理論に基づいて、500行以下のファイルに分割」

• 各ファイルが単一責務 (SRP)
• static inline で境界をゼロコスト化
• 依存関係を明確化
• リファクタリング順序の最適化

---

Phase 1: 現状分析

巨大ファイル TOP 10

ランク	ファイル	行数	責務
1	hakmem_pool.c	2592	Mid/Large allocator (対象外)
2	hakmem_tiny.c	1584	Tiny アグリゲータ (分析対象)
3	hakmem_tiny_free.inc	1470	Free + SS Alloc + Query (要分割)
4	hakmem.c	1449	Top-level allocator (対象外)
5	hakmem_l25_pool.c	1195	L25 pool (対象外)
6	hakmem_tiny_intel.inc	863	Intel 最適化 (分割候補)
7	hakmem_tiny_superslab.c	810	SuperSlab (継続, 強化済み)
8	hakmem_tiny_stats.c	697	Statistics (継続)
9	tiny_remote.c	645	Remote queue (継続, 分割候補)
10	hakmem_learner.c	603	Learning (対象外)

Tiny 関連で 500行超のファイル

hakmem_tiny_free.inc        1470 ← 要分割（最優先）
hakmem_tiny_intel.inc        863 ← 分割候補
hakmem_tiny_init.inc         544 ← 分割候補
tiny_remote.c                645 ← 分割候補

hakmem_tiny.c が include する .inc ファイル (44個)

最大級 (300行超):

• hakmem_tiny_free.inc (1470) ← 最優先
• hakmem_tiny_intel.inc (863)
• hakmem_tiny_init.inc (544)

中規模 (150-300行):

• hakmem_tiny_refill.inc.h (410)
• hakmem_tiny_alloc_new.inc (275)
• hakmem_tiny_background.inc (261)
• hakmem_tiny_alloc.inc (249)
• hakmem_tiny_lifecycle.inc (244)
• hakmem_tiny_metadata.inc (226)

小規模 (50-150行):

• hakmem_tiny_ultra_simple.inc (176)
• hakmem_tiny_slab_mgmt.inc (163)
• hakmem_tiny_fastcache.inc.h (149)
• hakmem_tiny_hotmag.inc.h (147)
• hakmem_tiny_smallmag.inc.h (139)
• hakmem_tiny_hot_pop.inc.h (118)
• hakmem_tiny_bump.inc.h (107)

---

Phase 2: 箱理論による責務分類

Box 1: Atomic Ops (最下層, 50-100行)

責務: CAS/Exchange/Fetch のラッパー、メモリ順序管理

新規作成:

• tiny_atomic.h (80行)

含める内容:

// Atomics for remote queue, owner_tid, refcount
- tiny_atomic_cas()
- tiny_atomic_exchange()
- tiny_atomic_load/store()
- Memory order wrapper

---

Box 2: Remote Queue & Ownership (下層, 500-700行)

2.1: Remote Queue Operations (tiny_remote_queue.inc.h, 250-350行)

責務: MPSC stack ops, guard check, node management

出処: hakmem_tiny_free.inc の remote queue 部分を抽出

- tiny_remote_queue_contains_guard()
- tiny_remote_queue_push()
- tiny_remote_queue_pop()
- tiny_remote_drain_owner()  // from hakmem_tiny_free.inc:170

2.2: Remote Drain Logic (tiny_remote_drain.inc.h, 200-250行)

責務: Drain logic, TLS cleanup

出処: hakmem_tiny_free.inc の drain ロジック

- tiny_remote_drain_batch()
- tiny_remote_process_mailbox()

2.3: Ownership (Owner TID) (tiny_owner.inc.h, 100-150行)

責務: owner_tid の acquire/release, slab ownership

既存: slab_handle.h (295行, 継続) + 強化 新規: tiny_owner.inc.h

- tiny_owner_acquire()
- tiny_owner_release()
- tiny_owner_self()

依存: Box 1 (Atomic)

---

Box 3: Superslab Core (hakmem_tiny_superslab.c + hakmem_tiny_superslab.h, 継続)

責務: SuperSlab allocation, cache, registry

現状: 810行（既に well-structured）

強化: 下記の Box と連携

• Box 4 の Publish/Adopt
• Box 2 の Remote ops

---

Box 4: Publish/Adopt (上層, 400-500行)

4.1: Publish (tiny_publish.c/h, 継続, 34行)

責務: Freelist 変化を publish

既存: tiny_publish.c (34行) ← 既に tiny

4.2: Mailbox (tiny_mailbox.c/h, 継続, 252行)

責務: 他スレッドからの adopt 要求

既存: tiny_mailbox.c (252行) → 分割検討

- tiny_mailbox_push()  // 50行
- tiny_mailbox_drain() // 150行

分割案:

• tiny_mailbox_push.inc.h (50行)
• tiny_mailbox_drain.inc.h (150行)

4.3: Adopt Logic (tiny_adopt.inc.h, 200-300行)

責務: SuperSlab から slab を adopt する logic

出処: hakmem_tiny_free.inc の adoption ロジックを抽出

- tiny_adopt_request()
- tiny_adopt_select()
- tiny_adopt_cooldown()

依存: Box 3 (SuperSlab), Box 4.2 (Mailbox), Box 2 (Ownership)

---

Box 5: Allocation Path (横断, 600-800行)

5.1: Fast Path (tiny_alloc_fast.inc.h, 200-300行)

責務: 3-4 命令の fast path (TLS cache direct pop)

出処: hakmem_tiny_ultra_simple.inc (176行) + hakmem_tiny_fastcache.inc.h (149行)

// Ultra-simple fast (SRP):
static inline void* tiny_fast_alloc(int class_idx) {
    void** head = &g_tls_cache[class_idx];
    void* ptr = *head;
    if (ptr) *head = *(void**)ptr;  // Pop
    return ptr;
}

// Fast push:
static inline int tiny_fast_push(int class_idx, void* ptr) {
    int cap = g_tls_cache_cap[class_idx];
    int cnt = atomic_load(&g_tls_cache_count[class_idx]);
    if (cnt < cap) {
        void** head = &g_tls_cache[class_idx];
        *(void**)ptr = *head;
        *head = ptr;
        atomic_increment(&g_tls_cache_count[class_idx]);
        return 1;
    }
    return 0;  // Slow path
}

5.2: Refill Logic (tiny_refill.inc.h, 410行, 既存)

責務: キャッシュのリファイル

現状: hakmem_tiny_refill.inc.h (410行) ← 既に well-sized

5.3: Slow Path (tiny_alloc_slow.inc.h, 250-350行)

責務: SuperSlab → New Slab → Refill

出処: hakmem_tiny_free.inc の superslab_refill + allocation logic

• hakmem_tiny_alloc.inc (249行)

- tiny_alloc_slow()
- tiny_refill_from_superslab()
- tiny_new_slab_alloc()

依存: Box 3 (SuperSlab), Box 5.2 (Refill)

---

Box 6: Free Path (横断, 600-800行)

6.1: Fast Free (tiny_free_fast.inc.h, 200-250行)

責務: Same-thread free, TLS cache push

出処: hakmem_tiny_free.inc の fast-path free logic

// Fast same-thread free:
static inline int tiny_free_fast(void* ptr, int class_idx) {
    // Owner check + Cache push
    uint32_t self_tid = tiny_self_u32();
    TinySlab* slab = hak_tiny_owner_slab(ptr);
    if (!slab || slab->owner_tid != self_tid) 
        return 0;  // Slow path
    
    return tiny_fast_push(class_idx, ptr);
}

6.2: Cross-Thread Free (tiny_free_remote.inc.h, 250-300行)

責務: Remote queue push, publish

出処: hakmem_tiny_free.inc の cross-thread logic + remote push

- tiny_free_remote()
- tiny_free_remote_queue_push()

依存: Box 2 (Remote Queue), Box 4.1 (Publish)

6.3: Guard/Safety (tiny_free_guard.inc.h, 100-150行)

責務: Guard sentinel check, bounds validation

出処: hakmem_tiny_free.inc の guard logic

- tiny_free_guard_check()
- tiny_free_validate_ptr()

---

Box 7: Statistics & Query (分析層, 700-900行)

既存（継続）:

• hakmem_tiny_stats.c (697行) - Stats aggregate
• hakmem_tiny_stats_api.h (103行) - Stats API
• hakmem_tiny_stats.h (278行) - Stats internal
• hakmem_tiny_query.c (72行) - Query API

分割検討:

hakmem_tiny_stats.c (697行) は統計エンジン専門なので OK

---

Box 8: Lifecycle (初期化・クリーンアップ, 544行)

既存:

• hakmem_tiny_init.inc (544行) - Initialization
• hakmem_tiny_lifecycle.inc (244行) - Lifecycle
• hakmem_tiny_slab_mgmt.inc (163行) - Slab management

分割検討:

• tiny_init_globals.inc.h (150行) - Global vars
• tiny_init_config.inc.h (150行) - Config from env
• tiny_init_pools.inc.h (150行) - Pool allocation
• tiny_lifecycle_trim.inc.h (120行) - Trim logic
• tiny_lifecycle_shutdown.inc.h (120行) - Shutdown

---

Box 9: Intel Specific (863行)

分割案:

• tiny_intel_fast.inc.h (300行) - Prefetch + PAUSE
• tiny_intel_cache.inc.h (200行) - Cache tuning
• tiny_intel_cfl.inc.h (150行) - CFL-specific
• tiny_intel_skl.inc.h (150行) - SKL-specific (共通化)

---

Phase 3: 分割実行計画

Priority 1: Critical Path (1週間)

目標: Fast path を 3-4 命令レベルまで削減

1. Box 1: tiny_atomic.h (80行) ✨

   • atomic_load_explicit() wrapper
   • atomic_store_explicit() wrapper
   • atomic_cas() wrapper
   • 依存: <stdatomic.h> のみ

2. Box 5.1: tiny_alloc_fast.inc.h (250行) ✨

   • Ultra-simple TLS cache pop
   • 依存: Box 1

3. Box 6.1: tiny_free_fast.inc.h (200行) ✨

   • Same-thread fast free
   • 依存: Box 1, Box 5.1

4. Extract from hakmem_tiny_free.inc:

   • Fast path logic (500行) → 上記へ
   • SuperSlab path (400行) → Box 5.3, 6.2へ
   • Remote logic (250行) → Box 2へ
   • Cleanup → hakmem_tiny_free.inc は 300行に削減

効果: Fast path を system tcache 並みに最適化

---

Priority 2: Remote & Ownership (1週間)

5. Box 2.1: tiny_remote_queue.inc.h (300行)

   • Remote queue ops
   • 依存: Box 1

6. Box 2.3: tiny_owner.inc.h (120行)

   • Owner TID management
   • 依存: Box 1, slab_handle.h (既存)

7. tiny_remote.c の整理: 645行

   • tiny_remote_queue_ops() → tiny_remote_queue.inc.h へ
   • tiny_remote_side_*() → 継続
   • リサイズ: 645 → 350行に削減

効果: Remote ops を モジュール化

---

Priority 3: SuperSlab Integration (1-2週間)

8. Box 3 強化: hakmem_tiny_superslab.c (810行, 継続)

   • Publish/Adopt 統合
   • 依存: Box 2, Box 4

9. Box 4.1-4.3: Publish/Adopt Path (400-500行)

   • tiny_publish.c (34行, 既存)
   • tiny_mailbox.c → 分割
   • tiny_adopt.inc.h (新規)

効果: SuperSlab adoption を完全に統合

---

Priority 4: Allocation/Free Slow Path (1週間)

10. Box 5.2-5.3: Refill & Slow Allocation (650行)

    • hakmem_tiny_refill.inc.h (410行, 既存)
    • tiny_alloc_slow.inc.h (新規, 300行)

11. Box 6.2-6.3: Cross-thread Free (400行)

    • tiny_free_remote.inc.h (新規)
    • tiny_free_guard.inc.h (新規)

効果: Slow path を 明確に分離

---

Priority 5: Lifecycle & Config (1-2週間)

12. Box 8: Lifecycle の分割 (400-500行)

    • hakmem_tiny_init.inc (544行) → 150 + 150 + 150
    • hakmem_tiny_lifecycle.inc (244行) → 120 + 120
    • Remove duplication

13. Box 9: Intel-specific の整理 (863行)

    • tiny_intel_fast.inc.h (300行)
    • tiny_intel_cache.inc.h (200行)
    • tiny_intel_common.inc.h (150行)
    • Deduplicate × 3 architectures

効果: 設定管理を統一化

---

Phase 4: 新ファイル構成案

最終構成

core/
├─ Box 1: Atomic Ops
│  └─ tiny_atomic.h (80行)
│
├─ Box 2: Remote & Ownership
│  ├─ tiny_remote.h (80行, 既存, 軽量化)
│  ├─ tiny_remote_queue.inc.h (300行, 新規)
│  ├─ tiny_remote_drain.inc.h (150行, 新規)
│  ├─ tiny_owner.inc.h (120行, 新規)
│  └─ slab_handle.h (295行, 既存, 継続)
│
├─ Box 3: SuperSlab Core
│  ├─ hakmem_tiny_superslab.h (500行, 既存)
│  └─ hakmem_tiny_superslab.c (810行, 既存)
│
├─ Box 4: Publish/Adopt
│  ├─ tiny_publish.h (6行, 既존)
│  ├─ tiny_publish.c (34行, 既存)
│  ├─ tiny_mailbox.h (11行, 既存)
│  ├─ tiny_mailbox.c (252行, 既존) → 분할 가능
│  ├─ tiny_mailbox_push.inc.h (80行, 새로)
│  ├─ tiny_mailbox_drain.inc.h (150行, 새로)
│  └─ tiny_adopt.inc.h (300行, 새로)
│
├─ Box 5: Allocation
│  ├─ tiny_alloc_fast.inc.h (250行, 新規)
│  ├─ hakmem_tiny_refill.inc.h (410行, 既存)
│  └─ tiny_alloc_slow.inc.h (300行, 新規)
│
├─ Box 6: Free
│  ├─ tiny_free_fast.inc.h (200行, 新規)
│  ├─ tiny_free_remote.inc.h (300行, 新規)
│  ├─ tiny_free_guard.inc.h (120行, 新規)
│  └─ hakmem_tiny_free.inc (1470行, 既存) → 300行に削減
│
├─ Box 7: Statistics
│  ├─ hakmem_tiny_stats.c (697行, 既存)
│  ├─ hakmem_tiny_stats.h (278行, 既存)
│  ├─ hakmem_tiny_stats_api.h (103行, 既存)
│  └─ hakmem_tiny_query.c (72行, 既存)
│
├─ Box 8: Lifecycle
│  ├─ tiny_init_globals.inc.h (150行, 新規)
│  ├─ tiny_init_config.inc.h (150行, 新規)
│  ├─ tiny_init_pools.inc.h (150行, 新規)
│  ├─ tiny_lifecycle_trim.inc.h (120行, 新規)
│  └─ tiny_lifecycle_shutdown.inc.h (120行, 新規)
│
├─ Box 9: Intel-specific
│  ├─ tiny_intel_common.inc.h (150行, 新規)
│  ├─ tiny_intel_fast.inc.h (300行, 新規)
│  └─ tiny_intel_cache.inc.h (200行, 新規)
│
└─ Integration
   └─ hakmem_tiny.c (1584行, 既存, include aggregator)
      └─ 新規フォーマット:
         1. includes Box 1-9
         2. Minimal glue code only

---

Phase 5: Include 順序の最適化

安全な include 依存関係

graph TD
    A[Box 1: tiny_atomic.h] --> B[Box 2: tiny_remote.h]
    A --> C[Box 5/6: Alloc/Free]
    B --> D[Box 2.1: tiny_remote_queue.inc.h]
    D --> E[tiny_remote.c]
    
    A --> F[Box 4: Publish/Adopt]
    E --> F
    
    C --> G[Box 3: SuperSlab]
    F --> G
    G --> H[Box 5.3/6.2: Slow Path]
    
    I[Box 8: Lifecycle] --> H
    J[Box 9: Intel] --> C

hakmem_tiny.c の新規フォーマット

#include "hakmem_tiny.h"
#include "hakmem_tiny_config.h"

// ============================================================
// LAYER 0: Atomic + Ownership (lowest)
// ============================================================
#include "tiny_atomic.h"
#include "tiny_owner.inc.h"
#include "slab_handle.h"

// ============================================================
// LAYER 1: Remote Queue + SuperSlab Core
// ============================================================
#include "hakmem_tiny_superslab.h"
#include "tiny_remote_queue.inc.h"
#include "tiny_remote_drain.inc.h"
#include "tiny_remote.inc"  // tiny_remote_side_*
#include "tiny_remote.c"    // Link-time

// ============================================================
// LAYER 2: Publish/Adopt (publication mechanism)
// ============================================================
#include "tiny_publish.h"
#include "tiny_publish.c"
#include "tiny_mailbox.h"
#include "tiny_mailbox_push.inc.h"
#include "tiny_mailbox_drain.inc.h"
#include "tiny_mailbox.c"
#include "tiny_adopt.inc.h"

// ============================================================
// LAYER 3: Fast Path (allocation + free)
// ============================================================
#include "tiny_alloc_fast.inc.h"
#include "tiny_free_fast.inc.h"

// ============================================================
// LAYER 4: Slow Path (refill + cross-thread free)
// ============================================================
#include "hakmem_tiny_refill.inc.h"
#include "tiny_alloc_slow.inc.h"
#include "tiny_free_remote.inc.h"
#include "tiny_free_guard.inc.h"

// ============================================================
// LAYER 5: Statistics + Query + Metadata
// ============================================================
#include "hakmem_tiny_stats.h"
#include "hakmem_tiny_query.c"
#include "hakmem_tiny_metadata.inc"

// ============================================================
// LAYER 6: Lifecycle + Init
// ============================================================
#include "tiny_init_globals.inc.h"
#include "tiny_init_config.inc.h"
#include "tiny_init_pools.inc.h"
#include "tiny_lifecycle_trim.inc.h"
#include "tiny_lifecycle_shutdown.inc.h"

// ============================================================
// LAYER 7: Intel-specific optimizations
// ============================================================
#include "tiny_intel_common.inc.h"
#include "tiny_intel_fast.inc.h"
#include "tiny_intel_cache.inc.h"

// ============================================================
// LAYER 8: Legacy/Experimental (kept for compat)
// ============================================================
#include "hakmem_tiny_ultra_simple.inc"
#include "hakmem_tiny_alloc.inc"
#include "hakmem_tiny_slow.inc"

// ============================================================
// LAYER 9: Old free.inc (minimal, mostly extracted)
// ============================================================
#include "hakmem_tiny_free.inc"  // Now just cleanup

#include "hakmem_tiny_background.inc"
#include "hakmem_tiny_magazine.h"
#include "tiny_refill.h"
#include "tiny_mmap_gate.h"

---

Phase 6: 実装ガイド

Key Principles

1. SRP (Single Responsibility Principle)

   • Each file: 1 責務、500行以下
   • No sideways dependencies

2. Zero-Cost Abstraction

   • All boundaries via static inline
   • No function pointer indirection
   • Compiler inlines aggressively

3. Cyclic Dependency Prevention

   • Layer 1 → Layer 2 → ... → Layer 9
   • Backward dependency は回避

4. Backward Compatibility

   • Legacy .inc files は維持（互換性）
   • 段階的に新ファイルに移行

Static Inline の使用場所

✅ Use static inline:

// tiny_atomic.h
static inline void tiny_atomic_store(volatile int* p, int v) {
    atomic_store_explicit((_Atomic int*)p, v, memory_order_release);
}

// tiny_free_fast.inc.h
static inline void* tiny_fast_pop_alloc(int class_idx) {
    void** head = &g_tls_cache[class_idx];
    void* ptr = *head;
    if (ptr) *head = *(void**)ptr;
    return ptr;
}

// tiny_alloc_slow.inc.h
static inline void* tiny_refill_from_superslab(int class_idx) {
    SuperSlab* ss = g_tls_current_ss[class_idx];
    if (ss) return superslab_alloc_from_slab(ss, ...);
    return NULL;
}

❌ Don't use static inline for:

• Large functions (>20 lines)
• Slow path logic
• Setup/teardown code

✅ Use regular functions:

// tiny_remote.c
void tiny_remote_drain_batch(int class_idx) {
    // 50+ lines: slow path → regular function
}

// hakmem_tiny_superslab.c
SuperSlab* superslab_refill(int class_idx) {
    // Complex allocation → regular function
}

Macro Usage

Use Macros for:

// tiny_atomic.h
#define TINY_ATOMIC_LOAD(ptr, order) \
    atomic_load_explicit((_Atomic typeof(*ptr)*)ptr, order)

#define TINY_ATOMIC_CAS(ptr, expected, desired) \
    atomic_compare_exchange_strong_explicit( \
        (_Atomic typeof(*ptr)*)ptr, expected, desired, \
        memory_order_release, memory_order_relaxed)

Don't over-use for:

• Complex logic (use functions)
• Multiple statements (hard to debug)

---

Phase 7: Testing Strategy

Per-File Unit Tests

// test_tiny_alloc_fast.c
void test_tiny_alloc_fast_pop_empty() {
    g_tls_cache[0] = NULL;
    assert(tiny_fast_pop_alloc(0) == NULL);
}

void test_tiny_alloc_fast_push_pop() {
    void* ptr = malloc(8);
    tiny_fast_push_alloc(0, ptr);
    assert(tiny_fast_pop_alloc(0) == ptr);
}

Integration Tests

// test_tiny_alloc_free_cycle.c
void test_alloc_free_single_thread() {
    void* p1 = hak_tiny_alloc(8);
    void* p2 = hak_tiny_alloc(8);
    hak_tiny_free(p1);
    hak_tiny_free(p2);
    // Verify no memory leak
}

void test_alloc_free_cross_thread() {
    // Thread A allocs, Thread B frees
    // Verify remote queue works
}

---

期待される効果

パフォーマンス

指標	現状	目標	効果
Fast path 命令数	20+	3-4	-80% cycles
Branch misprediction	50-100 cycles	15-20 cycles	-70%
TLS cache hit rate	70%	85%	+15% throughput

保守性

指標	現状	目標	効果
Max file size	1470行	300-400行	-70% 複雑度
Cyclic dependencies	多数	0	100% 明確化
Code review time	3h	30min	-90%

開発速度

タスク	現状	リファクタ後
Bug fix	2-4h	30min
Optimization	4-6h	1-2h
Feature add	6-8h	2-3h

---

Timeline

Week	Task	Owner	Status
1	Box 1,5,6 (Fast path)	Claude	TODO
2	Box 2,3 (Remote/SS)	Claude	TODO
3	Box 4 (Publish/Adopt)	Claude	TODO
4	Box 8,9 (Lifecycle/Intel)	Claude	TODO
5	Testing + Integration	Claude	TODO
6	Benchmark + Tuning	Claude	TODO

---

Rollback Strategy

If performance regresses:

1. Keep all old .inc files (legacy compatibility)
2. hakmem_tiny.c can include either old or new
3. Gradual migration: one Box at a time
4. Benchmark after each Box

---

Known Risks

1. Include order sensitivity: New Box 順序が critical → Test carefully
2. Inlining threshold: Compiler may not inline all static inline functions → Profiling needed
3. TLS cache contention: Fast path の simple化で TLS synchronization が bottleneck化する可能性 → Monitor g_tls_cache_count
4. RemoteQueue scalability: Box 2 の remote queue が high-contention に弱い → Lock-free 化検討

---

Success Criteria

✅ All tests pass (unit + integration + larson) ✅ Fast path = 3-4 命令 (assembly analysis) ✅ +10-15% throughput on Tiny allocations ✅ All files <= 500 行 ✅ Zero cyclic dependencies ✅ Documentation complete