Add MpscRingBuffer primitive for pre-allocated slot rings

[dougqh]

Summary

New datadog.trace.util.concurrent.MpscRingBuffer<T> — a bounded multi-producer / single-consumer ring buffer of pre-allocated, recyclable T instances. Producers and consumers mutate and read slots in place via callbacks; no allocation occurs per write/read after construction.

Lives in internal-api. No callers yet — this PR adds the primitive and tests/benches only. CSS integration to follow in a separate PR.

Motivation

Producer/consumer split in CSS v1.3.0 (#11381) allocates one SpanSnapshot per metrics-eligible span and hands the reference through an MpscArrayQueue. At typical heap sizes (≥256m) this is fine — the snapshots die young. At tight heap (we hit it at Xmx64m in spring-petclinic load testing) the in-flight snapshots overflow G1 survivor regions, triggering To-space Exhausted → fallback Full GC storms.

Moving from "reference passing of fresh objects" to "in-place mutation of pre-allocated slots" eliminates the per-publish allocation entirely. Smoke benchmarks (capacity=1024, 8 producers, 1 consumer on M-series Mac):

Benchmark	MpscArrayQueue<Slot> + per-publish new Slot(...)	MpscRingBuffer<Slot>	Ratio
write_*_8p (publish only)	399 M ops/s	768 M ops/s	1.92×
e2e_*_8p (8P→1C end-to-end)	514 M ops/s	846 M ops/s	1.65×

Allocation rate falls to zero on the ring path (vs sizeof(Slot) × producer ops/s on the queue path) — that's the heap-pressure side of the win, not visible in the throughput numbers above but the key reason this matters for tight-heap workloads.

API

Callback-style, with 0/1/2 context-object overloads. Contexts come before the slot, matching TagMap.forEach / Hashtable.forEach:

// 0 context
ring.tryWrite(slot -> { slot.value = 1; });
ring.drain(slot -> handle(slot));

// 1 context — static BiConsumer<C, T> avoids per-call lambda capture
static final BiConsumer<Span, Slot> FILL = (span, slot) -> slot.svc = span.getService();
ring.tryWrite(span, FILL);

// 2 contexts — TriConsumer<C1, C2, T>
static final TriConsumer<Span, Tag, Slot> FILL2 = (span, tag, slot) -> { ... };
ring.tryWrite(span, tag, FILL2);

tryWrite returns false when full (producer drops the value). drain returns the count processed.

Design

• Producer cursor is CAS-claimed (AtomicLong.compareAndSet in a retry loop). Stale read of the consumer cursor is fine — a false "full" reading just causes a drop.
• Per-slot publication is gated by an AtomicLongArray: a slot is published at sequence s iff sequences[s & mask] == s. This handles out-of-order publishes from concurrent producers — the consumer only advances over contiguous published slots.
• Consumer cursor is volatile; written only by the consumer thread, read by producers to detect free space.
• Capacity rounded up to power-of-two so mask = capacity - 1 works.

Test/bench coverage

• MpscRingBufferTest — 12 JUnit 5 tests covering construction, FIFO order, capacity bounds, fill-drain-fill round trip, 0/1/2 context variants, and an 8-producer × 50,000-writes concurrency test (400K writes, ~150ms).
• MpscRingBufferBenchmark (internal-api/src/jmh/...) — write_1p/8p/16p at varying producer counts + e2e_8p @Group (8 producers + 1 consumer). Parameterised on capacity.
• RingVsQueueBenchmark (dd-trace-core/src/jmh/... — sits alongside the CSS benches, where jctools is already a dep) — head-to-head against MpscArrayQueue<Slot> + per-publish allocation. Numbers above come from this.

Test plan

• :internal-api:test — MpscRingBufferTest passes (12/12 locally)
• :internal-api:jmh runs MpscRingBufferBenchmark (smoke run passes)
• :dd-trace-core:jmh runs RingVsQueueBenchmark (smoke run passes; 1.65×–1.92× ratio)
• No callers yet — production code paths unchanged

🤖 Generated with Claude Code

[dd-octo-sts]

🟢 Java Benchmark SLOs — All performance SLOs passed

Suite	Status
Startup	🟢 pass

SLO thresholds are defined here based on automatically generated metrics. A warning is raised when results are within 5% of the threshold.

PR vs. master results

Startup Time

Scenario	This PR	master	Change
insecure-bank / iast	14,799 ms	14,733 ms	+0.4%
insecure-bank / tracing	13,584 ms	13,752 ms	-1.2%
petclinic / appsec	16,477 ms	16,424 ms	+0.3%
petclinic / iast	16,430 ms	16,576 ms	-0.9%
petclinic / profiling	16,330 ms	15,538 ms	+5.1%
petclinic / tracing	15,677 ms	15,859 ms	-1.1%

Commit: 780a2042 · CI Pipeline · Benchmarking Platform UI

---

Load and DaCapo benchmarks can be triggered manually in the GitLab pipeline. Results will appear in the Benchmarking Platform UI after completion.