hakmem/docs/BUILDING_QUICKSTART.md

# BUILDING Quickstart

One‑liner (recommended)
- `./build.sh <target>`
  - Pins: `POOL_TLS_PHASE1=1 HEADER_CLASSIDX=1 AGGRESSIVE_INLINE=1 PREWARM_TLS=1 POOL_TLS_PREWARM=1`
- Help/targets: `./build.sh help`, `./build.sh list`
- Verify freshness: `./build.sh verify <binary>`

Common targets
- `bench_random_mixed_hakmem`  (Tiny 1T mixed)
- `bench_pool_tls_hakmem`      (Pool TLS 8–52KB)
- `bench_mid_large_mt_hakmem`  (Mid‑Large MT 8–32KB)
- `larson_hakmem`              (Larson)
- System baselines: `bench_*_system`

Pool TLS Arena ENV (A/B)
- `export HAKMEM_POOL_TLS_ARENA_MB_INIT=2`   # default 1
- `export HAKMEM_POOL_TLS_ARENA_MB_MAX=16`   # default 8
- `export HAKMEM_POOL_TLS_ARENA_GROWTH_LEVELS=4`  # default 3

Runtime safety/verbosity (optional)
- `EXTRA_MAKEFLAGS="HAKMEM_TINY_SAFE_FREE=1" ./build.sh <target>`
- `EXTRA_MAKEFLAGS="HAKMEM_DEBUG_VERBOSE=1" ./build.sh <target>`

Perf & strace
- `perf stat -e cycles,instructions,branches,branch-misses,cache-misses -r 3 -- ./<bin> ...`
- `strace -e trace=mmap,madvise,munmap -c ./<bin> ...`

Troubleshooting
- `make print-flags` to inspect flags
- `./verify_build.sh <bin>` to check binary freshness
-												Tiny: fix remote sentinel leak → SEGV; add defense-in-depth; PoolTLS: refill-boundary remote drain; build UX help; quickstart docs

Summary
- Fix SEGV root cause in Tiny random_mixed: TINY_REMOTE_SENTINEL leaked from Remote queue into freelist/TLS SLL.
- Clear/guard sentinel at the single boundary where Remote merges to freelist.
- Add minimal defense-in-depth in freelist_pop and TLS SLL pop.
- Silence verbose prints behind debug gates to reduce noise in release runs.
- Pool TLS: integrate Remote Queue drain at refill boundary to avoid unnecessary backend carve/OS calls when possible.
- DX: strengthen build.sh with help/list/verify and add docs/BUILDING_QUICKSTART.md.

Details
- core/superslab/superslab_inline.h: guard head/node against TINY_REMOTE_SENTINEL; sanitize node[0] when splicing local chain; only print diagnostics when debug guard is enabled.
- core/slab_handle.h: freelist_pop breaks on sentinel head (fail-fast under strict).
- core/tiny_alloc_fast_inline.h: TLS SLL pop breaks on sentinel head (rare branch).
- core/tiny_superslab_free.inc.h: sentinel scan log behind debug guard.
- core/pool_refill.c: try pool_remote_pop_chain() before backend carve in pool_refill_and_alloc().
- core/tiny_adaptive_sizing.c: default adaptive logs off; enable via HAKMEM_ADAPTIVE_LOG=1.
- build.sh: add help/list/verify; EXTRA_MAKEFLAGS passthrough; echo pinned flags.
- docs/BUILDING_QUICKSTART.md: add one‑pager for targets/flags/env/perf/strace.

Verification (high level)
- Tiny random_mixed 10k 256/1024: SEGV resolved; runs complete.
- Pool TLS 1T/4T perf: HAKMEM >= system (≈ +0.7% 1T, ≈ +2.9% 4T); syscall counts ~10–13.

Known issues (to address next)
- Tiny random_mixed perf is weak vs system:
  - 1T/500k/256: cycles/op ≈ 240 vs ~47 (≈5× slower), IPC ≈0.92, branch‑miss ≈11%.
  - 1T/500k/1024: cycles/op ≈ 149 vs ~53 (≈2.8× slower), IPC ≈0.82, branch‑miss ≈10.5%.
  - Hypothesis: frequent SuperSlab path for class7 (fast_cap=0), branchy refill/adopt, and hot-path divergence.
- Proposed next steps:
  - Introduce fast_cap>0 for class7 (bounded TLS SLL) and a simpler batch refill.
  - Add env‑gated Remote Side OFF for 1T A/B (reduce side-table and guards).
  - Revisit likely/unlikely and unify adopt boundary sequencing (drain→bind→acquire) for Tiny.

											
										
										
											2025-11-09 16:49:34 +09:00
+								# BUILDING Quickstart
 								One‑liner (recommended)
 								- `./build.sh <target>`
 								  - Pins: `POOL_TLS_PHASE1=1 HEADER_CLASSIDX=1 AGGRESSIVE_INLINE=1 PREWARM_TLS=1 POOL_TLS_PREWARM=1`
 								- Help/targets: `./build.sh help`, `./build.sh list`
 								- Verify freshness: `./build.sh verify <binary>`
 								Common targets
 								- `bench_random_mixed_hakmem`  (Tiny 1T mixed)
 								- `bench_pool_tls_hakmem`      (Pool TLS 8–52KB)
 								- `bench_mid_large_mt_hakmem`  (Mid‑Large MT 8–32KB)
 								- `larson_hakmem`              (Larson)
 								- System baselines: `bench_*_system`
 								Pool TLS Arena ENV (A/B)
 								- `export HAKMEM_POOL_TLS_ARENA_MB_INIT=2`   # default 1
 								- `export HAKMEM_POOL_TLS_ARENA_MB_MAX=16`   # default 8
 								- `export HAKMEM_POOL_TLS_ARENA_GROWTH_LEVELS=4`  # default 3
 								Runtime safety/verbosity (optional)
 								- `EXTRA_MAKEFLAGS="HAKMEM_TINY_SAFE_FREE=1" ./build.sh <target>`
 								- `EXTRA_MAKEFLAGS="HAKMEM_DEBUG_VERBOSE=1" ./build.sh <target>`
 								Perf & strace
 								- `perf stat -e cycles,instructions,branches,branch-misses,cache-misses -r 3 -- ./<bin> ...`
 								- `strace -e trace=mmap,madvise,munmap -c ./<bin> ...`
 								Troubleshooting
 								- `make print-flags` to inspect flags
 								- `./verify_build.sh <bin>` to check binary freshness