zio.blocks.ringbuffer

package zio.blocks.ringbuffer

Members list

Type members

Classlikes

case object BuildInfo

This object was generated by sbt-buildinfo.

This object was generated by sbt-buildinfo.

Attributes

Source
BuildInfo.scala
Supertypes
trait Singleton
trait Product
trait Mirror
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
Self type
BuildInfo.type
final class DoubleSpscRingBuffer(val capacity: Int)

High-performance non-blocking SPSC ring buffer specialized for Double.

High-performance non-blocking SPSC ring buffer specialized for Double.

Layout: a single Array[Long] storing raw doubleToRawLongBits. The FastFlow signal uses two reserved NaN bit patterns: EMPTY_BITS (0xFFF8_0000_0000_0001L) is the empty marker, DONE_BITS (0xFFF8_0000_0000_0002L) is the in-band end-of-stream marker. If the user offers a Double whose raw bits happen to equal either reserved pattern, it is canonicalized to Double.NaN's standard bit pattern (0x7FF8_0000_0000_0000L) on insertion.

This canonicalization is unobservable: IEEE 754 guarantees NaN != NaN, all NaNs compare equal under reference NaN semantics, and there is no portable Scala/Java way to round-trip a specific NaN payload through arithmetic. The remapping only affects two specific raw bit patterns, which the user could not have meaningfully produced through normal floating-point operations.

In-band "done" sentinel: producers can call offerDone() to insert the end-of-stream marker after the last data value. Consumers reading via pollPacked() receive EMPTY_BITS for empty, DONE_BITS for the sentinel, or the raw doubleToRawLongBits value for data. This removes the need for a separate control queue alongside the data queue.

One memory-ordered op per insert/remove, one cache line per slot.

SPSC: one producer thread, one consumer thread.

Value parameters

capacity

must be a positive power of two

Attributes

Companion
object
Source
DoubleSpscRingBuffer.scala
Supertypes
class Object
trait Matchable
class Any
object DoubleSpscRingBuffer

Attributes

Companion
class
Source
DoubleSpscRingBuffer.scala
Supertypes
class Object
trait Matchable
class Any
Self type
final class FloatSpscRingBuffer(val capacity: Int)

High-performance non-blocking SPSC ring buffer specialized for Float.

High-performance non-blocking SPSC ring buffer specialized for Float.

Layout: a single Array[Long]. Each slot packs both the data and the occupancy/control signal into one 64-bit word:

  • bits 32..63: tag (0 = empty, 1 = data, 2 = done)
  • bits 0..31: Float.floatToRawIntBits(value) (only meaningful when tag == 1)

The packed slot itself is the FastFlow signal; one memory-ordered op per insert/remove, one cache line per slot. All Float values are representable (including 0.0f, NaN, +/-Inf); the non-zero tag guarantees a stored slot is never zero.

In-band "done" sentinel: producers can call offerDone() to insert an end-of-stream marker after the last data value. Consumers reading via pollPacked() receive EMPTY_PACKED for empty, DONE_PACKED for the sentinel, or a TAG_FULL | float bits value for data. This removes the need for a separate control queue alongside the data queue.

SPSC: one producer thread, one consumer thread.

Value parameters

capacity

must be a positive power of two

Attributes

Companion
object
Source
FloatSpscRingBuffer.scala
Supertypes
class Object
trait Matchable
class Any
object FloatSpscRingBuffer

Attributes

Companion
class
Source
FloatSpscRingBuffer.scala
Supertypes
class Object
trait Matchable
class Any
Self type
object IntSpscRingBuffer

Attributes

Companion
class
Source
IntSpscRingBuffer.scala
Supertypes
class Object
trait Matchable
class Any
Self type
final class IntSpscRingBuffer(val capacity: Int)

High-performance non-blocking SPSC ring buffer specialized for Int.

High-performance non-blocking SPSC ring buffer specialized for Int.

Layout: a single Array[Long]. Each slot packs both the data and the occupancy/control signal into one 64-bit word:

  • bits 32..63: tag (0 = empty, 1 = data, 2 = done)
  • bits 0..31: the user's Int value (only meaningful when tag == 1)

This makes the slot's own value act as the FastFlow signal: every insert/remove is a single memory-ordered op on a single cache line. Zero is the empty marker because the array is zero-initialized; a stored value with a non-zero tag is always non-zero regardless of the Int payload (including 0, Int.MinValue, Int.MaxValue, etc.).

In-band "done" sentinel: producers can call offerDone() to insert an end-of-stream marker after the last data value. Consumers reading via pollPacked() receive EMPTY_PACKED for empty, DONE_PACKED for the sentinel, or a TAG_FULL | Int payload value for data. This removes the need for a separate control queue alongside the data queue.

SPSC: one producer thread, one consumer thread.

Value parameters

capacity

must be a positive power of two

Attributes

Companion
object
Source
IntSpscRingBuffer.scala
Supertypes
class Object
trait Matchable
class Any
final class LongSpscRingBuffer(val capacity: Int)

High-performance non-blocking SPSC ring buffer specialized for Long.

High-performance non-blocking SPSC ring buffer specialized for Long.

Layout: a single Array[Long]. Since every 64-bit pattern is a legal Long, the FastFlow signal requires reserving sentinel values: EMPTY (Long.MinValue) means "slot empty" and DONE (Long.MinValue + 1L) is the in-band end-of-stream marker. The array is pre-filled with EMPTY at construction.

offer(EMPTY) and offer(DONE) throw IllegalArgumentException (the same shape of contract as SpscRingBuffer.offer(null)). This costs two bit patterns out of 2^64 in exchange for a single memory-ordered op per insert/remove on a single cache line per slot, and removes the need for a separate control queue.

In-band "done" sentinel: producers can call offerDone() to insert the end-of-stream marker after the last data value. Consumers reading via pollPacked() receive EMPTY for empty, DONE for the sentinel, or the raw Long payload for data.

SPSC: one producer thread, one consumer thread.

Value parameters

capacity

must be a positive power of two

Attributes

Companion
object
Source
LongSpscRingBuffer.scala
Supertypes
class Object
trait Matchable
class Any
object LongSpscRingBuffer

Attributes

Companion
class
Source
LongSpscRingBuffer.scala
Supertypes
class Object
trait Matchable
class Any
Self type
final class MpmcRingBuffer[A <: AnyRef](val capacity: Int)

A high-performance, non-blocking MPMC (Multi-Producer Multi-Consumer) ring buffer for generic reference types.

A high-performance, non-blocking MPMC (Multi-Producer Multi-Consumer) ring buffer for generic reference types.

Uses the Vyukov/Dmitry bounded MPMC queue algorithm with a parallel sequence buffer. Each slot in the sequence buffer carries a stamp that indicates whether the slot is available for writing (stamp == expected producer index) or reading (stamp == expected consumer index + 1). Both producerIndex and consumerIndex are advanced via CAS, allowing any number of threads to call offer and poll concurrently.

Thread safety: Fully thread-safe for any combination of concurrent producers and consumers. No external synchronization is required.

Null elements are not permitted. offer(null) throws NullPointerException.

Value parameters

capacity

the buffer capacity, must be a power of two >= 2 (the sequence buffer algorithm requires at least 2 slots to distinguish written from consumed)

Attributes

Companion
object
Source
MpmcRingBuffer.scala
Supertypes
class Object
trait Matchable
class Any
object MpmcRingBuffer

Attributes

Companion
class
Source
MpmcRingBuffer.scala
Supertypes
class Object
trait Matchable
class Any
Self type
object MpscRingBuffer

Attributes

Companion
class
Source
MpscRingBuffer.scala
Supertypes
class Object
trait Matchable
class Any
Self type
final class MpscRingBuffer[A <: AnyRef](val capacity: Int)

A high-performance, non-blocking Multi-Producer Single-Consumer (MPSC) ring buffer for generic reference types.

A high-performance, non-blocking Multi-Producer Single-Consumer (MPSC) ring buffer for generic reference types.

Multiple threads may call offer concurrently, but only a single consumer thread may call take. This is enforced by contract — no runtime check is performed for the single-consumer invariant.

The algorithm follows the JCTools MpscArrayQueue design:

  • Producers claim a slot via CAS on producerIndex, then write the element with release semantics.
  • The consumer reads elements using acquire semantics. A null slot indicates either an empty queue or a producer that has claimed a slot but has not yet written the element (the "FastFlow" pattern). In the latter case, take returns null rather than spinning, following relaxedPoll semantics.
  • A cached producerLimit avoids reading consumerIndex on every offer, reducing cross-core traffic.

Null elements are not permitted. offer(null) throws NullPointerException.

Value parameters

capacity

the buffer capacity, must be a positive power of two

Attributes

Companion
object
Source
MpscRingBuffer.scala
Supertypes
class Object
trait Matchable
class Any
object SpmcRingBuffer

Attributes

Companion
class
Source
SpmcRingBuffer.scala
Supertypes
class Object
trait Matchable
class Any
Self type
final class SpmcRingBuffer[A <: AnyRef](val capacity: Int)

A high-performance, non-blocking SPMC (Single-Producer Multi-Consumer) ring buffer for generic reference types.

A high-performance, non-blocking SPMC (Single-Producer Multi-Consumer) ring buffer for generic reference types.

The producer uses index-based capacity checking with a cached producerLimit derived from consumerIndex. On the fast path, the producer avoids reading the volatile consumerIndex entirely; the slow path re-reads it to refresh the limit. The consumer side uses a CAS loop on consumerIndex to allow multiple consumer threads to safely dequeue elements concurrently.

'''Design:''' Consumers do not clear (null) array slots after reading. Instead, the producer freely overwrites slots once index-based capacity checking confirms the consumer has advanced past them. This eliminates the producer-consumer slot-clearing race that would otherwise occur in SPMC when a consumer CAS-claims a slot but hasn't yet nulled it. The element's validity is determined solely by comparing producerIndex and consumerIndex, never by null-checking slots.

Optimized for SPMC: exactly one producer thread and any number of consumer threads may access the buffer concurrently. Using multiple producer threads results in undefined behavior.

Null elements are not permitted. offer(null) throws NullPointerException.

Value parameters

capacity

the buffer capacity, must be a positive power of two

Attributes

Companion
object
Source
SpmcRingBuffer.scala
Supertypes
class Object
trait Matchable
class Any
object SpscRingBuffer

Attributes

Companion
class
Source
SpscRingBuffer.scala
Supertypes
class Object
trait Matchable
class Any
Self type
final class SpscRingBuffer[A <: AnyRef](val capacity: Int)

A high-performance, non-blocking SPSC ring buffer for generic reference types.

A high-performance, non-blocking SPSC ring buffer for generic reference types.

Uses the FastFlow pattern: the array element's null/non-null state IS the synchronization signal. The producer never reads consumerIndex; the consumer never reads producerIndex. This minimizes cross-core cache traffic.

Optimized for SPSC (Single Producer, Single Consumer). Only one producer thread and one consumer thread should access the buffer concurrently.

Null elements are not permitted. offer(null) throws NullPointerException.

Value parameters

capacity

the buffer capacity, must be a positive power of two

Attributes

Companion
object
Source
SpscRingBuffer.scala
Supertypes
class Object
trait Matchable
class Any