feat: enhance benchmark capabilities with customizable stack depth and improved throughput chart

Author: gooderfreed

.github/assets/throughput_chart.png

@@ -67,4 +67,5 @@ fuzzers/*_fuzzer
 # Python
 .venv
 
-benchmark
+benchmark
+benchmark_*

.gitignore

@@ -69,11 +69,12 @@ FUZZ_FLAGS = -fsanitize=fuzzer,address,undefined -O3 -g3 -fno-omit-frame-pointer
 FUZZ_DEBUG_FLAGS = -fsanitize=fuzzer,address,undefined -O0 -g3 -fno-omit-frame-pointer -DESTACK_FUZZ_DEBUG -DDEBUG
 
 # --- Benchmark Configuration ---
+DEPTH ?= 15
 BENCH_DIR = bench
 BENCH_SRCS = $(BENCH_DIR)/benchmark.cpp $(BENCH_DIR)/Allocator.cpp $(BENCH_DIR)/StackAllocator.cpp
-BENCH_BIN = $(BENCH_DIR)/benchmark
+BENCH_BIN = $(BENCH_DIR)/benchmark_$(DEPTH)
 CXX ?= g++
-CXXFLAGS = -O3 -std=c++17 -flto -DNDEBUG -Wno-stringop-overflow -I. -I$(BENCH_DIR)
+CXXFLAGS = -O3 -std=c++17 -flto -DNDEBUG -Wno-stringop-overflow -DBENCH_DEPTH=$(DEPTH) -I. -I$(BENCH_DIR)
 
 # Define the primary source file to check coverage for.
 COVERAGE_SRC = easy_stack.h
@@ -278,11 +279,11 @@ clean_matrix:
 
 # --- Benchmark Target ---
 $(BENCH_BIN): $(BENCH_SRCS) easy_stack.h
-	@printf "Compiling benchmark suite: $@\n"
+	@printf "Compiling benchmark suite (depth $(DEPTH)): $@\n"
 	@$(CXX) $(CXXFLAGS) $(BENCH_SRCS) -o $@
 
 bench: $(BENCH_BIN)
-	@printf "\n--- Running Stack Allocator Benchmarks ---\n"
+	@printf "\n--- Running Stack Allocator Benchmarks (Depth: $(DEPTH)) ---\n"
 	@./$(BENCH_BIN)
 
 
@@ -295,7 +296,7 @@ clean:
 	rm -f coverage.info
 	rm -f $(FUZZ_BINS) $(FUZZ_DEBUG_BINS)
 	rm -rf $(MATRIX_DIR)
-	rm -f $(BENCH_BIN) # Clean benchmark binary
+	rm -f $(BENCH_DIR)/benchmark_* # Clean all benchmark binaries
 
 
 # --- Fuzzing Targets ---
@@ -330,7 +331,7 @@ list:
 	@printf "  make tests                    - run all tests without debug output \n"
 	@printf "  make tests_full               - run all tests with debug output\n"
 	@printf "  make test_matrix -j$(nproc)   - run matrix of tests\n"
-	@printf "  make bench                    - compile and run stupidly fast allocator benchmarks\n"
+	@printf "  make bench [DEPTH=15|30|100]  - compile and run benchmarks with customizable stack depth (default: 15)\n"
 	@printf "  make coverage                 - build & run tests to generate coverage data for CodeCov\n"
 	@printf "  make fuzz_[name]              - run the 'core' fuzzer for 5 minutes (auto-detects fuzz_*.c)\n"
 	@printf "  make replay_[name] CRASH=...  - replay a specific crash file with ASCII visualization\n"

Makefile

@@ -124,30 +124,52 @@ Traditional stack allocators suffix or prefix each payload with inline metadata
 
 ## Benchmarks & Performance
 
-To verify execution speed and memory overhead, `easy_stack` was benchmarked against popular alternatives:
+To verify execution speed, cache resilience, and scalability under load, `easy_stack` was benchmarked against popular alternatives:
 *   **wb_alloc (Bundy):** A widely-used, minimalist C arena allocator.
 *   **Trebi StackAllocator:** A standard C++ LIFO stack allocator (compiled with `-flto` for maximum devirtualization).
 
 ### Test Environment
 *   **CPU:** AMD Ryzen 7 4700U (8 Cores / 8 Threads, Zen 2 @ up to 4.1 GHz)
 *   **Compiler:** GCC 15.2 with `-O3 -flto -DNDEBUG`
-*   **Scenario:** 2,000,000 iterations per run (executing exactly 72,000,000 allocator operations) of nested allocations (up to depth 15) with randomized sizes (16-160 bytes). Best of 25 runs.
+*   **Scenario:** 2,000,000 iterations per run (executing up to 480,000,000 allocator operations) of nested allocations with randomized sizes (16-160 bytes) scaled across three distinct stack allocation depths (15, 30, and 100). Best of 25 runs.
 
-### 1. Throughput (Speed)
+### 1. Throughput & Cache-Line Scaling (Speed)
 
-Even when configured with full runtime safety checks (`ESTACK_POLICY_DEFENSIVE`), `easy_stack` easily outperforms competitors due to its dense L1-cache friendly metadata layout. When compiled in trusted mode (`ESTACK_POLICY_CONTRACT`), it achieves near-hardware limits.
+Rather than benchmarking only a single shallow depth, the suite tests scaling across three critical architectural boundaries. This highlights how cache layout and processor prefetching impact execution speed as stack depth increases.
 
 <p align="center">
   <img src=".github/assets/throughput_chart.png" width="700" alt="Throughput Comparison" />
 </p>
 
-*   **EasyStack (Contract):** **820 Million ops/sec** (~1.22 ns per allocation/free cycle) — **3.56x faster** than traditional implementations.
-*   **EasyStack (Defensive):** **470 Million ops/sec** (~2.12 ns per cycle) — still **2.06x faster** than competitors, while providing full runtime LIFO safety and validation.
+#### Architectural Insights from the Results:
+
+*   **Perfect L1 Residency (Depth 15):** 
+    At shallow depths, the EStack header (16 bytes) and active metadata cells (30 bytes for `uint16_t` offsets) fit entirely within a single **64-byte L1 cache line** ($16 + 30 = 46$ bytes). In **Contract** (Trusted) mode, this achieves near-hardware limits of **821 Million ops/sec** (~1.22 ns per allocation/free cycle) due to 100% L1 cache hits.
+    
+*   **L1 Cache Line Transitions (Depth 30):** 
+    As the stack depth crosses the 64-byte boundary ($16 + 60 = 76$ bytes), metadata spans into a second cache line. This transition introduces a minor **6% throughput degradation** (dropping to **766 Million ops/sec**), representing the hardware overhead of fetching the adjacent cache line.
+    
+*   **Hardware Prefetcher Synergy (Depth 100):** 
+    At extreme depths, metadata spans 4 distinct cache lines (216 bytes total). Thanks to the dense, sequential, and contiguous layout of the metadata array, the CPU's **Hardware Prefetcher** instantly recognizes the linear access pattern. It proactively loads upcoming cache lines into L1, maintaining a blistering speed of **682 Million ops/sec** (only a 17% drop from peak L1 residency).
+    
+*   **Instruction Latency Hiding (Defensive Mode Flatness):** 
+    In **Defensive** (Safety) mode, throughput remains completely flat at a rock-solid **~464 Million ops/sec** across all depths (15, 30, and 100). 
+    
+    This stability is a textbook demonstration of **CPU-bound execution masking memory latency**. The execution of defensive `if` branches and boundary checks occupies the pipeline with ALU instructions. During this instruction execution window, the CPU's prefetcher asynchronously pulls next-cache-line memory requests in the background. By the time the safety checks are complete, the memory is already waiting in L1, resulting in a **zero-cycle memory stall** regardless of stack depth.
+
+#### Comparison to Competitors:
+
+Traditional inline-header allocators degrade more severely or remain slow under depth scaling. 
+*   **Trebi (C++)** drops from **199 Million ops/sec** down to **185 Million** at depth 100. This is because inline metadata scatters memory records across the buffer ($100 \times 16 \text{ bytes} = 1600 \text{ bytes}$ of headers mixed with payload). This layout thrashes L1 cache lines with hard-to-predict address jumps, causing frequent processor stalls. 
+*   Even with full safety checks active, **EasyStack (Defensive)** remains **87% faster than wb_alloc** and **150% faster than Trebi** at depth 100, while **EasyStack (Contract)** outperforms competitors by up to **268%**.
+
 
 ### 2. Memory Efficiency (Payload vs. Overhead)
 
 Traditional stack allocators prefix each block with a fixed 16-byte inline header (on 64-bit systems). On small allocations (common for temporary stacks), this inline overhead consumes up to **50%+ of your buffer**. 
+
 `easy_stack` uses dynamically scaled metadata (only 2 bytes per allocation for buffers < 64KB). Since metadata is segregated from aligned payloads, **zero bytes are wasted on alignment padding in the control zone**.
+
 Below is a comparison of usable payload space in a **10 KB buffer** across different allocation sizes:
 
 <p align="center">

README.md

@@ -7,6 +7,17 @@
 #include <algorithm>
 #include <cstring> // Added for std::memset
 
+// Define default depth if not passed via compiler options (e.g., -DBENCH_DEPTH=30)
+#ifndef BENCH_DEPTH
+    #define BENCH_DEPTH 15
+#endif
+
+// Compile-time scaling of benchmark execution limits
+constexpr int DEPTH_MAX = BENCH_DEPTH;
+constexpr int DEPTH_P1  = (DEPTH_MAX * 8) / 15;
+constexpr int DEPTH_P2  = (DEPTH_MAX * 5) / 15;
+constexpr double OPS_PER_ITERATION = 2.0 * (DEPTH_P1 - DEPTH_P2 + DEPTH_MAX);
+
 // Compiler barrier configuration to avoid optimization folds (call elimination)
 #if defined(__GNUC__) || defined(__clang__)
     #define COMPILER_BARRIER() asm volatile("" : : : "memory")
@@ -122,12 +133,12 @@ int main() {
             // Fresh initialization per round to isolate state
             EStack* stack = estack_create_static(backing_easy, STACK_SIZE);
             uint32_t r_idx = 0;
-            void* ptrs[15] = { nullptr };
+            void* ptrs[DEPTH_MAX] = { nullptr };
 
             auto start = std::chrono::high_resolution_clock::now();
             for (int i = 0; i < pattern_iterations; i++) {
-                // Phase 1: Allocate 8 blocks (Depth 0 -> 8)
-                for (int j = 0; j < 8; j++) {
+                // Phase 1: Allocate blocks (Depth 0 -> DEPTH_P1)
+                for (int j = 0; j < DEPTH_P1; j++) {
                     size_t sz = 16 + (rand_pool[r_idx++ & (RAND_POOL_SIZE - 1)] % 64);
                     ptrs[j] = estack_alloc(stack, sz);
                     if (!ptrs[j]) {
@@ -138,15 +149,15 @@ int main() {
                     COMPILER_BARRIER();
                 }
 
-                // Phase 2: Pop last 3 blocks (Depth 8 -> 5)
-                for (int j = 7; j >= 5; j--) {
+                // Phase 2: Pop last blocks (Depth DEPTH_P1 -> DEPTH_P2)
+                for (int j = DEPTH_P1 - 1; j >= DEPTH_P2; j--) {
                     estack_free(stack, ptrs[j]);
                     COMPILER_BARRIER();
                     ptrs[j] = nullptr;
                 }
 
-                // Phase 3: Allocate 10 more blocks (Depth 5 -> 15)
-                for (int j = 5; j < 15; j++) {
+                // Phase 3: Allocate more blocks (Depth DEPTH_P2 -> DEPTH_MAX)
+                for (int j = DEPTH_P2; j < DEPTH_MAX; j++) {
                     size_t sz = 32 + (rand_pool[r_idx++ & (RAND_POOL_SIZE - 1)] % 128);
                     ptrs[j] = estack_alloc(stack, sz);
                     if (!ptrs[j]) {
@@ -157,8 +168,8 @@ int main() {
                     COMPILER_BARRIER();
                 }
 
-                // Phase 4: Free all remaining blocks (Depth 15 -> 0)
-                for (int j = 14; j >= 0; j--) {
+                // Phase 4: Free all remaining blocks (Depth DEPTH_MAX -> 0)
+                for (int j = DEPTH_MAX - 1; j >= 0; j--) {
                     estack_free(stack, ptrs[j]);
                     COMPILER_BARRIER();
                     ptrs[j] = nullptr;
@@ -174,12 +185,12 @@ int main() {
             wb_MemoryArena wb_stack;
             wb_arenaFixedSizeInit(&wb_stack, backing_wb, STACK_SIZE, wb_Arena_Stack);
             uint32_t r_idx = 0;
-            void* ptrs[15] = { nullptr };
+            void* ptrs[DEPTH_MAX] = { nullptr };
 
             auto start = std::chrono::high_resolution_clock::now();
             for (int i = 0; i < pattern_iterations; i++) {
-                // Phase 1: Allocate 8 blocks (Depth 0 -> 8)
-                for (int j = 0; j < 8; j++) {
+                // Phase 1: Allocate blocks (Depth 0 -> DEPTH_P1)
+                for (int j = 0; j < DEPTH_P1; j++) {
                     size_t sz = 16 + (rand_pool[r_idx++ & (RAND_POOL_SIZE - 1)] % 64);
                     ptrs[j] = wb_arenaPush(&wb_stack, sz);
                     if (!ptrs[j]) {
@@ -190,15 +201,15 @@ int main() {
                     COMPILER_BARRIER();
                 }
 
-                // Phase 2: Pop last 3 blocks (Depth 8 -> 5)
-                for (int j = 7; j >= 5; j--) {
+                // Phase 2: Pop last blocks (Depth DEPTH_P1 -> DEPTH_P2)
+                for (int j = DEPTH_P1 - 1; j >= DEPTH_P2; j--) {
                     wb_arenaPop(&wb_stack);
                     COMPILER_BARRIER();
                     ptrs[j] = nullptr;
                 }
 
-                // Phase 3: Allocate 10 more blocks (Depth 5 -> 15)
-                for (int j = 5; j < 15; j++) {
+                // Phase 3: Allocate more blocks (Depth DEPTH_P2 -> DEPTH_MAX)
+                for (int j = DEPTH_P2; j < DEPTH_MAX; j++) {
                     size_t sz = 32 + (rand_pool[r_idx++ & (RAND_POOL_SIZE - 1)] % 128);
                     ptrs[j] = wb_arenaPush(&wb_stack, sz);
                     if (!ptrs[j]) {
@@ -209,8 +220,8 @@ int main() {
                     COMPILER_BARRIER();
                 }
 
-                // Phase 4: Free all remaining blocks (Depth 15 -> 0)
-                for (int j = 14; j >= 0; j--) {
+                // Phase 4: Free all remaining blocks (Depth DEPTH_MAX -> 0)
+                for (int j = DEPTH_MAX - 1; j >= 0; j--) {
                     wb_arenaPop(&wb_stack);
                     COMPILER_BARRIER();
                     ptrs[j] = nullptr;
@@ -225,12 +236,12 @@ int main() {
             StackAllocator trebi_stack(STACK_SIZE);
             trebi_stack.Init(); 
             uint32_t r_idx = 0;
-            void* ptrs[15] = { nullptr };
+            void* ptrs[DEPTH_MAX] = { nullptr };
 
             auto start = std::chrono::high_resolution_clock::now();
             for (int i = 0; i < pattern_iterations; i++) {
-                // Phase 1: Allocate 8 blocks (Depth 0 -> 8)
-                for (int j = 0; j < 8; j++) {
+                // Phase 1: Allocate blocks (Depth 0 -> DEPTH_P1)
+                for (int j = 0; j < DEPTH_P1; j++) {
                     size_t sz = 16 + (rand_pool[r_idx++ & (RAND_POOL_SIZE - 1)] % 64);
                     ptrs[j] = trebi_stack.Allocate(sz, 8);
                     if (!ptrs[j]) {
@@ -241,15 +252,15 @@ int main() {
                     COMPILER_BARRIER();
                 }
 
-                // Phase 2: Pop last 3 blocks (Depth 8 -> 5)
-                for (int j = 7; j >= 5; j--) {
+                // Phase 2: Pop last blocks (Depth DEPTH_P1 -> DEPTH_P2)
+                for (int j = DEPTH_P1 - 1; j >= DEPTH_P2; j--) {
                     trebi_stack.Free(ptrs[j]);
                     COMPILER_BARRIER();
                     ptrs[j] = nullptr;
                 }
 
-                // Phase 3: Allocate 10 more blocks (Depth 5 -> 15)
-                for (int j = 5; j < 15; j++) {
+                // Phase 3: Allocate more blocks (Depth DEPTH_P2 -> DEPTH_MAX)
+                for (int j = DEPTH_P2; j < DEPTH_MAX; j++) {
                     size_t sz = 32 + (rand_pool[r_idx++ & (RAND_POOL_SIZE - 1)] % 128);
                     ptrs[j] = trebi_stack.Allocate(sz, 8);
                     if (!ptrs[j]) {
@@ -260,8 +271,8 @@ int main() {
                     COMPILER_BARRIER();
                 }
 
-                // Phase 4: Free all remaining blocks (Depth 15 -> 0)
-                for (int j = 14; j >= 0; j--) {
+                // Phase 4: Free all remaining blocks (Depth DEPTH_MAX -> 0)
+                for (int j = DEPTH_MAX - 1; j >= 0; j--) {
                     trebi_stack.Free(ptrs[j]);
                     COMPILER_BARRIER();
                     ptrs[j] = nullptr;
@@ -277,10 +288,10 @@ int main() {
     double best_wb = get_min_time(times_wb);
     double best_trebi = get_min_time(times_trebi);
 
-    // Calculation of allocator throughput (each iteration does exactly 36 allocator calls)
-    const double total_ops_per_round = (double)pattern_iterations * 36.0;
+    // Calculation of allocator throughput dynamically scaled based on compiled depth
+    const double total_ops_per_round = (double)pattern_iterations * OPS_PER_ITERATION;
 
-    std::cout << "=== Results (Best of " << ROUNDS << " runs, " << pattern_iterations << " iterations/run) ===\n";
+    std::cout << "=== Results (Best of " << ROUNDS << " runs, " << pattern_iterations << " iterations/run, depth " << DEPTH_MAX << ") ===\n";
     std::printf("EasyStack:         %.4f sec (%.2f million ops/sec)\n", 
            best_easy, total_ops_per_round / best_easy / 1e6);