SPSC Ring Buffer

Learning objective

Explain a bounded SPSC ring buffer as an ownership-discipline problem: show why separating reservation from publication, and payload read from consumption acknowledgement, is what makes the structure correct, work through wrap-around, full, and empty detection, show the cached-cursor optimisation, contrast per-item publication with batching, and demonstrate two concrete correctness bugs a naive implementation can introduce.

Prerequisites

• The CAS Contention and Backoff lab — this lab contrasts a ring buffer's single-owner cursors against a CAS retry loop's contended updates.
• The Memory Ordering in Java and Rust lab — publication below depends on the release/acquire discipline that lab establishes.

Theory

Why single-producer/single-consumer is a distinct case

An MPMC ring buffer needs contended, CAS-based cursor updates — the exact contention the CAS Contention and Backoff lab describes. An SPSC ring buffer sidesteps that entirely: the producer is the only thread that ever writes the head cursor, and the consumer is the only thread that ever writes the tail cursor. Neither cursor is ever contended. The remaining work isn't avoiding contention — there isn't any — it's correctly publishing what one thread wrote so the other observes it correctly, and correctly detecting full and empty without a lock.

Five separate phases, not two

Collapsing "produce" and "consume" into single monolithic operations is exactly where the bugs below come from. A correct implementation separates:

1. Reservation (producer) — claim the next slot index. Doesn't touch the slot's memory yet.
2. Payload write (producer) — write the value into the reserved slot. Not yet visible to the consumer.
3. Publication (producer) — advance the head cursor. This is the release-store: the write in step 2 must be ordered strictly before this, or the consumer can observe a "ready" slot that isn't (see "Bug: publish before write" below).
4. Payload read (consumer) — read the value out of a published slot.
5. Consumption acknowledgement (consumer) — advance the tail cursor. Only after this may the producer legally overwrite that slot.

Wrap-around

Cursors (head, tail) are monotonically increasing counters, not values bounded to [0, N) — the actual slot is cursor % N (or cursor & mask for a power-of-two capacity). "Wrap-around" is just this arithmetic taking a cursor from index N-1 back to 0 — normal, correct behaviour, not an edge case. The only invariant: the producer never reserves a slot the consumer hasn't freed, and the consumer never reads a slot the producer hasn't published — both phrased in terms of the count of outstanding items (head - tail), never the wrapped index directly.

Full and empty detection

Full: the producer must not reserve when head - tail == capacity — doing so anyway is the overwrite bug below. This lab's model rejects and counts the rejection (backpressure) as the simplest honest choice. Empty: the consumer must not read when head == tail — nothing published yet.

The cached-cursor optimisation

Checking "is there room?" naively means reading the consumer's tail on every reservation — a cross-core coherence round trip. Since the producer only needs the tail to be accurate when its optimistic view says "maybe full," it can keep a cached copy of the consumer's tail (and symmetrically, the consumer caches the producer's head), refreshing only when the cache pessimistically suggests no room (or no data) is left. When the cache is already known sufficient, no cross-core read happens at all. This is the same idea behind cursor-caching in the LMAX Disruptor and comparable SPSC/MPSC queues.

Batch publication

Publishing one slot at a time costs one release-store per item. If the producer has reserved several contiguous slots, it can write all their payloads and then publish all of them with a single head update — the same idea as the consumer acknowledging several reads with one tail update. This amortises publication/acknowledgement cost across a batch without changing ordering within it, and without batching the payload read itself.

Bug: publish before write

If a producer advances the head cursor before finishing the payload write, the consumer can observe the slot as "published" and read it before the real payload exists. It doesn't crash: it silently returns whatever was previously there — stale data from an earlier cycle. This is why publication is its own explicit step, strictly after the write.

Bug: overwrite before consumption

If a producer's reservation step doesn't correctly check head - tail against capacity — or, as this lab's buggy scenario models, skips the check entirely — the producer will eventually overwrite a slot the consumer hasn't read. The old value is destroyed with no error and no signal. This is strictly worse than a crash: the program keeps running as if nothing went wrong.

Java and Rust

public final class SpscRingBuffer {
    private static final VarHandle HEAD;
    private static final VarHandle TAIL;
    static {
        try {
            HEAD = MethodHandles.lookup().findVarHandle(SpscRingBuffer.class, "head", long.class);
            TAIL = MethodHandles.lookup().findVarHandle(SpscRingBuffer.class, "tail", long.class);
        } catch (ReflectiveOperationException e) {
            throw new ExceptionInInitializerError(e);
        }
    }

    private final long[] slots;
    private final int mask;
    private volatile long head = 0; // published cursor
    private volatile long tail = 0; // acknowledged cursor
    private long cachedTail = 0, reserveIndex = 0; // producer-only
    private long cachedHead = 0, readIndex = 0;    // consumer-only

    public SpscRingBuffer(int capacity) {
        if (Integer.bitCount(capacity) != 1) throw new IllegalArgumentException("capacity must be a power of two");
        this.slots = new long[capacity];
        this.mask = capacity - 1;
    }

    public boolean tryProduce(long value) {
        int capacity = slots.length;
        if (reserveIndex - cachedTail == capacity) {
            cachedTail = (long) TAIL.getAcquire(this);
            if (reserveIndex - cachedTail == capacity) return false; // genuinely full
        }
        slots[(int) (reserveIndex & mask)] = value; // payload write — not yet visible
        reserveIndex++;
        HEAD.setRelease(this, reserveIndex); // publication
        return true;
    }

    public boolean tryConsume(long[] out) {
        if (readIndex == cachedHead) {
            cachedHead = (long) HEAD.getAcquire(this);
            if (readIndex == cachedHead) return false; // genuinely empty
        }
        out[0] = slots[(int) (readIndex & mask)]; // payload read
        readIndex++;
        TAIL.setRelease(this, readIndex); // consumption acknowledgement
        return true;
    }
}

@State(Scope.Group)
@BenchmarkMode(Mode.Throughput)
@OutputTimeUnit(TimeUnit.MILLISECONDS)
@Fork(1)
@Warmup(iterations = 5, time = 1)
@Measurement(iterations = 10, time = 1)
public class SpscRingBufferBenchmark {
    private final SpscRingBuffer buffer = new SpscRingBuffer(1024);
    private final long[] out = new long[1];

    @Benchmark @Group("spsc") @GroupThreads(1)
    public void produce() {
        while (!buffer.tryProduce(1)) Thread.onSpinWait();
    }

    @Benchmark @Group("spsc") @GroupThreads(1)
    public void consume() {
        while (!buffer.tryConsume(out)) Thread.onSpinWait();
    }
}

use std::cell::UnsafeCell;
use std::sync::atomic::{AtomicU64, Ordering};
use std::sync::Arc;

struct Shared {
    slots: Box<[UnsafeCell<u64>]>,
    mask: u64,
    head: AtomicU64, // published cursor
    tail: AtomicU64, // acknowledged cursor
}
unsafe impl Sync for Shared {}

pub fn ring_buffer(capacity: usize) -> (Producer, Consumer) {
    assert!(capacity.is_power_of_two(), "capacity must be a power of two");
    let slots = (0..capacity).map(|_| UnsafeCell::new(0)).collect();
    let shared = Arc::new(Shared { slots, mask: (capacity - 1) as u64, head: AtomicU64::new(0), tail: AtomicU64::new(0) });
    (
        Producer { shared: Arc::clone(&shared), reserve_index: 0, cached_tail: 0 },
        Consumer { shared, read_index: 0, cached_head: 0 },
    )
}

pub struct Producer { shared: Arc<Shared>, reserve_index: u64, cached_tail: u64 }

impl Producer {
    pub fn try_produce(&mut self, value: u64) -> bool {
        let capacity = self.shared.slots.len() as u64;
        if self.reserve_index - self.cached_tail == capacity {
            self.cached_tail = self.shared.tail.load(Ordering::Acquire);
            if self.reserve_index - self.cached_tail == capacity {
                return false; // genuinely full
            }
        }
        let idx = (self.reserve_index & self.shared.mask) as usize;
        unsafe { *self.shared.slots[idx].get() = value; } // payload write — not yet visible
        self.reserve_index += 1;
        self.shared.head.store(self.reserve_index, Ordering::Release); // publication
        true
    }
}
unsafe impl Send for Producer {}

pub struct Consumer { shared: Arc<Shared>, read_index: u64, cached_head: u64 }

impl Consumer {
    pub fn try_consume(&mut self) -> Option<u64> {
        if self.read_index == self.cached_head {
            self.cached_head = self.shared.head.load(Ordering::Acquire);
            if self.read_index == self.cached_head {
                return None; // genuinely empty
            }
        }
        let idx = (self.read_index & self.shared.mask) as usize;
        let value = unsafe { *self.shared.slots[idx].get() }; // payload read
        self.read_index += 1;
        self.shared.tail.store(self.read_index, Ordering::Release); // consumption acknowledgement
        Some(value)
    }
}
unsafe impl Send for Consumer {}

fn run_pipeline() {
    let (mut producer, mut consumer) = ring_buffer(1024);
    let producer_handle = thread::spawn(move || {
        for i in 0..ITEMS {
            while !producer.try_produce(i) { std::hint::spin_loop(); }
        }
    });
    let consumer_handle = thread::spawn(move || {
        let mut received = 0u64;
        while received < ITEMS {
            if consumer.try_consume().is_some() { received += 1; } else { std::hint::spin_loop(); }
        }
    });
    producer_handle.join().unwrap();
    consumer_handle.join().unwrap();
}

Benchmark methodology

Both languages benchmark the same shape but measure different things — the numbers must not be compared directly. JMH's @Group keeps both threads alive for the entire measurement window, reporting steady-state throughput. Criterion's b.iter(...) re-runs the whole closure — including thread::spawn/.join() for a fresh pair — every sample, so its time necessarily includes thread creation/teardown overhead the Java number excludes.

Java (JMH, @Group("spsc"), ops/ms per side, higher is better):

Rust (Criterion, full pipeline including thread spawn/join, 200,000 items per sample):

Producer and consumer throughput match almost exactly in the Java run (12,424.844 vs. 12,425.235 ops/ms) — expected for a correctly balanced SPSC pipeline where both sides do symmetric, equally-cheap work. The Rust number cannot be read as "faster than Java" here — its derived ~220,392 items/ms includes real thread spawn/join overhead the Java methodology deliberately excludes; a persistent-thread harness would very likely change it substantially. Neither number is a "real-world" figure — both run the tightest possible spin-loop with no actual payload processing, isolating the ring buffer's own mechanics from any application work.

Re-run the projects in code/ on your own hardware before treating any of this as authoritative for a design decision.

Common mistakes

• Publishing (advancing head) before finishing the payload write — the consumer can observe and read stale data with no error at all (see "Bug: publish before write").
• Getting the full-buffer check wrong, or skipping it — the producer silently overwrites unconsumed data (see "Bug: overwrite before consumption").
• Checking wrapped slot indices directly for "full"/"empty" instead of comparing raw cursor counts (head - tail) — this breaks the instant a cursor wraps.
• Choosing a non-power-of-two capacity when using a bitmask for the slot index — index & mask is only equivalent to index % capacity when capacity is a power of two.
• Reading the other side's real cursor on every single operation when a cached, refresh-on-demand copy would avoid nearly all of that cross-core traffic.

Investigation task

Using the Java or Rust project in code/:

1. Run the benchmark and record the reported throughput or pipeline time on your own hardware.
2. Change the buffer capacity (a power of two) and re-run — observe whether throughput changes, and form a hypothesis for why or why not.
3. In the Java benchmark, temporarily change tryProduce/tryConsume to always re-read the real tail/head (remove the cached-cursor short-circuit) and re-run — measure the throughput cost of the cache being absent.
4. Reproduce the "publish before write" bug in your own copy of the code by moving the HEAD.setRelease call before the payload write, and write a test that demonstrates the consumer can observe incorrect data (it will not do so on every run — note how often it reproduces on your hardware, and why that non-determinism doesn't make the bug any less real).
5. Write down your CPU model and core count, your measured numbers, and explain any difference from the disclosed numbers above.

Accessibility notes

• The interactive model is fully keyboard operable: the scenario selector and the Java/Rust code tabs are roving-tabindex tablists (arrow keys, Home/End); every step/reset control is a native <button>.
• Every state change is announced to screen readers via an aria-live="polite" region, in addition to the visible slot/actor status badges and the state inspector table — state is never colour-only.
• This page has no auto-playing or looping animation; step transitions resolve instantly, so there is nothing beyond the site-wide CSS rule to gate on prefers-reduced-motion.
• With JavaScript disabled, this page's theory, Java and Rust code, benchmark methodology, trade-offs and sources remain fully readable — only the interactive model and the graded quiz require script.

Review questions

Self-check before or after the graded quiz below:

1. Why must publication be a separate, later step from the payload write, rather than the same operation?
2. What specifically does the cached-cursor optimisation avoid, and when is it forced to give up and re-read the real cursor?
3. Why is "wrap-around" not an error condition, and what invariant must hold regardless of whether a cursor has wrapped?
4. What's the difference between how this lab's "full" scenario and its "overwrite" bug scenario each handle a full buffer?

Sources

• Disruptor: High Performance Alternative to Bounded Queues for Exchanging Data Between Concurrent Threads — Thompson, Fox, Barker, LMAX Technical Paper — lmax-exchange.github.io/disruptor
• The Art of Multiprocessor Programming — Herlihy & Shavit, Morgan Kaufmann, 2020.
• Java Concurrency in Practice — Goetz et al., Addison-Wesley, 2006.
• java.lang.invoke.VarHandle — Java SE documentation — docs.oracle.com
• The Rustonomicon — Working with Unsafe — doc.rust-lang.org/nomicon
• ringbuf crate documentation — docs.rs/ringbuf
• JMH: Java Microbenchmark Harness — openjdk.org/projects/code-tools/jmh
• Criterion.rs User Guide — bheisler.github.io/criterion.rs