# hakmem_tiny_free.inc 分割実装詳細 ## セクション別 行数マッピング ### 現在のファイル構造 ``` hakmem_tiny_free.inc (1,711 lines) SECTION Lines Code Comments Description ════════════════════════════════════════════════════════════════════════ Includes & declarations 1-13 10 3 External dependencies Helper: drain_to_sll_budget 16-25 10 5 ENV-based SLL drain budget Helper: drain_freelist_to_sll 27-42 16 8 Freelist → SLL splicing Helper: remote_queue_contains 44-64 21 10 Duplicate detection ═══════════════════════════════════════════════════════════════════════ MAIN FREE FUNCTION 68-625 462 96 hak_tiny_free_with_slab() └─ SuperSlab mode 70-133 64 29 If slab==NULL dispatch └─ Same-thread TLS paths 135-206 72 36 Fast/List/HotMag └─ Magazine/SLL paths 208-620 413 97 **TO EXTRACT** ═══════════════════════════════════════════════════════════════════════ ALLOCATION SECTION 626-1019 308 86 SuperSlab alloc & refill └─ superslab_alloc_from_slab 626-709 71 22 **TO EXTRACT** └─ superslab_refill 712-1019 237 64 **TO EXTRACT** ═══════════════════════════════════════════════════════════════════════ FREE SECTION 1171-1475 281 82 hak_tiny_free_superslab() └─ Validation & safety 1200-1230 30 20 Bounds/magic check └─ Same-thread path 1232-1310 79 45 **TO EXTRACT** └─ Remote/cross-thread 1312-1470 159 80 **TO EXTRACT** ═══════════════════════════════════════════════════════════════════════ EXTRACTED COMMENTS 1612-1625 0 14 (Placeholder) ═══════════════════════════════════════════════════════════════════════ SHUTDOWN 1676-1705 28 7 hak_tiny_shutdown() ═══════════════════════════════════════════════════════════════════════ ``` --- ## 分割計画（3つの新ファイル） ### SPLIT 1: tiny_free_magazine.inc.h **抽出元:** hakmem_tiny_free.inc lines 208-620 **内容:** ```c LINES CODE CONTENT ──────────────────────────────────────────────────────────── 208-217 10 #if !HAKMEM_BUILD_RELEASE & includes 218-226 9 TinyQuickSlot fast path 227-241 15 TLS SLL fast path (3-4 instruction check) 242-247 6 Magazine hysteresis threshold 248-263 16 Magazine push (top < cap + hyst) 264-290 27 Background spill async queue 291-620 350 Publisher final fallback + loop ``` **推定サイズ:** 413行 → 400行 (include overhead -3行) **新しい公開関数:** (なし - すべて inline/helper) **含まれるヘッダ:** ```c #include "hakmem_tiny_magazine.h" // TinyTLSMag, mag operations #include "tiny_tls_guard.h" // tls_list_push, guard ops #include "mid_tcache.h" // midtc_enabled, midtc_push #include "box/free_publish_box.h" // publisher operations #include // atomic operations ``` **呼び出し箇所:** ```c // In hak_tiny_free_with_slab(), after line 206: #include "tiny_free_magazine.inc.h" if (g_tls_list_enable) { #include logic here } // Else magazine path #include logic here ``` --- ### SPLIT 2: tiny_superslab_alloc.inc.h **抽出元:** hakmem_tiny_free.inc lines 626-1019 **内容:** ```c LINES CODE FUNCTION ────────────────────────────────────────────────────── 626-709 71 superslab_alloc_from_slab() ├─ Remote queue drain ├─ Linear allocation └─ Freelist allocation 712-1019 237 superslab_refill() ├─ Mid-size simple refill (747-782) ├─ SuperSlab adoption (785-947) │ ├─ First-fit slab selection │ ├─ Scoring algorithm │ └─ Slab acquisition └─ Fresh SuperSlab alloc (949-1019) ├─ superslab_allocate() ├─ Init slab 0 └─ Refcount mgmt ``` **추정 사이즈:** 394行 → 380행 **필요한 헤더:** ```c #include "tiny_refill.h" // ss_partial_adopt, superslab_allocate #include "slab_handle.h" // slab_try_acquire, slab_release #include "tiny_remote.h" // Remote tracking #include // atomic operations #include // memset #include // malloc, errno ``` **공개 함수:** - `static SuperSlab* superslab_refill(int class_idx)` - `static inline void* superslab_alloc_from_slab(SuperSlab* ss, int slab_idx)` - `static inline void* hak_tiny_alloc_superslab(int class_idx)` (1020-1170) **호출 위치:** ```c // In hakmem_tiny_free.inc, replace lines 626-1019 with: #include "tiny_superslab_alloc.inc.h" ``` --- ### SPLIT 3: tiny_superslab_free.inc.h **抽출元:** hakmem_tiny_free.inc lines 1171-1475 **내容:** ```c LINES CODE CONTENT ──────────────────────────────────────────────────── 1171-1198 28 Entry & debug initialization 1200-1230 30 Validation & safety checks 1232-1310 79 Same-thread freelist push ├─ ROUTE_MARK tracking ├─ Direct freelist push ├─ remote guard validation ├─ MidTC integration └─ First-free publish 1312-1470 159 Remote/cross-thread path ├─ Owner tid validation ├─ Remote queue enqueue ├─ Sentinel validation └─ Pending coordination ``` **推定サイズ:** 305행 → 290행 **필요한 헤더:** ```c #include "box/free_local_box.h" // tiny_free_local_box() #include "box/free_remote_box.h" // tiny_free_remote_box() #include "tiny_remote.h" // Remote validation & tracking #include "slab_handle.h" // slab_index_for #include "mid_tcache.h" // midtc operations #include // raise() #include // atomic operations ``` **공개 함수:** - `static inline void hak_tiny_free_superslab(void* ptr, SuperSlab* ss)` **호출 위치:** ```c // In hakmem_tiny_free.inc, replace lines 1171-1475 with: #include "tiny_superslab_free.inc.h" ``` --- ## Makefile 의존성 업데이트 **현재:** ```makefile libhakmem.so: hakmem_tiny_free.inc (간접 의존) ``` **변경 후:** ```makefile libhakmem.so: core/hakmem_tiny_free.inc \ core/tiny_free_magazine.inc.h \ core/tiny_superslab_alloc.inc.h \ core/tiny_superslab_free.inc.h ``` **또는 자동 의존성 생성 (이미 Makefile에 있음):** ```makefile # gcc -MMD -MP 플래그로 자동 검출됨 # .d 파일에 .inc 의존성도 기록됨 ``` --- ## 함수별 이동 체크리스트 ### hakmem_tiny_free.inc 에 남을 함수 - [x] `tiny_drain_to_sll_budget()` (lines 16-25) - [x] `tiny_drain_freelist_to_sll_once()` (lines 27-42) - [x] `tiny_remote_queue_contains_guard()` (lines 44-64) - [x] `hak_tiny_free_with_slab()` (lines 68-625, 축소됨) - [x] `hak_tiny_free()` (lines 1476-1610) - [x] `hak_tiny_shutdown()` (lines 1676-1705) ### tiny_free_magazine.inc.h 로 이동 - [x] `hotmag_push()` (inline from magazine.h) - [x] `tls_list_push()` (inline from guard) - [x] `bulk_mag_to_sll_if_room()` - [x] Magazine hysteresis logic - [x] Background spill logic - [x] Publisher fallback logic ### tiny_superslab_alloc.inc.h 로 이동 - [x] `superslab_alloc_from_slab()` (lines 626-709) - [x] `superslab_refill()` (lines 712-1019) - [x] `hak_tiny_alloc_superslab()` (lines 1020-1170) - [x] Adoption scoring helpers - [x] Registry scan helpers ### tiny_superslab_free.inc.h 로 이동 - [x] `hak_tiny_free_superslab()` (lines 1171-1475) - [x] Inline: `tiny_free_local_box()` - [x] Inline: `tiny_free_remote_box()` - [x] Remote queue sentinel validation - [x] First-free publish detection --- ## 병합/분리 후 검증 체크리스트 ### Build Verification ```bash [ ] make clean [ ] make build # Should not error [ ] make bench_comprehensive_hakmem [ ] Check: No new compiler warnings ``` ### Behavioral Verification ```bash [ ] ./larson_hakmem 2 8 128 1024 1 12345 4 → Score should match baseline (±1%) [ ] Run with various ENV flags: [ ] HAKMEM_TINY_DRAIN_TO_SLL=16 [ ] HAKMEM_TINY_SS_ADOPT=1 [ ] HAKMEM_SAFE_FREE=1 [ ] HAKMEM_TINY_FREE_TO_SS=1 ``` ### Code Quality ```bash [ ] grep -n "hak_tiny_free_with_slab\|superslab_refill" core/*.inc.h → Should find only in appropriate files [ ] Check cyclomatic complexity reduced [ ] hak_tiny_free_with_slab: 28 → ~8 [ ] superslab_refill: 18 (isolated) [ ] hak_tiny_free_superslab: 16 (isolated) ``` ### Git Verification ```bash [ ] git diff core/hakmem_tiny_free.inc | wc -l → Should show ~700 deletions, ~300 additions [ ] git add core/tiny_free_magazine.inc.h [ ] git add core/tiny_superslab_alloc.inc.h [ ] git add core/tiny_superslab_free.inc.h [ ] git commit -m "Split hakmem_tiny_free.inc into 3 focused modules" ``` --- ## 分割の逆戻し手順（緊急時） ```bash # Step 1: Restore backup cp core/hakmem_tiny_free.inc.bak core/hakmem_tiny_free.inc # Step 2: Remove new files rm core/tiny_free_magazine.inc.h rm core/tiny_superslab_alloc.inc.h rm core/tiny_superslab_free.inc.h # Step 3: Reset git git checkout core/hakmem_tiny_free.inc git reset --hard HEAD~1 # If committed # Step 4: Rebuild make clean && make ``` --- ## 分割後のアーキテクチャ図 ``` ┌──────────────────────────────────────────────────────────┐ │ hak_tiny_free() Entry Point │ │ (1476-1610, 135 lines, CC=12) │ └───────────────────┬────────────────────────────────────┘ │ ┌───────────┴───────────┐ │ │ v v [SuperSlab] [TinySlab] g_use_superslab=1 fallback │ │ v v ┌──────────────────┐ ┌─────────────────────┐ │ tiny_superslab_ │ │ hak_tiny_free_with_ │ │ free.inc.h │ │ slab() │ │ (305 lines) │ │ (dispatches to:) │ │ CC=16 │ └─────────────────────┘ │ │ │ ├─ Validation │ ┌─────────────────────────┐ │ ├─ Same-thread │ │ tiny_free_magazine.inc.h│ │ │ path (79L) │ │ (400 lines) │ │ └─ Remote path │ │ CC=10 │ │ (159L) │ │ │ └──────────────────┘ ├─ TinyQuickSlot ├─ TLS SLL push [Alloc] ├─ Magazine push ┌──────────┐ ├─ Background spill v v ├─ Publisher fallback ┌──────────────────────┐ │ tiny_superslab_alloc │ │ .inc.h │ │ (394 lines) │ │ CC=18 │ │ │ │ ├─ superslab_refill │ │ │ (308L, O(n) path)│ │ ├─ alloc_from_slab │ │ │ (84L) │ │ └─ entry point │ │ (151L) │ └──────────────────────┘ ``` --- ## パフォーマンス影響の予測 ### コンパイル時間 - **Before:** ~500ms (1 large file) - **After:** ~650ms (4 files with includes) - **増加:** +30% (許容範囲内) ### ランタイム性能 - **変化なし** (全てのコードは inline/static) - **理由:** `.inc.h` ファイルはコンパイル時に1つにマージされる ### 検証方法 ```bash ./larson_hakmem 2 8 128 1024 1 12345 4 # Expected: 4.19M ± 2% ops/sec (baseline maintained) ``` --- ## ドキュメント更新チェック - [ ] CLAUDE.md - 新しいファイル構造を記述 - [ ] README.md - 概要に分割情報を追加（必要なら） - [ ] Makefile コメント - 依存関係の説明 - [ ] このファイル (SPLIT_DETAILS.md)