refactor

[elimelt]

Makes queue config per-instance (previously static, so one queue could reconfigure or NPE another), consolidates construction onto QueuePreset + QueueConfig.Builder, removes sun.misc.Unsafe and the dead Serializable path, and fixes interrupt handling and a constructor file-handle leak.

Also aligns the toolchain on Java 21 (pom, CI, publish workflow), adds a self-contained run_tests.sh harness, and regenerates the committed docs from current source.

Golden tests pin the on-disk and wire formats byte-for-byte. 101 tests green.

[elimelt]

Benchmarks

Before/after comparison of main vs this branch. Methodology: 5 trials per side, each trial in a fresh JVM (Temurin 21.0.12, -Xms512m -Xmx512m, Darwin arm64 laptop). Trials interleave the two sides, and the side that runs first alternates each trial, to reduce machine-noise bias. The same harness runs against both sides; it uses only APIs that exist on both. Values below are medians; "~" means the delta is inside the run-to-run spread of either side, so the sides are equivalent on that metric. Full per-trial data, summary.md, and the runnable suite live in benchmarks/ (one command: benchmarks/run_benchmarks.sh).

Note: poll() persists its read position with an fsync per message on both sides, so poll throughput and round-trip latency are fsync-bound (~200 ops/s on this disk).

Medians (5 trials per side)

Metric	main	this branch	delta
offer() 64 B (msgs/s)	13,444	11,362	-15.5% ~
offer() 1 KiB (msgs/s)	12,050	12,592	+4.5% ~
offer() 8 KiB (msgs/s)	11,784	12,021	+2.0% ~
offer() 64 KiB (MiB/s)	445.6	424.1	-4.8% ~
offer() 1 KiB, checksums off (msgs/s)	13,483	12,917	-4.2% ~
poll() 64 B (msgs/s)	214	201	-6.5% ~
poll() 1 KiB (msgs/s)	217	220	+1.3% ~
poll() 8 KiB (msgs/s)	202	201	-0.5% ~
poll() 64 KiB (msgs/s)	208	217	+4.2% ~
poll() 1 KiB, checksums off (msgs/s)	208	201	-3.2% ~
Round trip p50, 1 KiB (µs)	8,692	8,577	-1.3% ~
Round trip p95, 1 KiB (µs)	10,376	12,470	+20.2% *
Round trip p99, 1 KiB (µs)	11,827	17,036	+44.0% *
Open+close populated file, p50 (µs)	8,635	9,364	+8.5% ~
Alloc per offer(), 1 KiB (B/op)	3,178	3,178	+0.0%
Alloc per poll(), 1 KiB (B/op)	5,513	5,633	+2.2%
Alloc per poll(), 64 B (B/op)	713	817	+14.6%
Settled heap after produce/consume cycle, 1 KiB	1.3 MiB	1.3 MiB	+1.6%
Peak RSS, offer() 1 KiB run	160.1 MiB	171.1 MiB	+6.9%

* medians differ, but the per-trial ranges overlap heavily (see below).

Reading

• Throughput and open/close cost are equivalent within noise on every case. No metric shows a clear throughput win or loss; run-to-run spread on this laptop is larger than the deltas.
• Real, repeatable memory regressions on this branch, all small in absolute terms: poll() allocates ~+120 B per message (the ByteBuffer-based deserialize path), and peak RSS of the 1 KiB and 8 KiB offer() workloads is 4-7% higher. offer() allocation is byte-identical. Settled heap is unchanged.
• Possible tail-latency regression: round-trip p95/p99 medians are higher on this branch (+20%/+44%), but per-trial ranges overlap (p99 main 10.6-18.7 ms vs branch 11.7-22.1 ms) and the path is fsync-dominated, so the data cannot separate this from disk noise. Worth a re-check on quieter hardware before reading much into it.

Plots