hakmem/docs/archive/MAINLINE_INTEGRATION.md

Mainline Integration Plan (Tiny focus)

> **⚠️ ARCHIVE NOTICE (2025-11-26)**
> Several ENV variables and files referenced in this document were removed in commit 6b791b97d:
> - `HAKMEM_TINY_BG_REMOTE` (deleted)
> - `HAKMEM_TINY_BG_REMOTE_BATCH` (deleted)
>
> This document is kept for historical reference but may contain outdated information.

What we promoted to mainline (safe, general)
- Safer tiny refill into SLL (already integrated)
  - `sll_refill_small_from_ss(class_idx, max_take)` now caps refill by the actual SLL free capacity, avoiding overtake and wasted meta->used increments.
- Entry order consolidation in the small fast path
  - Prefer `SLL → Magazine → SuperSlab` in the normal (non‑bench) path; Quick/FrontCache/Ultra tiers remain opt‑in.
- Targeted remote‑drain queue (compiled in, default OFF)
  - Per‑class Treiber queue for slabs that exceed remote thresholds; disabled by default via env knobs to preserve conservative behavior.
- PGO recipe (opt‑in)
  - Makefile targets for PGO on tiny benches are available, but not required for normal builds.

What remains bench‑only (NOT promoted)
- SLL‑only front (Magazine compiled out) and TLS warmup
  - These are highly benchmark‑specific and are kept in bench‑only builds.
- Free‑side SLL‑first push without owner/stats
  - Mainline preserves learning/stats semantics; bench builds can cut them out.
- Quick/FrontCache / 32/64 specialization hardwiring
  - Retained as A/B options; not enabled by default in mainline.

Recommended “Perf‑Main” preset (opt‑in, no bench macros)
- Environment (Tiny‑Hot biased but general):
  - `HAKMEM_TINY_TLS_SLL=1`
  - `HAKMEM_TINY_REFILL_MAX=96`
  - `HAKMEM_TINY_REFILL_MAX_HOT=192`
  - `HAKMEM_TINY_SPILL_HYST=16`
  - `HAKMEM_TINY_BG_REMOTE=0` (keep targeted remote drain off by default)
  - Keep Quick/FrontCache/Ultra OFF unless explicitly A/B tested

How to try Perf‑Main locally
- Build benches: `make bench_fast`
- Run tiny‑hot triad (no bench macros): `bash scripts/run_tiny_hot_triad.sh 60000`
- Run random‑mixed matrix: `bash scripts/run_random_mixed_matrix.sh 100000`

Notes
- LD_PRELOAD/app mode remains conservative (LD_SAFE staging). Tiny‑only and pass‑through modes are recommended for stability. The bench‑only optimizations are intentionally not applied in LD mode.
-												Debug Counters Implementation - Clean History

Major Features:
- Debug counter infrastructure for Refill Stage tracking
- Free Pipeline counters (ss_local, ss_remote, tls_sll)
- Diagnostic counters for early return analysis
- Unified larson.sh benchmark runner with profiles
- Phase 6-3 regression analysis documentation

Bug Fixes:
- Fix SuperSlab disabled by default (HAKMEM_TINY_USE_SUPERSLAB)
- Fix profile variable naming consistency
- Add .gitignore patterns for large files

Performance:
- Phase 6-3: 4.79 M ops/s (has OOM risk)
- With SuperSlab: 3.13 M ops/s (+19% improvement)

This is a clean repository without large log files.

🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>

											
										
										
											2025-11-05 12:31:14 +09:00
+								Mainline Integration Plan (Tiny focus)
-												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
+								> **⚠️ ARCHIVE NOTICE (2025-11-26)**
 								> Several ENV variables and files referenced in this document were removed in commit 6b791b97d:
 								> - `HAKMEM_TINY_BG_REMOTE` (deleted)
 								> - `HAKMEM_TINY_BG_REMOTE_BATCH` (deleted)
 								>
 								> This document is kept for historical reference but may contain outdated information.
-												Debug Counters Implementation - Clean History

Major Features:
- Debug counter infrastructure for Refill Stage tracking
- Free Pipeline counters (ss_local, ss_remote, tls_sll)
- Diagnostic counters for early return analysis
- Unified larson.sh benchmark runner with profiles
- Phase 6-3 regression analysis documentation

Bug Fixes:
- Fix SuperSlab disabled by default (HAKMEM_TINY_USE_SUPERSLAB)
- Fix profile variable naming consistency
- Add .gitignore patterns for large files

Performance:
- Phase 6-3: 4.79 M ops/s (has OOM risk)
- With SuperSlab: 3.13 M ops/s (+19% improvement)

This is a clean repository without large log files.

🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>

											
										
										
											2025-11-05 12:31:14 +09:00
+								What we promoted to mainline (safe, general)
 								- Safer tiny refill into SLL (already integrated)
 								  - `sll_refill_small_from_ss(class_idx, max_take)` now caps refill by the actual SLL free capacity, avoiding overtake and wasted meta->used increments.
 								- Entry order consolidation in the small fast path
 								  - Prefer `SLL → Magazine → SuperSlab` in the normal (non‑bench) path; Quick/FrontCache/Ultra tiers remain opt‑in.
 								- Targeted remote‑drain queue (compiled in, default OFF)
 								  - Per‑class Treiber queue for slabs that exceed remote thresholds; disabled by default via env knobs to preserve conservative behavior.
 								- PGO recipe (opt‑in)
 								  - Makefile targets for PGO on tiny benches are available, but not required for normal builds.
 								What remains bench‑only (NOT promoted)
 								- SLL‑only front (Magazine compiled out) and TLS warmup
 								  - These are highly benchmark‑specific and are kept in bench‑only builds.
 								- Free‑side SLL‑first push without owner/stats
 								  - Mainline preserves learning/stats semantics; bench builds can cut them out.
 								- Quick/FrontCache / 32/64 specialization hardwiring
 								  - Retained as A/B options; not enabled by default in mainline.
 								Recommended “Perf‑Main” preset (opt‑in, no bench macros)
 								- Environment (Tiny‑Hot biased but general):
 								  - `HAKMEM_TINY_TLS_SLL=1`
 								  - `HAKMEM_TINY_REFILL_MAX=96`
 								  - `HAKMEM_TINY_REFILL_MAX_HOT=192`
 								  - `HAKMEM_TINY_SPILL_HYST=16`
 								  - `HAKMEM_TINY_BG_REMOTE=0` (keep targeted remote drain off by default)
 								  - Keep Quick/FrontCache/Ultra OFF unless explicitly A/B tested
 								How to try Perf‑Main locally
 								- Build benches: `make bench_fast`
 								- Run tiny‑hot triad (no bench macros): `bash scripts/run_tiny_hot_triad.sh 60000`
 								- Run random‑mixed matrix: `bash scripts/run_random_mixed_matrix.sh 100000`
 								Notes
 								- LD_PRELOAD/app mode remains conservative (LD_SAFE staging). Tiny‑only and pass‑through modes are recommended for stability. The bench‑only optimizations are intentionally not applied in LD mode.