hakmem/docs/analysis/ENV_CLEANUP_PLAN.md

OBSOLETE ENV Cleanup Plan

Summary

• Total ENV vars in codebase: 221
• Potentially OBSOLETE vars: 54
• Files affected: 73
• Safe to remove immediately: 18 (Priority 1)
• Need verification: 36 (Priority 2-3)

---

Priority 1: 100% Safe Removals (Already Removed Code)

These ENV variables reference features that were completely removed in commits bcfb4f6b5 and 225b6fcc7 but ENV checks were left behind:

Removed Features:

• UltraHot (core/front/tiny_ultra_hot.h - removed bcfb4f6b5)
• RingCache (core/front/tiny_ring_cache.* - removed bcfb4f6b5)
• FrontC23 (core/front/tiny_front_c23.h - removed bcfb4f6b5)
• Class5 Hotpath (removed bcfb4f6b5)

ENV Variables (18 vars, SAFE TO DELETE):

No references found in current codebase - these can be removed immediately:

HAKMEM_TINY_ULTRA_HOT            ✅ Removed
HAKMEM_TINY_ULTRA_HOT_MAX_SIZE   ✅ Removed
HAKMEM_TINY_ULTRA_HOT_STATS      ✅ Removed
HAKMEM_TINY_HOT_RING_ENABLE      ✅ Removed
HAKMEM_TINY_HOT_RING_C2          ✅ Removed
HAKMEM_TINY_HOT_RING_C3          ✅ Removed
HAKMEM_TINY_HOT_RING_C5          ✅ Removed
HAKMEM_TINY_HOT_RING_CASCADE     ✅ Removed
HAKMEM_TINY_FRONT_C23            ✅ Removed
HAKMEM_TINY_CLASS5_HOTPATH       ✅ Removed
HAKMEM_TINY_CLASS5_STATS_DUMP    ✅ Removed

RESULT: No cleanup needed - already removed! ✅

---

Priority 2: Features Still Compiled But Possibly Unused

These features exist as files and are compiled into binaries, but may be disabled by default or experimental:

2A. SFC (Shared Frontend Cache) - ⚠️ ACTIVE (Default: ON)

Status: ACTIVE and compiled into all binaries (hakmem_tiny_sfc.o) Default: g_sfc_enabled = 1 (ON by default!) Decision: KEEP - This is an active optimization

ENV Variables (6 vars):

File: core/hakmem_tiny_sfc.c
- Line 51:  getenv("HAKMEM_SFC_ENABLE")           # A/B toggle
- Line 62:  getenv("HAKMEM_SFC_CAPACITY")         # Tuning
- Line 71:  getenv("HAKMEM_SFC_REFILL_COUNT")     # Tuning
- Line 123: getenv("HAKMEM_SFC_DEBUG")            # Debug
- Line 144: getenv("HAKMEM_SFC_STATS_DUMP")       # Stats

File: core/tiny_alloc_fast.inc.h
- Line 477: getenv("HAKMEM_SFC_CASCADE_PCT")      # Advanced tuning

File: core/tiny_alloc_fast_sfc.inc.h
- Line 114: getenv("HAKMEM_SFC_DEBUG")            # Debug (duplicate)

File: core/tiny_free_fast.inc.h
- Line 104: getenv("HAKMEM_SFC_DEBUG")            # Debug (duplicate)

File: core/box/hak_wrappers.inc.h
- Line 89:  getenv("HAKMEM_SFC_DEBUG")            # Debug (duplicate)

Action: KEEP ALL (active feature)

---

2B. BG (Background System) - ⚠️ PARTIALLY ACTIVE

Status: Files exist, compiled in (hakmem_tiny_bg_spill.o, hakmem_batch.o) Default: g_bg_enabled = 1 in hakmem_batch.c Compiled: YES (hakmem_batch.o, hakmem_tiny_bg_spill.o in OBJS_BASE)

ENV Variables (5+ vars):

File: core/hakmem_batch.c
- Line 73: getenv("HAKMEM_BATCH_BG")              # Enable/disable

File: core/hakmem_l25_pool.c (L25 BG drain)
- Line 741: getenv("HAKMEM_L25_BG_DRAIN")         # L25 specific
- Line 743: getenv("HAKMEM_L25_BG_MS")            # Interval

File: core/hakmem_tiny_remote_target.c
- HAKMEM_TINY_BG_REMOTE (referenced in comments, no getenv found)
- HAKMEM_TINY_BG_REMOTE_BATCH (referenced in comments)

Action: VERIFY with user - if BG system is deprecated, can remove 5 vars

---

2C. TC (Thread Cache for L25/MidPool) - ⚠️ ACTIVE

Status: ACTIVE for Pool/L25 allocations Compiled: YES (part of hakmem_l25_pool.o, mid_tcache.h) Default: Enabled in some paths

ENV Variables (10 vars):

File: core/hakmem_l25_pool.c (L25 Pool TC)
- Line 737: getenv("HAKMEM_L25_TC_SPILL")         # Spill threshold
- Line 739: getenv("HAKMEM_L25_TC_CAP")           # TC capacity

File: core/mid_tcache.h (Mid Pool TC)
- Line 16: getenv("HAKMEM_MID_TC")                # Enable
- Line 25: getenv("HAKMEM_MID_TC_CAP")            # Capacity

File: core/box/pool_init_api.inc.h (Generic TC)
- Line 72: getenv("HAKMEM_TC_ENABLE")             # Enable
- Line 74: getenv("HAKMEM_TC_UNBOUNDED")          # Mode
- Line 76: getenv("HAKMEM_TC_DRAIN_MAX")          # Drain max
- Line 78: getenv("HAKMEM_TC_DRAIN_TRIGGER")      # Drain trigger

File: core/hakmem_batch.c (Batch system)
- HAKMEM_DISABLE_BATCH (referenced, may relate to TC)

Action: KEEP - TC is active for Pool allocations

---

2D. Ultra Features - ⚠️ EXPERIMENTAL/GATED

Status: Files exist but ENV-gated (disabled by default) Compiled: Files exist but likely inactive Default: Disabled/experimental

ENV Variables (8 vars):

File: core/front/tiny_ultrafront.h
- getenv("HAKMEM_TINY_ULTRA_FRONT")               # UltraFront variant

File: core/ultra/tiny_ultra_heap.c
- getenv("HAKMEM_TINY_ULTRA_L0")                  # Ultra L0 layer
- getenv("HAKMEM_TINY_ULTRA_HEAP_DUMP")           # Debug dump

File: core/ultra/tiny_ultra_page_arena.c
- getenv("HAKMEM_TINY_ULTRA_PAGE_DUMP")           # Debug dump

File: core/box/ultra_slim_alloc_box.h
- getenv("HAKMEM_TINY_ULTRA_SLIM")                # UltraSlim mode
- getenv("HAKMEM_ULTRA_SLIM_STATS")               # Stats

File: core/box/hak_core_init.inc.h
- getenv("HAKMEM_TINY_ULTRA_DEBUG")               # Debug

Action: VERIFY - if Ultra features are experimental/unused, mark as deprecated

---

2E. Frontend V2/Heap V2 - ⚠️ POSSIBLY OBSOLETE

Status: ENV vars exist but feature may be replaced Compiled: Part of frontend code

ENV Variables (7 vars):

File: core/front/tiny_heap_v2.h
- getenv("HAKMEM_TINY_HEAP_V2_CLASS_MASK")        # Class mask
- getenv("HAKMEM_TINY_HEAP_V2_LEFTOVER_MODE")     # Leftover mode
- getenv("HAKMEM_TINY_HEAP_V2_DEBUG")             # Debug

File: core/tiny_alloc_fast.inc.h
- getenv("HAKMEM_TINY_HEAP_V2_STATS")             # Stats

File: core/box/front_metrics_box.h
- getenv("HAKMEM_TINY_FRONT_DISABLE_HEAPV2")      # Disable toggle

File: core/tiny_alloc_fast.inc.h
- getenv("HAKMEM_TINY_FRONT_V2")                  # Front V2 enable
- getenv("HAKMEM_TINY_FRONT_SLIM")                # Slim variant
- getenv("HAKMEM_TINY_FRONT_DIRECT")              # Direct mode
- getenv("HAKMEM_TINY_FRONT_METRICS")             # Metrics
- getenv("HAKMEM_TINY_FRONT_DUMP")                # Dump
- getenv("HAKMEM_TINY_FRONT_ENABLE_ULTRAHOT")     # UltraHot (obsolete?)

Action: VERIFY - Heap V2 status with user

---

2F. Ring/SLL Features - ⚠️ MIXED STATUS

Status: Some ring vars still in use (L25 TLS ring), others removed Compiled: Mixed

ENV Variables (6 vars):

File: core/hakmem_l25_pool.c (ACTIVE - L25 TLS ring)
- Line 718: getenv("HAKMEM_POOL_TLS_RING")        # ✅ ACTIVE
- Line 724: getenv("HAKMEM_RING_RETURN_DIV")      # ✅ ACTIVE
- Line 745: getenv("HAKMEM_L25_RING_TRIGGER")     # ✅ ACTIVE

File: core/box/pool_init_api.inc.h (ACTIVE)
- getenv("HAKMEM_POOL_TLS_RING")                  # ✅ ACTIVE (duplicate)
- getenv("HAKMEM_RING_RETURN_DIV")                # ✅ ACTIVE (duplicate)

File: core/box/tls_sll_box.h (SLL ring - may be different)
- Line 115: getenv("HAKMEM_TINY_SLL_RING")        # SLL variant ring

File: core/tiny_debug_ring.c (Debug ring)
- getenv("HAKMEM_TINY_TRACE_RING")                # Debug trace
- getenv("HAKMEM_TINY_DUMP_RING_ATEXIT")          # Dump at exit

Action:

• KEEP: HAKMEM_POOL_TLS_RING, HAKMEM_RING_RETURN_DIV, HAKMEM_L25_RING_TRIGGER (L25 active)
• VERIFY: HAKMEM_TINY_SLL_RING, HAKMEM_TINY_TRACE_RING, HAKMEM_TINY_DUMP_RING_ATEXIT

---

2G. HotMag / SmallMag - ⚠️ FILE EXISTS, STATUS UNCLEAR

Status: File exists (core/hakmem_tiny_hotmag.inc.h) but no active ENV refs Compiled: Likely included but no dedicated .o file

ENV Variables (1 var):

File: core/hakmem_tiny_smallmag.inc.h
- getenv("HAKMEM_TINY_SMALL_MAG")                 # Enable SmallMag

Action: VERIFY - check if HotMag/SmallMag are used or obsolete

---

2H. BigCache - ✅ ACTIVE

Status: ACTIVE and compiled (hakmem_bigcache.o) Compiled: YES (hakmem_bigcache.o in OBJS_BASE)

ENV Variables (1 var):

File: core/box/hak_free_api.inc.h
- getenv("HAKMEM_BIGCACHE_L25")                   # Enable BigCache for L25

Action: KEEP - BigCache is active

---

Priority 3: Verification Needed

These ENV variables need user/maintainer input:

3A. Experimental Features (Gated by ENV, Default OFF)

Need decision: Keep for experiments or remove?

HAKMEM_TINY_ULTRA_FRONT          # UltraFront experiment
HAKMEM_TINY_ULTRA_L0             # Ultra L0 layer
HAKMEM_TINY_ULTRA_SLIM           # UltraSlim mode
HAKMEM_TINY_HEAP_V2_*            # Heap V2 features (4 vars)
HAKMEM_TINY_FRONT_V2             # Frontend V2
HAKMEM_TINY_FRONT_SLIM           # Frontend Slim
HAKMEM_TINY_FRONT_ENABLE_ULTRAHOT # UltraHot toggle (feature removed!)

3B. Debug/Stats Variables

Keep for debugging or remove?

HAKMEM_SFC_DEBUG                 # SFC debug (4 duplicate locations!)
HAKMEM_TINY_ULTRA_DEBUG          # Ultra debug
HAKMEM_TINY_ULTRA_HEAP_DUMP      # Ultra heap dump
HAKMEM_TINY_ULTRA_PAGE_DUMP      # Ultra page dump
HAKMEM_ULTRA_SLIM_STATS          # UltraSlim stats
HAKMEM_TINY_HEAP_V2_DEBUG        # Heap V2 debug
HAKMEM_TINY_FRONT_METRICS        # Front metrics
HAKMEM_TINY_FRONT_DUMP           # Front dump
HAKMEM_TINY_TRACE_RING           # Debug ring trace
HAKMEM_TINY_DUMP_RING_ATEXIT     # Dump ring at exit

---

Execution Plan

Phase 1: Remove Duplicate/Dead Code (Immediate)

NO ACTION NEEDED - Already cleaned in bcfb4f6b5 and 225b6fcc7 ✅

Phase 2: Consolidate Duplicate Debug Checks (Low Risk)

File: core/tiny_alloc_fast_sfc.inc.h, core/tiny_free_fast.inc.h, core/box/hak_wrappers.inc.h

Problem: getenv("HAKMEM_SFC_DEBUG") called 4 times in different files

Fix: Create single global g_sfc_debug variable, set once in sfc_init()

Lines to modify:

• core/hakmem_tiny_sfc.c:123 - Keep this one (in init)
• core/tiny_alloc_fast_sfc.inc.h:114 - Change to extern int g_sfc_debug
• core/tiny_free_fast.inc.h:104 - Change to extern int g_sfc_debug
• core/box/hak_wrappers.inc.h:89 - Change to extern int g_sfc_debug

Impact: Reduces 3 getenv() calls per debug check to 1 at init

Phase 3: Verify Experimental Features (Needs Input)

Questions for user/maintainer:

1. Ultra features - Are these experiments still active?

   • HAKMEM_TINY_ULTRA_FRONT
   • HAKMEM_TINY_ULTRA_L0
   • HAKMEM_TINY_ULTRA_SLIM
   • HAKMEM_ULTRA_SLIM_STATS

2. Heap V2 - Is this still used or replaced?

   • HAKMEM_TINY_HEAP_V2_* (4 vars)

3. Frontend variants - Which are active?

   • HAKMEM_TINY_FRONT_V2
   • HAKMEM_TINY_FRONT_SLIM
   • HAKMEM_TINY_FRONT_ENABLE_ULTRAHOT (should remove - UltraHot deleted!)

4. BG system - Still needed?

   • HAKMEM_BATCH_BG
   • HAKMEM_L25_BG_DRAIN
   • HAKMEM_L25_BG_MS

5. HotMag/SmallMag - Used or obsolete?

   • HAKMEM_TINY_SMALL_MAG

Phase 4: Mark Deprecated (If Removing)

Add to documentation:

## Deprecated ENV Variables (Removed in vX.X)

The following ENV variables are deprecated and no longer have any effect:
- HAKMEM_TINY_FRONT_ENABLE_ULTRAHOT (feature removed in bcfb4f6b5)
- [Add others after verification]

---

Summary Table

Category	Total Vars	Status	Action
Already Removed	11	✅ Clean	None
SFC (Active)	6	✅ Keep	Deduplicate debug
BG System	5	⚠️ Verify	Need input
TC (Thread Cache)	10	✅ Keep	None
Ultra Features	8	⚠️ Verify	Need input
Heap V2	7	⚠️ Verify	Need input
Ring/SLL	6	🟡 Mixed	Keep L25, verify Tiny
HotMag/SmallMag	1	⚠️ Verify	Need input
BigCache	1	✅ Keep	None
TOTAL	55

---

Next Steps

1. User decision needed: Verify experimental features (Phase 3 questions)
2. Quick win: Deduplicate SFC_DEBUG checks (Phase 2)
3. Documentation: Mark deprecated vars
4. Testing: Ensure no ENV var removal breaks existing users
5. Gradual removal: Deprecate → warn → remove (3-release cycle)

---

Files Requiring Modification

Immediate Changes (Phase 2 - SFC Debug Deduplication):

• core/hakmem_tiny_sfc.c (add global)
• core/tiny_alloc_fast_sfc.inc.h (change to extern)
• core/tiny_free_fast.inc.h (change to extern)
• core/box/hak_wrappers.inc.h (change to extern)

Pending Verification (Phase 3):

• core/front/tiny_ultrafront.h
• core/front/tiny_heap_v2.h
• core/ultra/tiny_ultra_heap.c
• core/ultra/tiny_ultra_page_arena.c
• core/box/ultra_slim_alloc_box.h
• core/hakmem_batch.c
• core/hakmem_l25_pool.c
• core/hakmem_tiny_smallmag.inc.h
• core/tiny_alloc_fast.inc.h
• core/box/front_metrics_box.h

Total files: ~14 files need review/modification

---

Risk Assessment

• Phase 1: ✅ Zero risk (already done)
• Phase 2: 🟢 Low risk (internal optimization, no behavior change)
• Phase 3: 🟡 Medium risk (need verification, user-facing)
• Phase 4: 🔴 High risk (breaking change, needs deprecation cycle)

Recommendation: Start with Phase 2 (safe), then get user input for Phase 3.