Add virtual-threads-benchmark-webflux: the WebFlux leg of the three-way benchmark

Fixes found during self-correction before publishing: - /stream used Flux.interval(), which ticks on its own wall-clock schedule independent of downstream demand and threw OverflowException under a slow subscriber; switched to Flux.range(), which has no independent production schedule and can never outrun demand. - Single-trial HTTP load tests on this shared sandbox swung by more than 50% run to run (795ms-1247ms observed on the identical /io endpoint back to back) -- large enough to flip which threading model looked faster. Fixed by taking the median of 5 independent trials for the I/O-bound benchmark and the median of 3 for the event-loop-starvation benchmark, rather than reporting a single noisy run as if it were precise. - The event-loop-starvation test's first cut used only 8 concurrent /cpu requests as background load, which drained through the 4 event-loop threads well inside the /io measurement window and produced an inconsistent, sometimes-inverted result across runs; raising to 60 fixed the under-loading problem but still flaked once during verification (372ms vs 374ms p99, a real tie). Final fix: 150 concurrent requests plus the median-of-3 trials above. Also adds StreamBackpressureTest, a StepVerifier proof that the /stream endpoint never emits ahead of its subscriber's outstanding requests, and updates the module's docs to report the de-noised numbers with an explicit methodology note on how they compare to the single-trial platform/virtual- thread numbers reused from a different post.
2026-09-19 09:34:18 +00:00
parent f506b01389
commit 09631dcaab
19 changed files with 975 additions and 0 deletions
@@ -0,0 +1,12 @@
+I/O-bound endpoint (/io, Mono.delay(300ms)), concurrency=600, median of 5 trials, 2 vCPU sandbox, Spring Boot 4.1.1 / JDK 25.0.4.1
+==================================================================================================================================
+webflux (netty) : total=600 success=600 wall=569ms p50=455ms p99=510ms
+
+Mono.delay() never parks a thread -- the event loop schedules a timer callback and
+goes back to the selector loop immediately. A single trial at this concurrency swung
+50%+ between back-to-back runs on this shared sandbox -- bigger than the gap being
+measured -- so the number above is the median of 5 independent trials, not
+one shot. Even so it lands in the same range as virtual threads' /io result in
+../virtual-threads-benchmark/docs/output/01-io-bound-benchmark.txt (a single trial):
+treat any single-run percentage gap between WebFlux and virtual threads here as
+noise-level, not a reliable ranking.
@@ -0,0 +1,17 @@
+CPU-bound endpoint (/cpu vs /cpu-offloaded, 20,000x SHA-256), concurrency=60, 2 vCPU sandbox, Spring Boot 4.1.1 / JDK 25.0.4.1
+==============================================================================================================================
+LoopResources.DEFAULT_IO_WORKER_COUNT (Netty event-loop threads) = 4
+Runtime.availableProcessors() (Schedulers.parallel() thread count) = 2
+
+webflux naive (Mono.fromCallable, no subscribeOn)      : total=60 success=60 wall=302ms p50=145ms p99=288ms
+webflux offloaded (subscribeOn(Schedulers.parallel())) : total=60 success=60 wall=271ms p50=142ms p99=261ms
+
+Counter-intuitive result, and worth stating honestly rather than forcing the expected
+story: on THIS box, the two wall times are close, because Reactor Netty's default event-
+loop pool (DEFAULT_IO_WORKER_COUNT = max(availableProcessors(), 4) = 4 here) is actually
+LARGER than Schedulers.parallel()'s pool (sized to availableProcessors() = 2). The naive
+endpoint that "incorrectly" runs on the event loop has more worker threads to run on,
+at this modest concurrency, than the "correctly offloaded" one. This does not mean the
+naive version is fine -- see the event-loop-starvation scenario below for what it actually
+breaks -- only that per-endpoint throughput alone does not show the problem on a small,
+under-loaded box like this one.
@@ -0,0 +1,19 @@
+/io latency while 150 concurrent CPU-bound requests run, median of 3 trials, 2 vCPU sandbox, Spring Boot 4.1.1 / JDK 25.0.4.1
+=============================================================================================================================
+/io alone (baseline, no concurrent CPU load)              : total=20 success=20 wall=347ms p50=332ms p99=346ms
+/io while 150x /cpu (naive) run concurrently         : total=20 success=20 wall=995ms p50=742ms p99=950ms
+/io while 150x /cpu-offloaded run concurrently       : total=20 success=20 wall=731ms p50=693ms p99=697ms
+
+This is the real cost of the naive endpoint, and it does not show up by benchmarking
+/cpu in isolation: /io shares the same small event-loop pool with /cpu. Two fixes were
+needed to get a reproducible number here rather than a coin flip: enough concurrent CPU
+load to occupy all 4 event-loop threads for the full /io measurement window (a first
+cut used 8 concurrent requests, which drained through the event loop in well under the
+/io window and produced an inconsistent, sometimes-inverted result; 60 concurrent
+requests fixed that but still flaked once, 372ms vs 374ms p99, a real tie rather than a
+real result), and taking the median of 3 independent trials rather than one shot,
+same reasoning as the I/O-bound benchmark above. With both fixes, naive /io latency is
+consistently and substantially worse than both the undisturbed baseline and the
+offloaded case. At higher production concurrency this is the exact mechanism behind a
+single CPU-heavy endpoint silently degrading every other endpoint on the same Netty
+server.
@@ -0,0 +1,13 @@
+Flux backpressure proof: /stream, requested in batches of 3, 2, then 45
+=======================================================================
+StepVerifier.create(controller.streamResults(), 3)
+  .expectNext("event-0", "event-1", "event-2")
+  .expectNoEvent(Duration.ofMillis(80))   -- no 4th item arrives without a request
+  .thenRequest(2).expectNext("event-3", "event-4")
+  .thenRequest(45).expectNextCount(45)
+  .expectComplete()
+
+RESULT: verified -- the flux emitted exactly as many items as were requested, in
+the order requested, with no items arriving ahead of a pending request. This is
+what "backpressure is part of the Flux contract" means concretely: the subscriber,
+not the producer, controls the emission rate.