diff --git a/core/box/smallobject_cold_iface_v4.h b/core/box/smallobject_cold_iface_v4.h index 85b2448a..f9d070e4 100644 --- a/core/box/smallobject_cold_iface_v4.h +++ b/core/box/smallobject_cold_iface_v4.h @@ -1,8 +1,9 @@ -// smallobject_cold_iface_v4.h - SmallObject HotHeap v4 Cold Interface (境界 API のみ) +// smallobject_cold_iface_v4.h - SmallObject HotHeap v4 Cold Interface (Direct Functions) // // 役割: -// - HotBox_v4 と Superslab/Warm/Remote を繋ぐ関数ポインタの箱を定義する。 -// - 実装は後続フェーズで追加し、いまは型と宣言だけを置く。 +// - HotBox_v4 と Superslab/Warm/Remote を繋ぐ Cold 側のインターフェース。 +// - 関数ポインタ（vtable）ではなく direct function で統一。 +// - Hot Box は以下の関数を直接呼び出す（callback ではなく）。 #pragma once #include @@ -10,17 +11,8 @@ #include "smallobject_hotbox_v4_box.h" -typedef struct SmallColdIfaceV4 { - small_page_v4* (*refill_page)(small_heap_ctx_v4*, uint32_t class_idx); - void (*retire_page)(small_heap_ctx_v4*, uint32_t class_idx, small_page_v4* page); - bool (*remote_push)(small_page_v4* page, void* ptr, uint32_t self_tid); - void (*remote_drain)(small_heap_ctx_v4*); -} SmallColdIfaceV4; - -// Cold iface accessor（実装は後続フェーズ） -const SmallColdIfaceV4* small_cold_iface_v4_get(void); - -// Direct function prototypes (Alternative API for direct calls, not yet implemented) +// Cold path API: Direct functions (not function pointers) +// Hot box から直接呼び出される Cold 側の実装。 small_page_v4* small_cold_v4_refill_page(small_heap_ctx_v4* ctx, uint32_t class_idx); void small_cold_v4_retire_page(small_heap_ctx_v4* ctx, small_page_v4* page); bool small_cold_v4_remote_push(small_page_v4* page, void* ptr, uint32_t tid); diff --git a/core/box/smallobject_hotbox_v4_box.h b/core/box/smallobject_hotbox_v4_box.h index 53e34ca1..01822d03 100644 --- a/core/box/smallobject_hotbox_v4_box.h +++ b/core/box/smallobject_hotbox_v4_box.h @@ -15,10 +15,14 @@ #define SMALLOBJECT_NUM_CLASSES TINY_NUM_CLASSES #endif -struct small_segment_v4; +struct SmallSegment; // Forward declaration, defined in smallsegment_v4_box.h -// Page metadata for v4 HotBox -typedef struct small_page_v4 { +// ============================================================================ +// SmallObject v4 HotBox Type Definitions +// ============================================================================ + +// SmallPageMeta: Page metadata for v4 HotBox +typedef struct SmallPageMeta { void* freelist; uint16_t used; uint16_t capacity; @@ -26,29 +30,28 @@ typedef struct small_page_v4 { uint8_t flags; uint32_t block_size; uint8_t* base; - void* slab_ref; // Superslab / lease token (box境界で扱う) - struct small_segment_v4* segment; // PF3: segment owner（NULLなら Tiny v1 経路） - struct small_page_v4* next; -} small_page_v4; + void* slab_ref; // Superslab / lease token (box boundary) + struct SmallSegment* segment; // Segment owner (NULL if Tiny v1 path) + struct SmallPageMeta* next; +} SmallPageMeta; -// Per-class heap state (current / partial / full lists) -typedef struct small_class_heap_v4 { - small_page_v4* current; - small_page_v4* partial_head; - small_page_v4* full_head; +// SmallClassHeap: Per-class heap state (current / partial / full lists) +typedef struct SmallClassHeap { + SmallPageMeta* current; + SmallPageMeta* partial_head; + SmallPageMeta* full_head; uint32_t partial_count; -} small_class_heap_v4; +} SmallClassHeap; -// TLS heap context (per-thread) -typedef struct small_heap_ctx_v4 { - small_class_heap_v4 cls[SMALLOBJECT_NUM_CLASSES]; -} small_heap_ctx_v4; +// SmallHeapCtx: TLS heap context (per-thread) +typedef struct SmallHeapCtx { + SmallClassHeap cls[SMALLOBJECT_NUM_CLASSES]; +} SmallHeapCtx; -// TLS accessor (実装は後続フェーズで追加) -// SmallPageMeta を external で使う場合のエイリアス -typedef small_page_v4 SmallPageMeta; -typedef small_class_heap_v4 SmallClassHeap; -typedef small_heap_ctx_v4 SmallHeapCtx; +// Backward compatibility aliases (deprecated, use SmallXxx directly) +typedef SmallPageMeta small_page_v4; +typedef SmallClassHeap small_class_heap_v4; +typedef SmallHeapCtx small_heap_ctx_v4; small_heap_ctx_v4* small_heap_ctx_v4_get(void); diff --git a/core/box/smallsegment_v4_box.h b/core/box/smallsegment_v4_box.h index 8e2dd17a..8934abae 100644 --- a/core/box/smallsegment_v4_box.h +++ b/core/box/smallsegment_v4_box.h @@ -4,23 +4,29 @@ #include -// Forward declaration for SmallPageMeta -struct small_page_v4; +// Forward declaration +struct SmallPageMeta; +// ============================================================================ // SmallSegment: class_idx ごとに小さな segment を管理 -// 基本構造: base, page metadata array -typedef struct small_segment_v4 { +// ============================================================================ + +typedef struct SmallSegment { uintptr_t base; // Segment base address uint32_t num_pages; // Number of pages in segment uint32_t owner_tid; // Thread ID that owns this segment uint32_t magic; // Magic number for validation // Page metadata array (flexible, actual size depends on SMALL_PAGE_SIZE / SMALL_SEGMENT_SIZE) - // struct small_page_v4* page_meta[]; -} small_segment_v4; + // struct SmallPageMeta* page_meta[]; +} SmallSegment; -// API: Segment 取得・解放 -small_segment_v4* smallsegment_v4_acquire(int class_idx); -void smallsegment_v4_release_if_empty(small_segment_v4* seg, void* page, int class_idx); +// Backward compatibility alias +typedef SmallSegment small_segment_v4; -// API: ページメタデータの取得 -struct small_page_v4* smallsegment_v4_page_meta_of(small_segment_v4* seg, void* ptr); +// ============================================================================ +// API: Segment Management +// ============================================================================ + +SmallSegment* smallsegment_v4_acquire(int class_idx); +void smallsegment_v4_release_if_empty(SmallSegment* seg, void* page, int class_idx); +struct SmallPageMeta* smallsegment_v4_page_meta_of(SmallSegment* seg, void* ptr); diff --git a/core/smallobject_hotbox_v4.c b/core/smallobject_hotbox_v4.c index e29414c0..14e92f56 100644 --- a/core/smallobject_hotbox_v4.c +++ b/core/smallobject_hotbox_v4.c @@ -248,40 +248,24 @@ static void cold_retire_page_v4(small_heap_ctx_v4* hot_ctx, uint32_t class_idx, free(page); } -static const SmallColdIfaceV4 g_cold_iface_v4 = { - .refill_page = cold_refill_page_v4, - .retire_page = cold_retire_page_v4, - .remote_push = NULL, - .remote_drain = NULL, -}; - -const SmallColdIfaceV4* small_cold_iface_v4_get(void) { - return &g_cold_iface_v4; -} - -// Direct function stubs (phase v4-mid-0: delegates to iface) +// Direct function implementations (phase v4-mid-0: cold_refill/retire を直接呼び出す) small_page_v4* small_cold_v4_refill_page(small_heap_ctx_v4* ctx, uint32_t class_idx) { - const SmallColdIfaceV4* iface = small_cold_iface_v4_get(); - if (!iface || !iface->refill_page) return NULL; - return iface->refill_page(ctx, class_idx); + return cold_refill_page_v4(ctx, class_idx); } void small_cold_v4_retire_page(small_heap_ctx_v4* ctx, small_page_v4* page) { - const SmallColdIfaceV4* iface = small_cold_iface_v4_get(); - if (!iface || !iface->retire_page || !page) return; - iface->retire_page(ctx, (uint32_t)page->class_idx, page); + if (!page) return; + cold_retire_page_v4(ctx, (uint32_t)page->class_idx, page); } bool small_cold_v4_remote_push(small_page_v4* page, void* ptr, uint32_t tid) { - const SmallColdIfaceV4* iface = small_cold_iface_v4_get(); - if (!iface || !iface->remote_push) return false; - return iface->remote_push(page, ptr, tid); + (void)page; (void)ptr; (void)tid; + return false; // stub: not yet implemented } void small_cold_v4_remote_drain(small_heap_ctx_v4* ctx) { - const SmallColdIfaceV4* iface = small_cold_iface_v4_get(); - if (!iface || !iface->remote_drain) return; - iface->remote_drain(ctx); + (void)ctx; + // stub: not yet implemented } // Stub accessor for smallsegment_v4_page_meta_of @@ -321,9 +305,8 @@ static small_page_v4* small_alloc_slow_v4(small_heap_ctx_v4* ctx, int class_idx) return from_partial; } - const SmallColdIfaceV4* cold = small_cold_iface_v4_get(); - if (!cold || !cold->refill_page) return NULL; - small_page_v4* page = cold->refill_page(ctx, (uint32_t)class_idx); + // Call direct Cold function (not vtable) + small_page_v4* page = small_cold_v4_refill_page(ctx, (uint32_t)class_idx); if (!page) return NULL; h->current = page; return page; @@ -400,7 +383,6 @@ void small_heap_free_fast_v4(small_heap_ctx_v4* ctx, int class_idx, void* ptr) { } if (page->used == 0) { - const SmallColdIfaceV4* cold = small_cold_iface_v4_get(); if (loc != V4_LOC_CURRENT) { v4_unlink_from_list(h, loc, prev, page); } @@ -417,11 +399,8 @@ void small_heap_free_fast_v4(small_heap_ctx_v4* ctx, int class_idx, void* ptr) { v4_page_push_partial(h, page); return; } - if (cold && cold->retire_page) { - cold->retire_page(ctx, (uint32_t)class_idx, page); - } else { - free(page); - } + // Call direct Cold function (not vtable) + small_cold_v4_retire_page(ctx, page); return; } diff --git a/docs/analysis/ENV_CLEANUP_CANDIDATES.md b/docs/analysis/ENV_CLEANUP_CANDIDATES.md new file mode 100644 index 00000000..93500e01 --- /dev/null +++ b/docs/analysis/ENV_CLEANUP_CANDIDATES.md @@ -0,0 +1,137 @@ +# ENV Variable Cleanup Candidates + +**Date**: 2025-12-10 +**Status**: Documentation for code cleanup planning + +--- + +## Summary + +This document lists environment variables that are candidates for cleanup, categorization, and potential removal. The analysis is based on current usage in bench profiles, default configurations, and implementation status. + +--- + +## Categories + +### 1. KEEP: Core Production (Always ON by default) + +These ENVs control essential features that are ON by default in all standard profiles. + +| ENV | Default | Purpose | Status | +|-----|---------|---------|--------| +| `HAKMEM_TINY_FRONT_V3_ENABLED` | 1 | Front v3 fast path | CORE | +| `HAKMEM_TINY_FRONT_V3_LUT_ENABLED` | 1 | Front v3 lookup table | CORE | +| `HAKMEM_SMALL_HEAP_V3_ENABLED` | 1 | SmallObject HotBox v3 | CORE | +| `HAKMEM_SMALL_HEAP_V3_CLASSES` | 0x80 | SmallObject v3 class mask (C7 by default) | CORE | +| `HAKMEM_TINY_C7_ULTRA_ENABLED` | 1 | C7 ULTRA segment path | CORE | +| `HAKMEM_POOL_V1_FLATTEN_ENABLED` | 0 | Pool v1 flatten fast path (OFF default) | SAFE | + +--- + +### 2. RESEARCH: Experimental & Gate-able (OFF by default) + +These ENVs control alternative/experimental implementations. All are OFF by default, enabling opt-in for A/B testing. + +| ENV | Default | Purpose | Status | Notes | +|-----|---------|---------|--------|-------| +| `HAKMEM_SMALL_HEAP_V4_ENABLED` | 0 | SmallObject HotBox v4 (research) | RESEARCH | Phase v4-mid-0 onwards | +| `HAKMEM_SMALL_HEAP_V4_CLASSES` | 0x0 | SmallObject v4 class mask | RESEARCH | Opt-in only | +| `HAKMEM_TINY_HOTHEAP_V2` | 0 | TinyHotHeap v2 (research) | RESEARCH | Complete but disabled | +| `HAKMEM_TINY_HOTHEAP_CLASSES` | 0x00 | TinyHotHeap class mask | RESEARCH | v2 only, OFF by default | +| `HAKMEM_POOL_V2_ENABLED` | 0 | Pool HotBox v2 (research) | RESEARCH | Stub, not used | +| `HAKMEM_POOL_V2_CLASSES` | 0x0 | Pool v2 class mask | RESEARCH | Unused | +| `HAKMEM_SMALL_SEGMENT_V4_ENABLED` | 0 | SmallSegment v4 (research) | RESEARCH | Phase v4 onwards | +| `HAKMEM_TINY_C7_ULTRA_HEADER_LIGHT` | 0 | C7 ULTRA header optimization (research) | RESEARCH | Experimental | + +--- + +### 3. DELETE CANDIDATES: Dead/Obsolete Code + +These ENVs should be considered for removal (after confirming no active usage): + +| ENV | Status | Reason | Action | +|-----|--------|--------|--------| +| `HAKMEM_TINY_FRONT_V2` | OBSOLETE | Front v2 replaced by v3 | Consider deletion | +| `HAKMEM_TINY_HEAP_V2` | RESEARCH-ONLY | Magazine variant, no perf gain | Keep as research | +| `POOL_V2_*` (all) | STUB | Not fully implemented | Consider deletion | + +--- + +### 4. CONFIGURATION: Profile-specific (Should not be user-editable) + +These ENVs are set by bench profiles and should not be manually edited: + +| ENV | Typical Value | Purpose | +|-----|---------------|---------| +| `HAKMEM_BENCH_MIN_SIZE` | 16 or 257 | Workload size range (bench only) | +| `HAKMEM_BENCH_MAX_SIZE` | 1024 or 768 | Workload size range (bench only) | +| `HAKMEM_PROFILE` | `MIXED_TINYV3_C7_SAFE` | Bench profile selection | +| `HAKMEM_TINY_HEAP_PROFILE` | `C7_SAFE` | Tiny heap profile | + +--- + +### 5. STATISTICS & DEBUG (Non-functional) + +These ENVs control measurement and debugging, not behavior: + +| ENV | Default | Purpose | +|-----|---------|---------| +| `HAKMEM_SMALL_HEAP_V3_STATS` | 0 | SmallObject v3 stats collection | +| `HAKMEM_TINY_HOTHEAP_V2_STATS` | 0 | TinyHotHeap v2 stats collection | +| `HAKMEM_SS_OS_STATS` | 0 | SuperSlab OS stats | +| `HAKMEM_POOL_V1_FLATTEN_STATS` | 0 | Pool flatten stats | + +--- + +## Recommended Action Plan + +### Phase 1: Immediate Documentation (Done) + +- [x] Categorize all active ENVs +- [x] Document which are production vs. research +- [x] Mark deletion candidates + +### Phase 2: Cleanup (Future) + +1. **Create `ENV_DEFAULTS.h`**: Consolidate default values +2. **Deprecate dead code**: Mark `HAKMEM_TINY_FRONT_V2`, `POOL_V2_*` as obsolete +3. **Organize env boxes**: Group by category + - `core/box/env/production_env_box.h` (KEEP) + - `core/box/env/research_env_box.h` (RESEARCH) + - `core/box/env/profile_env_box.h` (PROFILE) + +### Phase 3: Deletion (Later) + +- Confirm zero references to deprecated ENVs +- Remove associated code (v2, pool_v2) +- Update documentation + +--- + +## Default Configuration (Current Standard) + +The `MIXED_TINYV3_C7_SAFE` profile (Mixed workload baseline) uses: + +```bash +HAKMEM_BENCH_MIN_SIZE=16 +HAKMEM_BENCH_MAX_SIZE=1024 +HAKMEM_TINY_HEAP_PROFILE=C7_SAFE +HAKMEM_TINY_C7_HOT=1 +HAKMEM_TINY_HOTHEAP_V2=0 # OFF +HAKMEM_SMALL_HEAP_V3_ENABLED=1 # ON +HAKMEM_SMALL_HEAP_V3_CLASSES=0x80 # C7-only +HAKMEM_SMALL_HEAP_V4_ENABLED=0 # OFF (research) +HAKMEM_POOL_V2_ENABLED=0 # OFF (research) +HAKMEM_TINY_FRONT_V3_ENABLED=1 # ON +HAKMEM_TINY_FRONT_V3_LUT_ENABLED=1 # ON +HAKMEM_TINY_C7_ULTRA_ENABLED=1 # ON +``` + +--- + +## Notes + +- **v2 code is complete and safe**: Not marked for deletion; remains as research/A/B testing infrastructure. +- **v4 code is scaffolding**: Phase v4-mid-0 introduces type skeleton; later phases will add implementation. +- **Research boxes are intentional**: Pool v2, TinyHeap v2, and v4 variants serve as design exploration layers. +