tomoaki/hakmem
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
b51b600e8d626601e1deca96d044cd10674c7cb1
hakmem/docs/analysis/ENV_CLEANUP_ANALYSIS.md
Moe Charm (CI) 2ec6689dee Docs: Update ENV variable documentation after Ultra HEAP deletion 
Updated documentation to reflect commit 6b791b97d deletions:

Removed ENV variables (6):
- HAKMEM_TINY_ULTRA_FRONT
- HAKMEM_TINY_ULTRA_L0
- HAKMEM_TINY_ULTRA_HEAP_DUMP
- HAKMEM_TINY_ULTRA_PAGE_DUMP
- HAKMEM_TINY_BG_REMOTE (no getenv, dead code)
- HAKMEM_TINY_BG_REMOTE_BATCH (no getenv, dead code)

Files updated (5):
- docs/analysis/ENV_CLEANUP_ANALYSIS.md: Updated BG/Ultra counts
- docs/analysis/ENV_QUICK_REFERENCE.md: Updated verification sections
- docs/analysis/ENV_CLEANUP_PLAN.md: Added REMOVED category
- docs/archive/TINY_LEARNING_LAYER.md: Added archive notice
- docs/archive/MAINLINE_INTEGRATION.md: Added archive notice

Changes: +71/-32 lines

Preserved ENV variables:
- HAKMEM_TINY_ULTRA_SLIM (active 4-layer fast path)
- HAKMEM_ULTRA_SLIM_STATS (Ultra SLIM statistics)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
2025-11-27 04:51:59 +09:00

13 KiB
Raw Blame History

HAKMEM ENV Variables - Comprehensive Cleanup Analysis

Total Variables: 282 → Target: <50

Generated: 2025年 11月 26日 水曜日 16:58:53 JST

Executive Summary

Category Count Percentage Action
OBSOLETE 54 19% REMOVE (defunct features)
DEBUG 59 21% GATE (#if !HAKMEM_BUILD_RELEASE)
ESSENTIAL 20 7% KEEP (core functionality)
POLICY 149 53% CONSOLIDATE (reduce to ~30)

Reduction Path: 282 → 113 (remove obsolete) → 54 (gate debug) → ~50 (consolidate policy)

Category 1: OBSOLETE (54 vars - REMOVE)

These variables control removed/deprecated features and should be deleted:

1.1 Background Processing (BG) - 9 vars

Status: BG system removed in 2025-12 cleanup

HAKMEM_BATCH_BG
HAKMEM_L25_BG_DRAIN
HAKMEM_L25_BG_MS

Note: The following 2 Tiny BG vars were removed in commit 6b791b97d (2025-11-26):

HAKMEM_TINY_BG_REMOTE          (deleted)
HAKMEM_TINY_BG_REMOTE_BATCH    (deleted)

1.2 SFC (Shared Frontend Cache) - 7 vars

Status: SFC removed, replaced by UNIFIED_CACHE

HAKMEM_SFC_CAPACITY
HAKMEM_SFC_CASCADE_PCT
HAKMEM_SFC_DEBUG
HAKMEM_SFC_ENABLE
HAKMEM_SFC_REFILL_COUNT
HAKMEM_SFC_STATS_DUMP
HAKMEM_TINY_SFC_CASCADE

1.3 HotMag/UltraHot/Quick - 4 vars

Status: Experimental caches removed

HAKMEM_TINY_QUICK
HAKMEM_TINY_ULTRA
HAKMEM_TINY_ULTRA_VALIDATE
HAKMEM_TINY_ULTRA_SLIM

Note: The following 6 vars were removed in commit 6b791b97d (2025-11-26):

HAKMEM_TINY_ULTRA_FRONT        (deleted)
HAKMEM_TINY_ULTRA_L0           (deleted)
HAKMEM_TINY_ULTRA_HEAP_DUMP    (deleted)
HAKMEM_TINY_ULTRA_PAGE_DUMP    (deleted)
HAKMEM_TINY_BG_REMOTE          (deleted)
HAKMEM_TINY_BG_REMOTE_BATCH    (deleted)

1.4 Ring Cache - 4 vars

Status: Ring system removed

HAKMEM_L25_RING_TRIGGER
HAKMEM_POOL_TLS_RING
HAKMEM_RING_RETURN_DIV
HAKMEM_TINY_ALLOC_RING
HAKMEM_TINY_DUMP_RING_ATEXIT
HAKMEM_TINY_SLL_RING
HAKMEM_TINY_TRACE_RING

1.5 Thread Cache (TC) - 4 vars

Status: TC system deprecated

1.6 L25 BigCache - 8 vars

Status: BigCache system removed

HAKMEM_BIGCACHE_L25
HAKMEM_DISABLE_BIGCACHE
HAKMEM_L25_BG_DRAIN
HAKMEM_L25_BG_MS
HAKMEM_L25_RING_TRIGGER
HAKMEM_L25_TC_CAP
HAKMEM_L25_TC_SPILL

1.7 Frontend Experiments - 10 vars

Status: Experimental frontends (V2, Heap, Slim) removed

HAKMEM_TINY_FASTCACHE
HAKMEM_TINY_FRONTEND
HAKMEM_TINY_FRONT_DISABLE_HEAPV2
HAKMEM_TINY_FRONT_ENABLE_ULTRAHOT
HAKMEM_TINY_FRONT_SLIM
HAKMEM_TINY_FRONT_V2
HAKMEM_TINY_HEAP_V2_CLASS_MASK
HAKMEM_TINY_HEAP_V2_DEBUG
HAKMEM_TINY_HEAP_V2_LEFTOVER_MODE
HAKMEM_TINY_HEAP_V2_STATS

Category 2: DEBUG_ONLY (59 vars - COMPILE-TIME GATE)

These should be gated with #if !HAKMEM_BUILD_RELEASE and removed from production:

2.1 Tracing/Logging - 20 vars

HAKMEM_ADAPTIVE_LOG
HAKMEM_EXTERNAL_GUARD_LOG
HAKMEM_FREE_ROUTE_TRACE
HAKMEM_FREE_WRAP_TRACE
HAKMEM_INVALID_FREE_LOG
HAKMEM_LOG_FILE
HAKMEM_PTR_TRACE_DUMP
HAKMEM_PTR_TRACE_VERBOSE
HAKMEM_SUPER_REG_REQTRACE
HAKMEM_TIMING
HAKMEM_TINY_MAILBOX_TRACE
HAKMEM_TINY_MAILBOX_TRACE_LIMIT
HAKMEM_TINY_RF_TRACE
HAKMEM_TINY_SUPERSLAB_TRACE
HAKMEM_TINY_TRACE_RING
HAKMEM_VERBOSE

2.2 Statistics/Profiling - 18 vars

HAKMEM_ACE_PROFILE
HAKMEM_ACE_SAMPLE
HAKMEM_EVO_SAMPLE
HAKMEM_EXTERNAL_GUARD_STATS
HAKMEM_HIST_SAMPLE
HAKMEM_INT_SAMPLE
HAKMEM_LEARN_SAMPLE
HAKMEM_POOL_COUNT_SAMPLE
HAKMEM_PROF
HAKMEM_PROF_SAMPLE
HAKMEM_ROUTE_SAMPLE_LG
HAKMEM_SFC_STATS_DUMP
HAKMEM_SHARED_POOL_LOCK_STATS
HAKMEM_SHARED_POOL_STAGE_STATS
HAKMEM_TINY_ALLOC_1024_METRIC
HAKMEM_TINY_COUNT_SAMPLE
HAKMEM_TINY_FAST_STATS
HAKMEM_TINY_FRONT_METRICS

2.3 Debug/Validation - 21 vars

HAKMEM_ACE_DEBUG
HAKMEM_ACE_OBSERVE
HAKMEM_DEBUG_SEGV
HAKMEM_EXTERNAL_GUARD_LOG
HAKMEM_EXTERNAL_GUARD_MINCORE
HAKMEM_EXTERNAL_GUARD_STATS
HAKMEM_PTR_TRACE_DUMP
HAKMEM_SFC_DEBUG
HAKMEM_SFC_STATS_DUMP
HAKMEM_SS_ACQUIRE_DEBUG
HAKMEM_SS_FREE_DEBUG
HAKMEM_SS_LRU_DEBUG
HAKMEM_SS_PREWARM_DEBUG
HAKMEM_SUPER_LOOKUP_DEBUG
HAKMEM_SUPER_REG_DEBUG
HAKMEM_TINY_ALLOC_DEBUG
HAKMEM_TINY_COUNTERS_DUMP
HAKMEM_TINY_DEBUG_FAST0
HAKMEM_TINY_DEBUG_REMOTE_GUARD
HAKMEM_TINY_DUMP_ATEXIT_ONLY
HAKMEM_TINY_DUMP_RING_ATEXIT

Category 3: ESSENTIAL (20 vars - KEEP)

Core functionality that must remain:

3.1 Major Features (8 vars)

HAKMEM_TINY_UNIFIED_CACHE=1      # Phase 3d-B (default ON)
HAKMEM_SS_EMPTY_REUSE=1          # Phase 12-1.1 (default ON)
HAKMEM_FRONT_GATE_UNIFIED=1      # Phase 26 (default ON)
HAKMEM_WRAP_TINY=1               # Enable Tiny Pool
HAKMEM_TINY_USE_SUPERSLAB=1      # SuperSlab backend
HAKMEM_TINY_TLS_SLL=1            # TLS cache layer
HAKMEM_TINY_FREE_FAST=1          # Fast free path
HAKMEM_POOL_TLS_FREE=1           # Pool TLS free

3.2 Pool TLS Arena (3 vars)

HAKMEM_POOL_TLS_ARENA_MB_INIT=1  # Initial arena size
HAKMEM_POOL_TLS_ARENA_MB_MAX=8   # Max arena size
HAKMEM_POOL_TLS_ARENA_GROWTH_LEVELS=3  # Growth stages

3.3 Page Arena (5 vars)

HAKMEM_PAGE_ARENA_ENABLE=1       # Page arena system
HAKMEM_PAGE_ARENA_HOT_SIZE=...   # Hot size threshold
HAKMEM_PAGE_ARENA_WARM_64K=...   # Warm level 1
HAKMEM_PAGE_ARENA_WARM_128K=...  # Warm level 2
HAKMEM_PAGE_ARENA_WARM_2M=...    # Warm level 3

3.4 Misc Essential (4 vars)

HAKMEM_PREWARM_SUPERSLABS=1      # Phase 11 prewarm
HAKMEM_TINY_PREWARM_ALL=1        # Full prewarm
HAKMEM_WRAP_TINY_REFILL=1        # Wrapper refill
HAKMEM_SMALLMID_ENABLE=1         # SmallMid allocator

Category 4: POLICY (149 vars - CONSOLIDATE to ~30)

4.1 Duplicate/Similar Functionality

Refill Parameters (18 vars → 3 vars)

Current:

HAKMEM_INT_ADAPT_REFILL
HAKMEM_SFC_REFILL_COUNT
HAKMEM_TINY_MID_REFILL_SIMPLE
HAKMEM_TINY_REFILL_COUNT
HAKMEM_TINY_REFILL_COUNT_HOT
HAKMEM_TINY_REFILL_COUNT_MID
HAKMEM_TINY_REFILL_DUMP
HAKMEM_TINY_REFILL_FAILFAST
HAKMEM_TINY_REFILL_MAX
HAKMEM_TINY_REFILL_MAX_HOT
HAKMEM_TINY_REFILL_ONE_ON_MISS
HAKMEM_TINY_REFILL_OPT_DEBUG
HAKMEM_WRAP_TINY_REFILL

Proposal: Consolidate to:

HAKMEM_TINY_REFILL_BATCH=64      # Default batch size
HAKMEM_TINY_REFILL_HOT_BATCH=192 # Hot class batch
HAKMEM_TINY_REFILL_MAX=1024      # Global max

Capacity Parameters (25 vars → 5 vars)

Current:

HAKMEM_CAP_LARGE
HAKMEM_CAP_MID
HAKMEM_CAP_MID_DYN1
HAKMEM_CAP_MID_DYN2
HAKMEM_L25_MIN_BUNDLE
HAKMEM_MF2_MAX_QUEUES
HAKMEM_POOL_MIN_BUNDLE
HAKMEM_SUPERSLAB_MAX_CACHED
HAKMEM_SUPERSLAB_MAX_MEMORY_MB
HAKMEM_TINY_MAX_CLASS
HAKMEM_TINY_REFILL_MAX_HOT
HAKMEM_TINY_SS_MAX_MB
HAKMEM_TINY_SS_MIN_MB
...(25 total)

Proposal: Use tiered approach:

HAKMEM_TINY_CACHE_SIZE=small|medium|large  # Preset
HAKMEM_MID_CACHE_SIZE=small|medium|large
HAKMEM_LARGE_CACHE_SIZE=small|medium|large
HAKMEM_SS_MEMORY_LIMIT_MB=512    # Global limit
HAKMEM_POOL_MEMORY_LIMIT_MB=256  # Pool limit

Learning/Adaptation (35 vars → 8 vars)

Current: ACE, INT, WMAX, THP, ELO, LEARN, ADAPTIVE, HOT, DYN systems

HAKMEM_ACE_DEBUG
HAKMEM_ACE_ENABLED
HAKMEM_ACE_OBSERVE
HAKMEM_ACE_PROFILE
HAKMEM_ACE_SAMPLE
HAKMEM_ADAPTIVE_LOG
HAKMEM_ADAPTIVE_SIZING
HAKMEM_CAP_MID_DYN1
HAKMEM_CAP_MID_DYN2
HAKMEM_DISABLE_ELO
HAKMEM_DYN1_AUTO
HAKMEM_DYN2_AUTO
HAKMEM_INT_ADAPT_CAPS
HAKMEM_INT_ADAPT_REFILL
HAKMEM_INT_ENGINE
...(35 total)

Proposal: Unified learning system:

HAKMEM_LEARN_MODE=off|observe|active     # Master switch
HAKMEM_LEARN_TARGETS=caps,refill,wmax    # What to tune
HAKMEM_LEARN_INTERVAL_MS=1000            # Update rate
HAKMEM_LEARN_AGGRESSIVENESS=0.1          # Tuning rate
HAKMEM_THP_POLICY=off|auto|on            # THP
HAKMEM_ADAPTIVE_CAPS=1                   # Enable cap adaptation
HAKMEM_ADAPTIVE_REFILL=1                 # Enable refill adaptation
HAKMEM_ADAPTIVE_WMAX=1                   # Enable wmax adaptation

Drain/Threshold Parameters (20 vars → 5 vars)

Current:

HAKMEM_L25_BG_DRAIN
HAKMEM_L25_RING_TRIGGER
HAKMEM_MF2_IDLE_THRESHOLD_US
HAKMEM_TC_DRAIN_MAX
HAKMEM_TC_DRAIN_TRIGGER
HAKMEM_TINY_DRAIN_TO_SLL
HAKMEM_TINY_REMOTE_DRAIN_THRESHOLD
HAKMEM_TINY_REMOTE_DRAIN_TRYRATE
HAKMEM_TINY_SLL_DRAIN_DEBUG
HAKMEM_TINY_SLL_DRAIN_ENABLE
HAKMEM_TINY_SLL_DRAIN_INTERVAL
HAKMEM_TINY_TENSION_DRAIN_ENABLE
HAKMEM_TINY_TENSION_DRAIN_THRESHOLD
...(20 total)

Proposal: Unified thresholds:

HAKMEM_REMOTE_DRAIN_THRESHOLD=32   # When to drain
HAKMEM_REMOTE_DRAIN_BATCH=16       # Drain batch size
HAKMEM_SPILL_THRESHOLD_PCT=90      # Cache spill %
HAKMEM_TRIM_INTERVAL_MS=1000       # Memory trim rate
HAKMEM_IDLE_TIMEOUT_MS=5000        # Idle detection

4.2 Recommended Consolidation Summary

Area Current Proposed Reduction
Refill params 18 3 -83%
Capacity params 25 5 -80%
Learning/Adapt 35 8 -77%
Drain/Threshold 20 5 -75%
L25/Pool config 15 5 -67%
Misc policy 36 4 -89%
TOTAL 149 30 -80%

Final Reduction Path

Step 1: Remove OBSOLETE             282 → 228 (-54)
Step 2: Gate DEBUG with #if         228 → 169 (-59)
Step 3: Keep ESSENTIAL as-is        169 → 149 (-20)
Step 4: Consolidate POLICY          149 → 30  (-119)

FINAL COUNT: 20 (essential) + 30 (policy) = 50 variables

Top Removal Candidates (By Priority)

Priority 1: Dead Code (Immediate Removal) - 54 vars

BG System (11 vars):

HAKMEM_L25_BG_DRAIN
HAKMEM_L25_BG_MS

SFC System (7 vars):

HAKMEM_SFC_CAPACITY
HAKMEM_SFC_CASCADE_PCT
HAKMEM_SFC_DEBUG
HAKMEM_SFC_ENABLE
HAKMEM_SFC_REFILL_COUNT
HAKMEM_SFC_STATS_DUMP
HAKMEM_TINY_SFC_CASCADE

Experimental Caches (4 vars):

HAKMEM_TINY_QUICK
HAKMEM_TINY_ULTRA
HAKMEM_TINY_ULTRA_VALIDATE
HAKMEM_TINY_ULTRA_SLIM

Note: 6 Ultra/BG vars removed in commit 6b791b97d (see section 1.3 above)

Ring/TC/Frontend (18 vars):

HAKMEM_L25_RING_TRIGGER
HAKMEM_L25_TC_CAP
HAKMEM_L25_TC_SPILL
HAKMEM_MID_TC_CAP
HAKMEM_POOL_TLS_RING
HAKMEM_RING_RETURN_DIV
HAKMEM_TC_DRAIN_MAX
HAKMEM_TC_DRAIN_TRIGGER
HAKMEM_TC_ENABLE
HAKMEM_TC_UNBOUNDED
HAKMEM_TINY_ALLOC_RING
HAKMEM_TINY_DUMP_RING_ATEXIT
HAKMEM_TINY_FASTCACHE
HAKMEM_TINY_FRONT_V2
HAKMEM_TINY_HEAP_V2_CLASS_MASK
HAKMEM_TINY_HEAP_V2_DEBUG
HAKMEM_TINY_HEAP_V2_LEFTOVER_MODE
HAKMEM_TINY_HEAP_V2_STATS

Priority 2: Debug Gate (Next Phase) - 59 vars

Move to #if !HAKMEM_BUILD_RELEASE block:

HAKMEM_ACE_DEBUG
HAKMEM_ACE_OBSERVE
HAKMEM_ACE_PROFILE
HAKMEM_ADAPTIVE_LOG
HAKMEM_DEBUG_SEGV
HAKMEM_EXTERNAL_GUARD_LOG
HAKMEM_EXTERNAL_GUARD_MINCORE
HAKMEM_EXTERNAL_GUARD_STATS
HAKMEM_FREE_ROUTE_TRACE
HAKMEM_FREE_WRAP_TRACE
HAKMEM_INVALID_FREE_LOG
HAKMEM_LOG_FILE
HAKMEM_PROF
HAKMEM_PROF_SAMPLE
HAKMEM_PTR_TRACE_DUMP
HAKMEM_PTR_TRACE_VERBOSE
HAKMEM_SFC_DEBUG
HAKMEM_SFC_STATS_DUMP
HAKMEM_SHARED_POOL_LOCK_STATS
HAKMEM_SHARED_POOL_STAGE_STATS
HAKMEM_SS_ACQUIRE_DEBUG
HAKMEM_SS_FREE_DEBUG
HAKMEM_SS_LRU_DEBUG
HAKMEM_SS_PREWARM_DEBUG
HAKMEM_SUPER_LOOKUP_DEBUG
HAKMEM_SUPER_REG_DEBUG
HAKMEM_SUPER_REG_REQTRACE
HAKMEM_TINY_ALLOC_DEBUG
HAKMEM_TINY_COUNTERS_DUMP
HAKMEM_TINY_DEBUG_FAST0
...(59 total)

Priority 3: Policy Consolidation (Final Phase) - 119 vars

High-impact consolidation targets:

  1. Per-class overrides (30+ vars): Remove HAKMEM_TINY_*_C{0..7}, use class-agnostic tuning
  2. Learning systems (35 vars): Unify ACE/INT/WMAX/ELO into HAKMEM_LEARN_*
  3. Capacity limits (25 vars): Use tiered presets (small/medium/large)
  4. Drain thresholds (20 vars): Unify under HAKMEM_DRAIN_* namespace

Undocumented Variables

Variables in code but not in ENV_VARS.md:

(Run: comm -13 <(grep -o 'HAKMEM_[A-Z_0-9]*' ENV_VARS.md | sort -u) <(grep -rh 'getenv("HAKMEM_' core/ | grep -o 'HAKMEM_[A-Z_0-9]*' | sort -u))

Recommended Actions

Phase 1: Remove OBSOLETE (Week 1)

  • Remove all BG system ENV vars (11 vars)
  • Remove all SFC system ENV vars (7 vars)
  • Remove HotMag/Ultra/Quick ENV vars (10 vars)
  • Remove Ring/TC ENV vars (8 vars)
  • Remove experimental frontend ENV vars (18 vars)
  • Result: 282 → 228 vars (-19%)

Phase 2: Gate DEBUG (Week 2)

  • Create core/hakmem_debug_env.h with #if !HAKMEM_BUILD_RELEASE
  • Move all *_DEBUG, *_TRACE, *_STATS, *_DUMP vars
  • Move all *_LOG, *_PROF, *_OBSERVE vars
  • Update build.sh to strip debug ENV in release
  • Result: 228 → 169 vars (-21% production)

Phase 3: Consolidate POLICY (Week 3-4)

  • Consolidate REFILL_* params (18 → 3)
  • Consolidate CAP_/MAX_/MIN_ params (25 → 5)
  • Unify learning systems (35 → 8)
  • Consolidate drain thresholds (20 → 5)
  • Simplify L25/Pool config (15 → 5)
  • Merge misc policy vars (36 → 4)
  • Result: 169 → 50 vars (-82% total)

Phase 4: Document & Test (Week 5)

  • Update ENV_VARS.md with final 50 vars
  • Create ENV_MIGRATION_GUIDE.md for old→new mapping
  • Add ENV validation warnings for removed vars
  • Regression test all 50 vars
  • Update CLAUDE.md with new ENV list