hakmem/CURRENT_TASK.md

Current Task: Phase 9-2 Refactoring (Complete) & Phase 10 Preparation

Date: 2025-12-01 Status: COMPLETE (Phase 9-2) / PLANNING (Phase 10) Goal: Legacy Backend Removal, Shared Pool Unification, and Type Safety

---

Phase 9-2 Achievements (Completed)

1. Legacy Backend Removal & Unification (2025-12-01)

   • Eliminated Fallback: Removed hak_tiny_alloc_superslab_backend_legacy fallback. Shared Pool is now the sole backend (hak_tiny_alloc_superslab_box -> hak_tiny_alloc_superslab_backend_shared).
   • Soft Cap Removed: Removed the artificial "Soft Cap" limit in Shared Pool Stage 3, allowing it to handle full workload load.
   • EMPTY Recycling: Implemented SLAB_TRY_RECYCLE with atomic batch decrement of meta->used in _ss_remote_drain_to_freelist_unsafe. This ensures EMPTY slabs are immediately returned to the global pool.
   • Race Condition Fix: Moved remove_superslab_from_legacy_head(ss) to the start of shared_pool_release_slab to prevent Legacy Backend from allocating from a slab being recycled. Added total_active_blocks check before freeing.
   • Performance: 50.3 M ops/s in WS8192 benchmark (vs 16.5 M baseline). OOM/Crash issues resolved.

2. Critical Fixes (Deadlock & OOM)

   • Deadlock: shared_pool_acquire_slab releases alloc_lock before superslab_allocate.
   • Is Empty Return: tiny_free_local_box now returns int is_empty status to allow safe, race-free recycling by the caller.

3. Code Refactoring

   • Modularized hakmem_shared_pool.c into acquire/release/internal components.

---

Next Phase: Phase 10 - Type Safety & Hardening

1. Pointer Type Safety (Debug Only)

• Issue: Occasional [TLS_SLL_HDR_RESET] warnings indicate confusion between BasePtr (header start) and UserPtr (payload start).
• Solution: Implement "Phantom Type" checking macros enabled only in debug builds.
  • Define hak_base_ptr_t and hak_user_ptr_t structs in debug.
  • Define strict conversion macros (hak_base_to_user, hak_user_to_base).
  • Apply incrementally to tls_sll_box, free_local_box, and remote_free_box.
  • Goal: Catch pointer arithmetic errors at compile time in debug mode.

2. Header Protection Hardening

• Goal: Reinforce header integrity checks in tiny_free_local_box and tls_sll_pop using the new type system.

3. Fast Path Optimization

• Goal: Re-evaluate hot path performance (Stage 1 lock-free) after Phase 9-2 stabilization.

---

Current Status

• Build: Passing (Clean build verified).
• Benchmarks:
  • WS8192: 50.3 M ops/s (Shared Pool ONLY).
  • Crash/OOM: Resolved.
• Pending: Phase 10 implementation (Type Safety).