@zio.dev/zio-blocks 0.0.32 → 0.0.51

package/reference/ringbuffer/advanced.mdx

@@ -0,0 +1,109 @@
+---
+id: advanced
+title: "Advanced Topics"
+---
+
+## Thread Safety and Correctness
+
+Ring buffers are **lock-free** but must be used correctly:
+
+- **Wrong thread access causes undefined behavior**: Using `SpscRingBuffer` from multiple producer threads produces data races, silent data loss, or crashes. Always use the implementation matching your thread pattern.
+- **`SpscRingBuffer#offer` and `SpscRingBuffer#take` thread contract**: The producer thread must be the sole caller of `SpscRingBuffer#offer`; the consumer thread must be the sole caller of `SpscRingBuffer#take`. They may be the same physical thread (as in single-threaded environments like Scala.js or unit tests) or different threads.
+- **State queries are approximate**: Under concurrency, `SpscRingBuffer#size`, `SpscRingBuffer#isEmpty`, and `SpscRingBuffer#isFull` may stay stale by the time they return. Do not rely on them for exact synchronization — use `SpscRingBuffer#offer`'s return value for backpressure instead.
+- **Null elements are forbidden**: All implementations reject `null` with `NullPointerException`. If you need to store nullable values, wrap them in `Option` or another container.
+
+:::warning
+**Critical:** Ring buffers do not enforce thread-safety at runtime. Using the wrong implementation for your thread pattern or calling methods from the wrong thread **does not throw an exception** — it silently corrupts data. Test thoroughly and document your threading contract.
+:::
+
+## Advanced Usage: Cache-Line Padding
+
+Ring buffers use **cache-line padding** to prevent false sharing between producer and consumer indices on modern CPUs. The padding is transparent to users but enables dramatically lower latency on multi-core systems.
+
+Each implementation pads its internal index fields (producer index, consumer index) to occupy a full cache line (128 bytes on Apple Silicon, 64 bytes on most other architectures). This ensures that when one thread reads its index, it does not invalidate the cache line holding the other thread's index, eliminating costly cache-coherency traffic.
+
+This optimization is automatic and requires no configuration. Ring buffers are inherently more efficient than comparable Scala and Java implementations because of this padding.
+
+## Designing With Ring Buffers
+
+Common patterns for using ring buffers include:
+
+### Pattern: Producer-Consumer Pipeline
+
+Ring buffers form the backbone of producer-consumer pipelines where one or more producers generate work and one or more consumers process it:
+
+```
+┌──────────┐       ┌──────────────┐       ┌──────────┐
+│Producer 1├──────>│ RingBuffer   │<──────┤Consumer 1│
+│Producer 2├──────>│ (MPMC, cap=N)│<──────┤Consumer 2│
+└──────────┘       └──────────────┘       └──────────┘
+```
+
+In this pattern:
+- Producers call `MpmcRingBuffer#offer` and handle backpressure if `false` is returned (e.g., retry, queue internally, apply rate limiting).
+- Consumers call `MpmcRingBuffer#take` in a tight loop, checking for `null` to detect empty buffers.
+- Ring buffer capacity bounds memory and provides natural backpressure.
+
+### Pattern: Batch Processing
+
+For workloads where producers batch elements together, use `SpscRingBuffer#fill` (SPSC) or call `SpscRingBuffer#offer` in a loop:
+
+```
+Producer fills batch of N items
+         ↓
+   Ring Buffer (growing)
+         ↓
+Consumer drain()s batch of M items
+         ↓
+     Process batch
+```
+
+Batching reduces per-element synchronization costs.
+
+### Pattern: Work Stealing with Multiple Consumers (MPMC)
+
+When multiple workers consume from the same queue, use `MpmcRingBuffer`. Each worker calls `MpmcRingBuffer#take` to grab the next item atomically:
+
+```scala mdoc:compile-only
+import zio.blocks.ringbuffer.MpmcRingBuffer
+
+case class Task(id: Int, work: String)
+
+val queue = MpmcRingBuffer[Task](256)
+
+def worker(): Unit = {
+  while (true) {
+    val task = queue.take()
+    if (task ne null) {
+      println(s"Processing: ${task.work}")
+    }
+  }
+}
+```
+
+The CAS loop in `MpmcRingBuffer#take` ensures no two workers grab the same task.
+
+## Performance Characteristics
+
+All ring buffer implementations provide O(1) time complexity for `offer`, `take`, `size`, `isEmpty`, and `isFull` operations.
+
+- **SPSC** (FastFlow) — Fastest: avoids volatile reads on the fast path, minimal cache traffic
+- **SPMC** — Fast: producer uses index-based checking; consumers CAS on a shared index
+- **MPSC** — Fast: producers CAS on a shared index with a cached limit; consumer uses FastFlow relaxed-poll
+- **MPMC** — Slightly slower: uses sequence buffer stamps for coordination; all indices use CAS
+
+Actual performance depends on:
+- **CPU cache architecture** — 64-byte vs 128-byte cache lines affect padding efficiency
+- **Contention level** — high contention increases CAS failure rates and retries
+- **Element size** — larger elements may affect cache locality
+- **Platform** — JVM JIT warmup, Scala.js compiled code, GraalVM-generated native image
+
+Micro-benchmark your specific workload if latency is critical.
+
+## Integration with Other ZIO Blocks Types
+
+Ring buffers are standalone data structures and do not depend on other ZIO Blocks types. However, they integrate well with:
+
+- **Threading models**: Ring buffers work on raw JVM threads, virtual threads (Loom), or platform-specific threads. Pair with `ZIO.fork` or `Thread` as needed.
+- **Reactive streams**: Ring buffers can back reactive sources, where producers feed a `Source` and consumers pull from it. The ring buffer provides natural backpressure via `offer`'s return value.
+- **Event loops**: In game engines or event-driven systems, ring buffers connect event producers (input, network) to event dispatchers (main loop) with predictable latency.

package/reference/ringbuffer/index.mdx

@@ -0,0 +1,145 @@
+---
+id: index
+title: "RingBuffer"
+---
+
+Ring buffers are **fixed-size, lock-free queues** for efficiently exchanging elements between producer and consumer threads with minimal contention and cache-line effects. They use a circular array to recycle memory, eliminating garbage collection pressure from transient allocations. The `zio.blocks.ringbuffer` module provides four specialized implementations tuned for different producer/consumer thread patterns:
+
+```scala
+final class SpscRingBuffer[A <: AnyRef](val capacity: Int) {
+  def offer(a: A): Boolean
+  def take(): A
+  def size: Int
+  def isEmpty: Boolean
+  def isFull: Boolean
+  def drain(consumer: A => Unit, limit: Int): Int
+  def fill(supplier: () => A, limit: Int): Int
+}
+
+final class SpmcRingBuffer[A <: AnyRef](val capacity: Int) {
+  def offer(a: A): Boolean
+  def take(): A
+  def size: Int
+  def isEmpty: Boolean
+  def isFull: Boolean
+}
+
+final class MpscRingBuffer[A <: AnyRef](val capacity: Int) {
+  def offer(a: A): Boolean
+  def take(): A
+  def size: Int
+  def isEmpty: Boolean
+  def isFull: Boolean
+  def drain(consumer: A => Unit, limit: Int): Int
+}
+
+final class MpmcRingBuffer[A <: AnyRef](val capacity: Int) {
+  def offer(a: A): Boolean
+  def take(): A
+  def size: Int
+  def isEmpty: Boolean
+  def isFull: Boolean
+}
+```
+
+## Motivation
+
+Building low-latency systems — trading platforms, game engines, real-time event processors — requires careful control over memory allocation and CPU cache behavior. Standard JVM collections like `LinkedList` or `ArrayDeque` are convenient but have a cost: every enqueue/dequeue pair allocates a node, triggering garbage collection pauses that can destroy millisecond-scale latencies.
+
+A naive approach is to pre-allocate a large `Array[A]` and manually manage head/tail indices. This code shows a simplified single-threaded version:
+
+```scala mdoc:compile-only
+class SimpleRingBuffer {
+  // WARNING: Mutable state (vars) demonstrated here to show the problem;
+  // this is NOT how ring buffers actually solve concurrency.
+  private var head = 0
+  private var tail = 0
+  private val array = new Array[String](1024)
+
+  def offer(x: String): Boolean = {
+    if (tail - head >= array.length) false  // full
+    else {
+      array(tail % array.length) = x
+      tail += 1
+      true
+    }
+  }
+
+  def take(): String = {
+    if (head == tail) null  // empty
+    else {
+      val x = array(head % array.length)
+      head += 1
+      x
+    }
+  }
+}
+```
+
+This works for single-threaded code, but introduces a critical problem under concurrency: both threads read and write `head` and `tail` without synchronization, leading to lost updates, stale reads, and silent data corruption. Adding `synchronized` blocks solves the data race but reintroduces contention and latency pauses.
+
+Ring buffers solve both problems with **lock-free algorithms** and **cache-line padding**. A ring buffer provides:
+- **No garbage collection** — reuses the same array forever
+- **Lock-free access** — uses atomic compare-and-swap (CAS) for coordination, avoiding mutex contention
+- **Predictable latency** — no surprise GC pauses or lock waits
+- **Thread-specialized variants** — choose SPSC, MPSC, SPMC, or MPMC based on your thread pattern
+
+This module provides four implementations tuned for maximum throughput and minimal latency across all producer/consumer combinations.
+
+## Overview
+
+Ring buffers are high-performance data structures for:
+
+- **Event queues** in IO, networking, and game engines where throughput and latency matter
+- **Thread-safe work queues** with bounded capacity to backpressure senders
+- **Inter-thread communication** between producers and consumers with predictable latency
+- **Concurrent batch processing** where producers fill elements and consumers drain them
+
+## Why Ring Buffers
+
+Ring buffers excel when you need:
+
+- **Ultra-low latency** — lock-free algorithms and cache-line padding eliminate pauses from contention
+- **Predictable throughput** — no GC overhead since the same memory array is reused forever
+- **Bounded resources** — fixed capacity prevents runaway memory growth and enables backpressure
+- **High concurrency** — multiple implementations optimized for different thread patterns (SPSC, MPMC, etc.)
+
+How do ring buffers compare to other queue and collection types?
+
+### Comparison with Java and Scala Alternatives
+
+| Property                | RingBuffer (ZIO Blocks)                | `java.util.Queue` (ConcurrentLinkedQueue) | `scala.collection.concurrent.TrieMap` | Array + manual index     | Disruptor                |
+|-------------------------|----------------------------------------|-------------------------------------------|---------------------------------------|--------------------------|--------------------------|
+| **Allocation**          | Single upfront                         | Per-element nodes                         | Per-node allocations                  | Single upfront           | Single upfront           |
+| **Lock-free**           | Yes (CAS-based)                        | Yes                                       | Yes (CASes on trie nodes)             | Yes (if single-threaded) | Yes (CAS)                |
+| **GC pressure**         | Minimal (reuses slots)                 | High (node garbage)                       | High (trie node garbage)              | Minimal                  | Minimal                  |
+| **Bounded**             | Fixed capacity                         | Unbounded                                 | Unbounded                             | Fixed                    | Fixed (bounded capacity) |
+| **Thread patterns**     | Four variants (SPSC, MPSC, SPMC, MPMC) | Multi-producer/multi-consumer             | Multi-reader/multi-writer             | Limited (see impl)       | Multi-producer/consumer  |
+| **Predictable latency** | High (no GC)                           | Medium (GC pauses)                        | Medium (GC pauses)                    | High (if no contention)  | High                     |
+
+RingBuffer is ideal when you control both producer and consumer thread counts and want maximum performance. `java.util.Queue` is better if you need unbounded capacity; Disruptor is a comparable JVM alternative with similar guarantees.
+
+## Installation
+
+Add the ZIO Blocks Ring Buffer module to your `build.sbt`:
+
+```scala
+libraryDependencies += "dev.zio" %% "zio-blocks-ringbuffer" % "@VERSION@"
+```
+
+For Scala.js cross-platform support:
+
+```scala
+libraryDependencies += "dev.zio" %%% "zio-blocks-ringbuffer" % "@VERSION@"
+```
+
+## Implementations
+
+ZIO Blocks provides four optimized ring buffer implementations. Choose the one matching your producer/consumer thread counts:
+
+- **SPSC** — Single Producer, Single Consumer (⚡⚡⚡ **Fastest**)
+- **SPMC** — Single Producer, Multiple Consumers
+- **MPSC** — Multiple Producers, Single Consumer
+- **MPMC** — Multiple Producers, Multiple Consumers
+
+Use the sidebar for the per-implementation guides and the advanced topics page covering thread safety, cache-line padding, design patterns, and performance characteristics.

package/reference/ringbuffer/mpmc.mdx

@@ -0,0 +1,151 @@
+---
+id: mpmc
+title: "MPMC RingBuffer"
+---
+
+import MpmcDiagram from './MpmcDiagram.jsx';
+
+`MpmcRingBuffer[A]` is the fully general-purpose implementation for systems with multiple producer and consumer threads. It uses the **Vyukov/Dmitry sequence-buffer algorithm**, a sophisticated lock-free design that coordinates all access through monotonically increasing indices and per-slot sequence stamps—making every slot's state self-describing at any moment.
+
+## Algorithm
+
+`MpmcRingBuffer` handles the hardest case: **many producers and many consumers** all accessing the same buffer at once. It uses the **Vyukov/Dmitry algorithm**, which is a lock-free MPMC queue design.
+
+The challenge: when multiple producers might try to write to the same slot, and multiple consumers might try to read the same slot, we need a fair way to say "this slot is mine" without using locks.
+
+**The trick: Give each slot a "ticket number" that changes in a predictable cycle.**
+
+The algorithm runs two parallel arrays of the same length:
+
+- `buffer[i]` — holds the actual element at position `i`
+- `seqBuf[i]` — holds a *sequence stamp* at position `i`
+
+The sequence stamps are the heart of the algorithm. Each stamp encodes the *ownership state* of its slot: who is allowed to act on it and what they are allowed to do.
+
+On initialization, `seqBuf[i]` is set to `i`. The producer index `pIdx` and consumer index `cIdx` both start at zero. From here, every operation follows the same pattern: read the stamp, compute a single difference (`diff`), and branch on whether `diff` is zero, negative, or positive.
+
+At any moment, slot `i` (where `i = index & mask`) is in exactly one of three states:
+
+| stamp value                 | meaning                                          |
+|-----------------------------|--------------------------------------------------|
+| if `seq == pIdx`            | Slot is free — the producer at `pIdx` may write  |
+| if `seq == cIdx + 1`        | Data written — the consumer at `cIdx` may read   |
+| if `seq == cIdx + capacity` | Slot consumed — free for the producer's next lap |
+
+The producer looks for `diff = seq - pIdx == 0`. The consumer looks for `diff = seq - (cIdx + 1) == 0`. In both cases, a negative diff means the other side has fallen behind (buffer full or empty), and a positive diff means another thread already claimed this slot and you should retry.
+
+### Diagram
+
+To see the sequence buffer in action, use this interactive stepper. The component below implements the algorithm faithfully in React. Type any label, click **Offer** to enqueue or **Take** to dequeue, and watch the trace panel show every intermediate variable — `pIdx`, `slot`, `seq`, `diff` — and the exact decision the algorithm makes from them.
+
+<MpmcDiagram />
+
+Click "Step Producer" and "Step Consumer" to see how the algorithm coordinates access handoff without locks.
+
+Here is a complete walkthrough of every variable in the trace, in the order the algorithm computes them.
+
+### `pIdx` / `cIdx` — the monotonic counters
+
+These two numbers are the heartbeat of the entire algorithm. `pIdx` is the producer's counter and `cIdx` is the consumer's counter. They start at zero and *only ever increase* — they never wrap, never reset, never go backwards. After a million operations `pIdx` might be 1,000,000 and `cIdx` might be 999,996. The raw slot position is derived from them rather than stored directly, which is what makes the algorithm safe for multiple concurrent threads.
+
+### `slot = idx & mask` — the circular array index
+
+Because the buffer has a power-of-two capacity (4 in the demo), `mask = capacity - 1 = 3`, which in binary is `0011`. The bitwise AND strips everything above the lowest two bits, giving a number in the range `[0, 3]`. This is mathematically identical to `idx % capacity` but costs a single CPU instruction instead of a division. So `pIdx = 7` maps to slot `7 & 3 = 3`, and `pIdx = 8` maps back to slot `8 & 3 = 0` — that is the wrap-around.
+
+### `seq = seqBuf[slot]` — the sequence stamp
+
+Every slot carries its own stamp, completely independent of the other slots. The stamp is not a lock and not a boolean "occupied/free" flag — it is a number that encodes the *exact generation* of the slot. On construction `seqBuf[i] = i`, so slot 0 starts at 0, slot 1 at 1, and so on. After each write the stamp advances by 1. After each consume it advances by `capacity`. Because of this, slot 0's stamp trail across three laps looks like `0 → 1 → 4 → 5 → 8 → 9 → 12 → 13 …` — it grows forever and never repeats, which is what prevents the ABA problem entirely.
+
+### `expected` (take only) `= cIdx + 1`
+
+The producer, after winning its CAS and writing data, stamps the slot with `pIdx + 1`. So if a producer claimed slot 0 when `pIdx` was 4, it leaves `seqBuf[0] = 5`. The consumer that arrives with `cIdx = 4` therefore looks for `seqBuf[0] == cIdx + 1 == 5`. The `+ 1` is the handshake signal: *"a producer has finished writing here, and you are the right consumer to read it."* The offer trace does not need an `expected` row because the producer compares `seq` directly against `pIdx` (not `pIdx + 1`) — the slot is free when the stamp equals the producer index exactly.
+
+### `diff` — the three-way decision
+
+This is the key insight of the Vyukov algorithm. A single subtraction replaces what would otherwise be a tangle of conditional checks.
+
+For **offer**: `diff = seq − pIdx`
+- `diff == 0` — the stamp exactly matches the producer index, meaning no one has touched this slot since it was last released. The slot is yours. The thread does a CAS on `pIdx`, writes the element, then stamps `seqBuf[slot] = pIdx + 1`.
+- `diff < 0` — the stamp is *behind* the producer index. This means the slot is still occupied by data from the current lap that has not been consumed yet. The buffer is full. Return `false`.
+- `diff > 0` — the stamp is *ahead* of the producer index. Another producer already claimed this slot and advanced past it. Retry the loop with a fresh read of `pIdx`.
+
+For **take**: `diff = seq − expected` where `expected = cIdx + 1`
+- `diff == 0` — the stamp matches exactly what the producer left. Data is ready. CAS on `cIdx`, read the element, null out the slot for GC, stamp `seqBuf[slot] = cIdx + capacity` to release the slot for a future producer on the next lap.
+- `diff < 0` — the stamp is behind what the consumer expects, meaning the producer has not finished writing yet (or has not written at all). The buffer appears empty from this consumer's perspective. Return `null`.
+- `diff > 0` — another consumer already read this slot and advanced past it. Retry.
+
+### Why all three decisions are safe without any lock
+
+The diff check and the subsequent CAS form an atomic claim. Two producers might both read the same `pIdx` and both see `diff == 0`, but only one will win the CAS that advances `pIdx`. The loser sees the CAS fail, loops back, reads the new `pIdx`, and naturally ends up looking at the next slot. No explicit coordination between threads is ever needed — the sequence stamps and the monotonically increasing indices together make every slot's state self-describing at any point in time.
+
+## Creating Instances
+
+`MpmcRingBuffer[A]` is the fully general-purpose implementation supporting any number of producers and consumers. It uses the Vyukov/Dmitry algorithm with a parallel sequence buffer to coordinate access safely.
+
+```scala
+object MpmcRingBuffer {
+  def apply[A <: AnyRef](capacity: Int): MpmcRingBuffer[A]
+}
+```
+
+Creates a new MPMC ring buffer with the given capacity. The capacity must be a power of two >= 2 (the sequence buffer algorithm requires at least 2 slots). A capacity of 1 is valid for `SpscRingBuffer`, `SpmcRingBuffer`, and `MpscRingBuffer`, but `MpmcRingBuffer` needs at least 2 because its sequence stamp mechanism requires a second slot to distinguish the written-but-not-consumed state from the empty state.
+
+To create an MPMC buffer:
+
+```scala mdoc:compile-only
+import zio.blocks.ringbuffer.MpmcRingBuffer
+
+val rb = MpmcRingBuffer[String](128)
+```
+
+## Operations
+
+`MpmcRingBuffer` provides operations for multiple producers and consumers to exchange elements:
+
+### Inserting Elements — `MpmcRingBuffer#offer`
+
+Use `MpmcRingBuffer#offer` to insert an element with this signature:
+
+```scala
+final class MpmcRingBuffer[A <: AnyRef](val capacity: Int) {
+  def offer(a: A): Boolean
+}
+```
+
+Inserts the element without blocking. Returns `true` on successful insertion, `false` when the buffer is full. Raises `NullPointerException` if the element is `null`. Thread-safe; multiple producer threads may call this concurrently.
+
+### Removing Elements — `MpmcRingBuffer#take`
+
+Use `MpmcRingBuffer#take` to remove an element with this signature:
+
+```scala
+final class MpmcRingBuffer[A <: AnyRef](val capacity: Int) {
+  def take(): A
+}
+```
+
+Retrieves and removes an element from the front of the buffer. Returns immediately without blocking, providing the element or `null` if the buffer is empty. Thread-safe; multiple consumer threads may call this concurrently.
+
+### Checking State — `size`, `isEmpty`, `isFull`
+
+Ring buffers provide three query methods to check their state. Note that under concurrent access, these results are **approximate** — by the time the method returns, other threads may modify the buffer.
+
+All four implementations provide the same method signatures: `size`, `isEmpty`, and `isFull`. See the [`SpscRingBuffer` Operations](./spsc.mdx#operations) section for detailed descriptions and examples of these methods.
+
+## Examples
+
+### MPMC: General-Purpose Queue
+
+For workloads with multiple producers and consumers, use `MpmcRingBuffer`. This example demonstrates how multiple workers coordinate to process tasks from a shared queue.
+
+```scala mdoc:passthrough
+import docs.SourceFile
+
+SourceFile.print("zio-blocks-examples/src/main/scala/ringbuffer/MpmcExample.scala")
+```
+
+([source](https://github.com/zio/zio-blocks/blob/main/zio-blocks-examples/src/main/scala/ringbuffer/MpmcExample.scala))
+
+```bash
+sbt "zio-blocks-examples/runMain ringbuffer.MpmcExample"
+```

package/reference/ringbuffer/mpsc.mdx

@@ -0,0 +1,132 @@
+---
+id: mpsc
+title: "MPSC RingBuffer"
+---
+
+import MpscDiagram from './MpscDiagram.jsx';
+
+`MpscRingBuffer[A]` handles the inverse case: multiple producer threads safely offering elements to a single consumer thread. It uses a **hybrid design** combining producer-side CAS coordination with a FastFlow-style relaxed-poll consumer, balancing producer contention while keeping the consumer blazingly fast.
+
+## Algorithm
+
+`MpscRingBuffer` handles multiple producers with a single consumer, based on the **JCTools `MpscArrayQueue`** design. It's a hybrid: producers use CAS among themselves, while the consumer remains FastFlow-style.
+
+**How it works:**
+
+- The **producers** (multiple) coordinate via CAS on the shared `producerIndex`. Each producer claims a slot by atomically incrementing `producerIndex`, then writes its element with release semantics. A cached `producerLimit` (initialized to capacity) reduces volatile reads of `consumerIndex`.
+- The **consumer** (single) uses **FastFlow relaxed-poll semantics**: it reads array slots directly. A `null` slot indicates either the buffer is empty or a producer has claimed the slot via CAS but has not yet written the element (mid-write). In both cases, `take` returns `null` rather than spinning. The consumer clears the slot after reading.
+- The `producerLimit` is updated opportunistically (racy updates are benign) to reflect approximate available capacity.
+
+**Why hybrid?** Multiple producers need CAS to coordinate their offers, but the single consumer can achieve maximum speed using pure FastFlow (no CAS, no reading producer state).
+
+### Diagram
+
+To see the hybrid algorithm in action, use this interactive stepper. Type any label, click **Offer** to enqueue or **Take** to dequeue, and watch the trace panel show every intermediate variable — `pIdx`, `cIdx`, `size`, `slot`, `value` — and the exact decision the algorithm makes.
+
+<MpscDiagram />
+
+Here is a complete walkthrough of every variable in the trace, in the order the algorithm computes them.
+
+### `pIdx` / `cIdx` — the monotonic counters
+
+Like the MPMC algorithm, both counters start at zero and only ever increase — they never wrap, never reset, never go backwards. `pIdx` is shared by all producer threads: each producer atomically claims the next slot by performing a compare-and-swap (CAS) from `pIdx` to `pIdx + 1`. Whoever wins the CAS owns that slot. `cIdx` is read with a plain load because only one thread ever consumes, so no CAS is needed.
+
+### `size = pIdx − cIdx` — the occupancy check
+
+Before claiming a slot, the producer checks whether the buffer is full: if `pIdx − cIdx == capacity`, every slot is occupied and `offer` returns `false` immediately. The difference `pIdx − cIdx` is the number of elements currently in the buffer. Under real concurrent access, the JVM implementation maintains a cached `producerLimit` to avoid reading the volatile `consumerIndex` on every `offer` call — but the fundamental check is the same occupancy test shown here.
+
+### `slot = pIdx & mask` — the circular array index
+
+Because capacity is a power of two, `mask = capacity - 1`, and the bitwise AND strips high bits to give a slot number in `[0, capacity)`. This is mathematically equivalent to `pIdx % capacity` but costs a single CPU instruction. So `pIdx = 7` maps to slot `7 & 3 = 3`, and `pIdx = 8` wraps back to slot `0`.
+
+### `value = buf[slot]` — the FastFlow slot check
+
+The consumer uses the **FastFlow relaxed-poll pattern**: read the array slot directly with acquire semantics. If the slot is `null`, either the buffer is empty, or a producer has won the CAS but has not yet finished writing the element (mid-write). In both cases, `take` returns `null` rather than blocking or spinning — this is the *relaxed poll* semantic. This is why the consumer never reads `pIdx`; it derives all its information from the slot value itself.
+
+Once the producer wins its CAS, it writes the element with release semantics. The acquire/release pair guarantees the consumer will see the fully written element as soon as the slot is non-null.
+
+## Creating Instances
+
+`MpscRingBuffer[A]` allows multiple producer threads to offer elements concurrently via compare-and-swap on the producer index, while a single consumer thread takes elements efficiently.
+
+```scala
+object MpscRingBuffer {
+  def apply[A <: AnyRef](capacity: Int): MpscRingBuffer[A]
+}
+```
+
+Creates a new MPSC ring buffer with the given capacity. The capacity must be a positive power of two.
+
+To create an MPSC buffer:
+
+```scala mdoc:compile-only
+import zio.blocks.ringbuffer.MpscRingBuffer
+
+val rb = MpscRingBuffer[java.lang.Long](32)
+```
+
+## Operations
+
+`MpscRingBuffer` supports inserting elements from multiple producers, removing from a single consumer, and batch operations:
+
+### Inserting Elements — `MpscRingBuffer#offer`
+
+Use `MpscRingBuffer#offer` to insert an element with this signature:
+
+```scala
+final class MpscRingBuffer[A <: AnyRef](val capacity: Int) {
+  def offer(a: A): Boolean
+}
+```
+
+Inserts the element without blocking. Returns `true` on successful insertion, `false` when the buffer is full. Raises `NullPointerException` if the element is `null`. Thread-safe; multiple producer threads may call this concurrently.
+
+### Removing Elements — `MpscRingBuffer#take`
+
+Use `MpscRingBuffer#take` to remove an element with this signature:
+
+```scala
+final class MpscRingBuffer[A <: AnyRef](val capacity: Int) {
+  def take(): A
+}
+```
+
+Retrieves and removes an element from the front of the buffer. Returns immediately without blocking, providing the element or `null` if the buffer is empty. Call only from the single consumer thread.
+
+### Checking State — `size`, `isEmpty`, `isFull`
+
+Ring buffers provide three query methods to check their state. Note that under concurrent access, these results are **approximate** — by the time the method returns, other threads may modify the buffer.
+
+All four implementations provide the same method signatures: `size`, `isEmpty`, and `isFull`. See the [`SpscRingBuffer` Operations](./spsc.mdx#operations) section for detailed descriptions and examples of these methods.
+
+### Batch Operations — `MpscRingBuffer#drain`
+
+Use `MpscRingBuffer#drain` to consume up to N elements with this signature:
+
+```scala
+final class MpscRingBuffer[A <: AnyRef](val capacity: Int) {
+  def drain(consumer: A => Unit, limit: Int): Int
+}
+```
+
+Removes up to `limit` elements from the buffer, passing each to the `consumer` callback. Returns the number of elements actually drained. Raises `IllegalArgumentException` if `limit` is negative. Call only from the consumer thread. O(n) where n is the number of elements drained.
+
+**Note**: Uses relaxed poll semantics and stops at the first `null` slot, which may indicate either an empty buffer or a producer that has claimed a slot but has not yet written its element (mid-write). In the mid-write case, fewer than `limit` elements are returned even though more elements will become available shortly. If the callback throws, all elements passed to it up to that point remain consumed and the buffer is in a consistent state.
+
+## Examples
+
+### MPSC: Multiple Producers, Single Aggregator
+
+When multiple threads produce work for a single processor, use `MpscRingBuffer`. This example shows how three producer threads safely offer items to a single consumer.
+
+```scala mdoc:passthrough
+import docs.SourceFile
+
+SourceFile.print("zio-blocks-examples/src/main/scala/ringbuffer/MpscExample.scala")
+```
+
+([source](https://github.com/zio/zio-blocks/blob/main/zio-blocks-examples/src/main/scala/ringbuffer/MpscExample.scala))
+
+```bash
+sbt "zio-blocks-examples/runMain ringbuffer.MpscExample"
+```

package/reference/ringbuffer/spmc.mdx

@@ -0,0 +1,108 @@
+---
+id: spmc
+title: "SPMC RingBuffer"
+---
+
+import SpmcDiagram from './SpmcDiagram.jsx';
+
+`SpmcRingBuffer[A]` allows a single producer thread to efficiently feed multiple consumer threads. It uses an **index-based algorithm** where slot validity is determined by comparing producer and consumer indices, allowing multiple consumers to coordinate safely via CAS operations on a shared consumer index.
+
+## Algorithm
+
+`SpmcRingBuffer` allows a single producer to feed multiple consumers. The algorithm is **index-based**: slot validity is determined by comparing `producerIndex` and `consumerIndex`, not by null-checking slots.
+
+**How it works:**
+
+- The **producer** is single-threaded and never uses CAS. It maintains a `producerLimit` derived from reading the volatile `consumerIndex`. On the fast path, it checks its local limit; when exhausted, it refreshes by reading `consumerIndex`. This design avoids the producer ever reading consumer state on the fast path.
+- The **consumers** (any number) coordinate via a CAS loop on `consumerIndex`. Each consumer reads the element at its claimed index, then attempts to CAS `consumerIndex` forward. If CAS fails, it retries with a refreshed index. This ensures each element is claimed by exactly one consumer.
+- **No slot clearing by consumers:** Consumers do not write `null` after reading. Instead, the producer safely overwrites slots once its `producerLimit` check (based on `consumerIndex`) confirms all consumers have advanced past them. This eliminates the race that would occur if a consumer claimed a slot but hadn't yet cleared it.
+
+**Trade-off:** Consumer CAS introduces overhead under contention, but the producer remains extremely fast (no synchronization).
+
+### Diagram
+
+To see the single-producer multi-consumer algorithm in action, use this interactive stepper. Type any label, click **Offer** to enqueue (single producer) or **Take** to dequeue (any consumer), and watch the trace panel show every intermediate variable — `pIdx`, `cIdx`, `size`, `slot`, `element` — and the exact decision each side makes.
+
+<SpmcDiagram />
+
+Here is a complete walkthrough of every variable in the trace, in the order the algorithm computes them.
+
+### `pIdx` — the monotonic producer counter
+
+The producer has its own index that starts at zero and only ever increases. Because only one thread produces, `pIdx` is read and written with plain loads and stores — no CAS is needed. The producer's job is simple: check capacity (`pIdx - cIdx < capacity`), write to the slot, then advance `pIdx`.
+
+### `cIdx` — the monotonic consumer counter (multi-threaded)
+
+All consumers share a single `consumerIndex` counter. Because multiple consumers may be operating concurrently, each consumer reads `cIdx` with volatile semantics to see the most recent updates, then attempts to atomically advance it via CAS. If the CAS fails, another consumer claimed the slot first and the reader discards their read and retries.
+
+### `size = pIdx − cIdx` — the occupancy check
+
+Both sides use the same occupancy formula: `pIdx − cIdx` is the number of elements currently in the buffer. The producer checks if `size == capacity` to detect a full buffer. The consumer checks if `size == 0` to detect an empty buffer.
+
+### `slot = pIdx & mask` or `slot = cIdx & mask` — the circular array index
+
+Identical to all other ring buffer variants: because capacity is a power of two, the bitwise AND `& mask` replaces modulo division, giving a slot number in `[0, capacity)`. So `pIdx = 7` maps to slot `7 & 3 = 3`, and `pIdx = 8` wraps back to slot `0`.
+
+### `element = buf[slot]` — read-before-CAS
+
+This is the critical SPMC distinction. The consumer reads the element *before* attempting the CAS on `cIdx`. This ordering is essential: once the CAS succeeds and `cIdx` advances, the producer is permitted to overwrite that slot on its next lap. By reading the element first, the consumer guarantees it captures the value while the slot is still logically owned.
+
+In the trace, when a consumer takes an element, you will see the `element` row highlighted — this captures the read that must happen before the CAS.
+
+### Why SPMC doesn't clear slots
+
+Unlike MPSC (which uses FastFlow's null-check pattern), SPMC determines slot validity purely by index comparison: if `cIdx ≤ slot < pIdx`, the slot is live. After a consumer advances `cIdx`, the slot becomes "stale" — no longer live, but still holding the old value until the producer wraps around and overwrites it. This eliminates the race that would occur if a consumer had to null out the slot while holding the CAS; instead, the producer simply overwrites when it knows the consumer has advanced.
+
+The diagram marks stale slots with a dashed border and a "stale" label in grey.
+
+## Creating Instances
+
+`SpmcRingBuffer[A]` allows a single producer thread to offer elements while multiple consumer threads concurrently take elements via compare-and-swap on the consumer index. Use the companion object to instantiate a buffer:
+
+```scala
+object SpmcRingBuffer {
+  def apply[A <: AnyRef](capacity: Int): SpmcRingBuffer[A]
+}
+```
+
+The capacity must be a positive power of two. To create an SPMC buffer:
+
+```scala mdoc:compile-only
+import zio.blocks.ringbuffer.SpmcRingBuffer
+
+val rb = SpmcRingBuffer[java.lang.Integer](64)
+```
+
+## Operations
+
+`SpmcRingBuffer` provides three core operations for sending and receiving elements:
+
+### Inserting Elements — `SpmcRingBuffer#offer`
+
+Use `SpmcRingBuffer#offer` to insert an element with this signature:
+
+```scala
+final class SpmcRingBuffer[A <: AnyRef](val capacity: Int) {
+  def offer(a: A): Boolean
+}
+```
+
+Inserts the element without blocking. Returns `true` on successful insertion, `false` when the buffer is full. Raises `NullPointerException` if the element is `null`. Call only from the single producer thread; concurrent calls from multiple threads cause undefined behavior.
+
+### Removing Elements — `SpmcRingBuffer#take`
+
+Use `SpmcRingBuffer#take` to remove an element with this signature:
+
+```scala
+final class SpmcRingBuffer[A <: AnyRef](val capacity: Int) {
+  def take(): A
+}
+```
+
+Retrieves and removes an element from the front of the buffer. Returns immediately without blocking. Returns the element, or `null` if the buffer is empty. Thread-safe; multiple consumer threads may call this concurrently.
+
+### Checking State — `size`, `isEmpty`, `isFull`
+
+Ring buffers provide three query methods to check their state. Note that under concurrent access, these results are **approximate** — by the time the method returns, other threads may already modify the buffer.
+
+All four implementations provide the same method signatures: `size`, `isEmpty`, and `isFull`. See the [`SpscRingBuffer` Operations](./spsc.mdx#operations) section for detailed descriptions and examples of these methods.