hakmem/docs/BUILD_PHASE7_POOL_TLS.md

HAKMEM Phase 7 + Pool TLS Phase 1.5b — Build & Run Cheatsheet

This document captures the stable build/run recipe used for recent benches.

One‑liner Build (recommended)

./build.sh <target>

# examples
./build.sh bench_mid_large_mt_hakmem
./build.sh bench_random_mixed_hakmem
./build.sh larson_hakmem

Enables at build time:

• POOL_TLS_PHASE1=1 (Pool TLS Phase 1.5b)
• HEADER_CLASSIDX=1 (Phase 7 header)
• AGGRESSIVE_INLINE=1
• PREWARM_TLS=1

Verify switches:

make print-flags

Optional safety/verbosity toggles:

• HAKMEM_TINY_SAFE_FREE=1 — strict free validation (mincore on all frees). Slower but safest.
• HAKMEM_DEBUG_VERBOSE=1 — enable verbose logs for Tiny header/free, etc.

Examples:

make clean && make HAKMEM_TINY_SAFE_FREE=1 POOL_TLS_PHASE1=1 HEADER_CLASSIDX=1 AGGRESSIVE_INLINE=1 PREWARM_TLS=1 bench_mid_large_mt_hakmem

Bench Recipes (used in reports)

Larson (Mixed)

./build.sh larson_hakmem
make larson_system
./larson_hakmem 2 8 128 1024 1 12345 1
./larson_hakmem 2 8 128 1024 1 12345 4
./larson_system 2 8 128 1024 1 12345 1
./larson_system 2 8 128 1024 1 12345 4

Pool TLS (8–52KB)

./build.sh bench_pool_tls_hakmem
make bench_pool_tls_system
./bench_pool_tls_hakmem 1 100000 256 42
./bench_pool_tls_hakmem 4 50000 256 42
./bench_pool_tls_system 1 100000 256 42
./bench_pool_tls_system 4 50000 256 42

Random Mixed (Tiny 128–1024B)

./build.sh bench_random_mixed_hakmem
make bench_random_mixed_system
for s in 128 256 512 1024; do \
  ./bench_random_mixed_hakmem 100000 $s 42; \
  ./bench_random_mixed_system 100000 $s 42; \
done

Mid‑Large MT (8–32KB)

./build.sh bench_mid_large_mt_hakmem
make bench_mid_large_mt_system
./bench_mid_large_mt_hakmem 1 100000 256 42
./bench_mid_large_mt_hakmem 4 50000 256 42
./bench_mid_large_mt_system 1 100000 256 42
./bench_mid_large_mt_system 4 50000 256 42

Mimalloc note (when comparing)

Direct‑link mimalloc benches require runtime path:

export LD_LIBRARY_PATH=$PWD/mimalloc-bench/extern/mi/out/release

Build hygiene

• Always prefer ./build.sh over ad‑hoc make (prevents flag drift)
• Check switches: make print-flags
• Verify freshness: ./verify_build.sh <binary>