@zio.dev/zio-blocks 0.0.28 → 0.0.29

package/reference/schema-evolution/as.md

@@ -39,13 +39,13 @@ The bidirectional data flow looks like this:
 `As` is part of `zio-blocks-schema`:
 
 ```scala
-libraryDependencies += "dev.zio" %% "zio-blocks-schema" % "0.0.28"
+libraryDependencies += "dev.zio" %% "zio-blocks-schema" % "0.0.29"
 ```
 
 For Scala.js and Scala Native, use `%%%`:
 
 ```scala
-libraryDependencies += "dev.zio" %%% "zio-blocks-schema" % "0.0.28"
+libraryDependencies += "dev.zio" %%% "zio-blocks-schema" % "0.0.29"
 ```
 
 Supported Scala versions: 2.13.x and 3.x.
@@ -240,7 +240,7 @@ trait As[A, B] {
 
 ```scala
 val revAs: As[LongBox, IntBox] = boxAs.reverse
-// revAs: As[LongBox, IntBox] = zio.blocks.schema.As$$anon$1@15f56a1f
+// revAs: As[LongBox, IntBox] = zio.blocks.schema.As$$anon$1@29407f04
 
 revAs.into(LongBox(5L))
 // res11: Either[SchemaError, IntBox] = Right(IntBox(5))
@@ -302,7 +302,7 @@ We import `As.reverseInto` and use it to obtain the reverse `Into[Int, String]`:
 import As.reverseInto
 
 val intToStr: Into[Int, String] = reverseInto[String, Int]
-// intToStr: Into[Int, String] = zio.blocks.schema.AsLowPriorityImplicits$$Lambda$16607/0x00007f8eb27d4250@40672bcc
+// intToStr: Into[Int, String] = zio.blocks.schema.AsLowPriorityImplicits$$Lambda$16771/0x00007f092a81f330@1cdf3706
 intToStr.into(42)
 // res14: Either[SchemaError, String] = Right("42")
 ```

package/reference/schema-evolution/into.md

@@ -69,13 +69,13 @@ Compare this to a manual implementation:
 `Into` is part of the `zio-blocks-schema` module:
 
 ```scala
-libraryDependencies += "dev.zio" %% "zio-blocks-schema" % "0.0.28"
+libraryDependencies += "dev.zio" %% "zio-blocks-schema" % "0.0.29"
 ```
 
 For Scala.js:
 
 ```scala
-libraryDependencies += "dev.zio" %%% "zio-blocks-schema" % "0.0.28"
+libraryDependencies += "dev.zio" %%% "zio-blocks-schema" % "0.0.29"
 ```
 
 Supported Scala versions: 2.13.x and 3.x.

package/reference/schema-expr.md

@@ -70,13 +70,13 @@ val result: Either[OpticCheck, Seq[Boolean]] = combined.eval(alice)
 ## Installation
 
 ```scala
-libraryDependencies += "dev.zio" %% "zio-blocks-schema" % "0.0.28"
+libraryDependencies += "dev.zio" %% "zio-blocks-schema" % "0.0.29"
 ```
 
 For cross-platform (Scala.js):
 
 ```scala
-libraryDependencies += "dev.zio" %%% "zio-blocks-schema" % "0.0.28"
+libraryDependencies += "dev.zio" %%% "zio-blocks-schema" % "0.0.29"
 ```
 
 Supported Scala versions: 2.13.x and 3.x.

package/reference/type-class-derivation.md

@@ -107,7 +107,7 @@ trait Deriver[TC[_]] {
   def deriveRecord[F[_, _], A](
     fields: IndexedSeq[Term[F, A, ?]],
     typeId: TypeId[A],
-    binding: Binding[BindingType.Record, A],
+    binding: Binding.Record[A],
     doc: Doc,
     modifiers: Seq[Modifier.Reflect],
     defaultValue: Option[A],
@@ -194,7 +194,7 @@ object DeriveShow extends Deriver[Show] {
   override def derivePrimitive[A](
     primitiveType: PrimitiveType[A],
     typeId: TypeId[A],
-    binding: Binding[BindingType.Primitive, A],
+    binding: Binding.Primitive[A],
     doc: Doc,
     modifiers: Seq[Modifier.Reflect],
     defaultValue: Option[A],
@@ -213,7 +213,7 @@ object DeriveShow extends Deriver[Show] {
   override def deriveRecord[F[_, _], A](
     fields: IndexedSeq[Term[F, A, ?]],
     typeId: TypeId[A],
-    binding: Binding[BindingType.Record, A],
+    binding: Binding.Record[A],
     doc: Doc,
     modifiers: Seq[Modifier.Reflect],
     defaultValue: Option[A],
@@ -255,7 +255,7 @@ object DeriveShow extends Deriver[Show] {
   override def deriveVariant[F[_, _], A](
     cases: IndexedSeq[Term[F, A, ?]],
     typeId: TypeId[A],
-    binding: Binding[BindingType.Variant, A],
+    binding: Binding.Variant[A],
     doc: Doc,
     modifiers: Seq[Modifier.Reflect],
     defaultValue: Option[A],
@@ -289,7 +289,7 @@ object DeriveShow extends Deriver[Show] {
   override def deriveSequence[F[_, _], C[_], A](
     element: Reflect[F, A],
     typeId: TypeId[C[A]],
-    binding: Binding[BindingType.Seq[C], C[A]],
+    binding: Binding.Seq[C, A],
     doc: Doc,
     modifiers: Seq[Modifier.Reflect],
     defaultValue: Option[C[A]],
@@ -315,7 +315,7 @@ object DeriveShow extends Deriver[Show] {
     key: Reflect[F, K],
     value: Reflect[F, V],
     typeId: TypeId[M[K, V]],
-    binding: Binding[BindingType.Map[M], M[K, V]],
+    binding: Binding.Map[M, K, V],
     doc: Doc,
     modifiers: Seq[Modifier.Reflect],
     defaultValue: Option[M[K, V]],
@@ -341,7 +341,7 @@ object DeriveShow extends Deriver[Show] {
   }
 
   override def deriveDynamic[F[_, _]](
-    binding: Binding[BindingType.Dynamic, DynamicValue],
+    binding: Binding.Dynamic,
     doc: Doc,
     modifiers: Seq[Modifier.Reflect],
     defaultValue: Option[DynamicValue],
@@ -380,7 +380,7 @@ object DeriveShow extends Deriver[Show] {
   override def deriveWrapper[F[_, _], A, B](
     wrapped: Reflect[F, B],
     typeId: TypeId[A],
-    binding: Binding[BindingType.Wrapper[A, B], A],
+    binding: Binding.Wrapper[A, B],
     doc: Doc,
     modifiers: Seq[Modifier.Reflect],
     defaultValue: Option[A],
@@ -414,7 +414,7 @@ When the derivation process encounters a primitive type (e.g., `String`, `Int`),
 def derivePrimitive[A](
   primitiveType: PrimitiveType[A],
   typeId: TypeId[A],
-  binding: Binding[BindingType.Primitive, A],
+  binding: Binding.Primitive[A],
   doc: Doc,
   modifiers: Seq[Modifier.Reflect],
   defaultValue: Option[A],
@@ -444,7 +444,7 @@ When the derivation process encounters a record type (e.g., a case class), it ca
 def deriveRecord[F[_, _], A](
   fields: IndexedSeq[Term[F, A, ?]],
   typeId: TypeId[A],
-  binding: Binding[BindingType.Record, A],
+  binding: Binding.Record[A],
   doc: Doc,
   modifiers: Seq[Modifier.Reflect],
   defaultValue: Option[A],
@@ -512,7 +512,7 @@ When the derivation process encounters a variant type (e.g., a sealed trait with
 def deriveVariant[F[_, _], A](
   cases: IndexedSeq[Term[F, A, ?]],
   typeId: TypeId[A],
-  binding: Binding[BindingType.Variant, A],
+  binding: Binding.Variant[A],
   doc: Doc,
   modifiers: Seq[Modifier.Reflect],
   defaultValue: Option[A],
@@ -556,7 +556,7 @@ When the derivation process encounters a sequence type (e.g., `List[A]`), it cal
 def deriveSequence[F[_, _], C[_], A](
   element: Reflect[F, A],
   typeId: TypeId[C[A]],
-  binding: Binding[BindingType.Seq[C], C[A]],
+  binding: Binding.Seq[C, A],
   doc: Doc,
   modifiers: Seq[Modifier.Reflect],
   defaultValue: Option[C[A]],
@@ -590,7 +590,7 @@ def deriveMap[F[_, _], M[_, _], K, V](
   key: Reflect[F, K],
   value: Reflect[F, V],
   typeId: TypeId[M[K, V]],
-  binding: Binding[BindingType.Map[M], M[K, V]],
+  binding: Binding.Map[M, K, V],
   doc: Doc,
   modifiers: Seq[Modifier.Reflect],
   defaultValue: Option[M[K, V]],
@@ -620,11 +620,11 @@ The derivation process for maps is similar to sequences, but we have two child i
 
 ### Dynamic Derivation
 
-When the derivation process encounters a dynamic type (e.g., `DynamicValue`), it calls the `deriveDynamic` method of the `Deriver`. This method receives a `Binding[BindingType.Dynamic, DynamicValue]` representing the dynamic type, along with other metadata such as documentation, modifiers, default values, and examples:
+When the derivation process encounters a dynamic type (e.g., `DynamicValue`), it calls the `deriveDynamic` method of the `Deriver`. This method receives a `Binding.Dynamic` representing the dynamic type, along with other metadata such as documentation, modifiers, default values, and examples:
 
 ```scala
 def deriveDynamic[F[_, _]](
-  binding: Binding[BindingType.Dynamic, DynamicValue],
+  binding: Binding.Dynamic,
   doc: Doc,
   modifiers: Seq[Modifier.Reflect],
   defaultValue: Option[DynamicValue],
@@ -667,7 +667,7 @@ When the derivation process encounters a wrapper type (e.g., a value class, opaq
 def deriveWrapper[F[_, _], A, B](
   wrapped: Reflect[F, B],
   typeId: TypeId[A],
-  binding: Binding[BindingType.Wrapper[A, B], A],
+  binding: Binding.Wrapper[A, B],
   doc: Doc,
   modifiers: Seq[Modifier.Reflect],
   defaultValue: Option[A],
@@ -875,7 +875,7 @@ object DeriveGen extends Deriver[Gen] {
   override def derivePrimitive[A](
     primitiveType: PrimitiveType[A],
     typeId: TypeId[A],
-    binding: Binding[BindingType.Primitive, A],
+    binding: Binding.Primitive[A],
     doc: Doc,
     modifiers: Seq[Modifier.Reflect],
     defaultValue: Option[A],
@@ -913,7 +913,7 @@ object DeriveGen extends Deriver[Gen] {
   override def deriveRecord[F[_, _], A](
     fields: IndexedSeq[Term[F, A, ?]],
     typeId: TypeId[A],
-    binding: Binding[BindingType.Record, A],
+    binding: Binding.Record[A],
     doc: Doc,
     modifiers: Seq[Modifier.Reflect],
     defaultValue: Option[A],
@@ -957,7 +957,7 @@ object DeriveGen extends Deriver[Gen] {
   override def deriveVariant[F[_, _], A](
     cases: IndexedSeq[Term[F, A, ?]],
     typeId: TypeId[A],
-    binding: Binding[BindingType.Variant, A],
+    binding: Binding.Variant[A],
     doc: Doc,
     modifiers: Seq[Modifier.Reflect],
     defaultValue: Option[A],
@@ -990,7 +990,7 @@ object DeriveGen extends Deriver[Gen] {
   override def deriveSequence[F[_, _], C[_], A](
     element: Reflect[F, A],
     typeId: TypeId[C[A]],
-    binding: Binding[BindingType.Seq[C], C[A]],
+    binding: Binding.Seq[C, A],
     doc: Doc,
     modifiers: Seq[Modifier.Reflect],
     defaultValue: Option[C[A]],
@@ -1033,7 +1033,7 @@ object DeriveGen extends Deriver[Gen] {
     key: Reflect[F, K],
     value: Reflect[F, V],
     typeId: TypeId[M[K, V]],
-    binding: Binding[BindingType.Map[M], M[K, V]],
+    binding: Binding.Map[M, K, V],
     doc: Doc,
     modifiers: Seq[Modifier.Reflect],
     defaultValue: Option[M[K, V]],
@@ -1069,7 +1069,7 @@ object DeriveGen extends Deriver[Gen] {
    * content.
    */
   override def deriveDynamic[F[_, _]](
-    binding: Binding[BindingType.Dynamic, DynamicValue],
+    binding: Binding.Dynamic,
     doc: Doc,
     modifiers: Seq[Modifier.Reflect],
     defaultValue: Option[DynamicValue],
@@ -1124,7 +1124,7 @@ object DeriveGen extends Deriver[Gen] {
   override def deriveWrapper[F[_, _], A, B](
     wrapped: Reflect[F, B],
     typeId: TypeId[A],
-    binding: Binding[BindingType.Wrapper[A, B], A],
+    binding: Binding.Wrapper[A, B],
     doc: Doc,
     modifiers: Seq[Modifier.Reflect],
     defaultValue: Option[A],
@@ -1153,7 +1153,7 @@ The `derivePrimitive` method is responsible for deriving a `Gen` instance for pr
 def derivePrimitive[A](
   primitiveType: PrimitiveType[A],
   typeId: TypeId[A],
-  binding: Binding[BindingType.Primitive, A],
+  binding: Binding.Primitive[A],
   doc: Doc,
   modifiers: Seq[Modifier.Reflect],
   defaultValue: Option[A],
@@ -1187,7 +1187,7 @@ The `deriveRecord` method is responsible for deriving a `Gen` instance for recor
 def deriveRecord[F[_, _], A](
   fields: IndexedSeq[Term[F, A, ?]],
   typeId: TypeId[A],
-  binding: Binding[BindingType.Record, A],
+  binding: Binding.Record[A],
   doc: Doc,
   modifiers: Seq[Modifier.Reflect],
   defaultValue: Option[A],
@@ -1233,7 +1233,7 @@ The `deriveVariant` method is responsible for deriving a `Gen` instance for vari
 def deriveVariant[F[_, _], A](
   cases: IndexedSeq[Term[F, A, ?]],
   typeId: TypeId[A],
-  binding: Binding[BindingType.Variant, A],
+  binding: Binding.Variant[A],
   doc: Doc,
   modifiers: Seq[Modifier.Reflect],
   defaultValue: Option[A],
@@ -1268,7 +1268,7 @@ The `deriveSequence` method is responsible for deriving a `Gen` instance for seq
 def deriveSequence[F[_, _], C[_], A](
   element: Reflect[F, A],
   typeId: TypeId[C[A]],
-  binding: Binding[BindingType.Seq[C], C[A]],
+  binding: Binding.Seq[C, A],
   doc: Doc,
   modifiers: Seq[Modifier.Reflect],
   defaultValue: Option[C[A]],
@@ -1313,7 +1313,7 @@ def deriveMap[F[_, _], M[_, _], K, V](
   key: Reflect[F, K],
   value: Reflect[F, V],
   typeId: TypeId[M[K, V]],
-  binding: Binding[BindingType.Map[M], M[K, V]],
+  binding: Binding.Map[M, K, V],
   doc: Doc,
   modifiers: Seq[Modifier.Reflect],
   defaultValue: Option[M[K, V]],
@@ -1352,7 +1352,7 @@ The `deriveDynamic` method is responsible for deriving a `Gen` instance for dyna
 
 ```scala
 def deriveDynamic[F[_, _]](
-  binding: Binding[BindingType.Dynamic, DynamicValue],
+  binding: Binding.Dynamic,
   doc: Doc,
   modifiers: Seq[Modifier.Reflect],
   defaultValue: Option[DynamicValue],
@@ -1415,7 +1415,7 @@ The `deriveWrapper` method is responsible for deriving a `Gen` instance for wrap
 def deriveWrapper[F[_, _], A, B](
   wrapped: Reflect[F, B],
   typeId: TypeId[A],
-  binding: Binding[BindingType.Wrapper[A, B], A],
+  binding: Binding.Wrapper[A, B],
   doc: Doc,
   modifiers: Seq[Modifier.Reflect],
   defaultValue: Option[A],
@@ -1456,7 +1456,7 @@ Now we can use the derived `Gen[Person]` instance to generate random `Person` va
 
 ```scala
 val random = new Random(42) // Seeded for reproducible output
-// random: Random = scala.util.Random@5cfafbe0
+// random: Random = scala.util.Random@1d1d8934
 
 Person.gen.generate(random)
 // res14: Person = Person(name = "p", age = -1360544799)

package/ringbuffer.md

@@ -0,0 +1,249 @@
+---
+id: ringbuffer
+title: "Ring Buffer"
+---
+
+# ZIO Blocks — Ring Buffer (`zio.blocks.ringbuffer`)
+
+`zio.blocks.ringbuffer` is a family of **high-performance, bounded ring buffers** for the JVM (and Scala.js). Each variant is optimized for a specific producer/consumer threading pattern—pick the one that matches your use case and get the fastest possible inter-thread communication with zero dependencies.
+
+All variants expose `offer` (returns `false` if full) and `take` (returns `null` if empty)—both non-blocking. Capacity must be a **power of two** (enables bitwise masking instead of modulo). Elements must be **non-null reference types** (`A <: AnyRef`).
+
+## Ring buffer variants
+
+| Type | Producers | Consumers | Algorithm |
+|------|-----------|-----------|-----------|
+| `SpscRingBuffer` | 1 | 1 | FastFlow (null/non-null signaling) |
+| `SpmcRingBuffer` | 1 | Many | Index-based capacity + CAS consumers |
+| `MpscRingBuffer` | Many | 1 | CAS producers + relaxed poll |
+| `MpmcRingBuffer` | Many | Many | Vyukov/Dmitry sequence buffer |
+
+**Naming convention:** `S` = single, `M` = multi, `p` = producer, `c` = consumer.
+
+---
+
+## Installation
+
+```scala
+libraryDependencies += "dev.zio" %% "zio-blocks-ringbuffer" % "0.0.29"
+```
+
+---
+
+## Quick start
+
+```scala
+import zio.blocks.ringbuffer.SpscRingBuffer
+
+val buf = SpscRingBuffer[String](1024) // capacity must be a power of 2
+
+// Producer thread
+buf.offer("hello") // true if inserted, false if full
+
+// Consumer thread
+val msg: String = buf.take() // element or null if empty
+```
+
+---
+
+## API
+
+Every ring buffer provides:
+
+```scala
+def offer(a: A): Boolean   // insert; returns false if full
+def take(): A               // remove; returns null if empty
+def size: Int               // approximate element count
+def isEmpty: Boolean        // approximate emptiness check
+def isFull: Boolean         // approximate fullness check
+```
+
+`SpscRingBuffer` additionally provides batch operations:
+
+```scala
+def drain(consumer: A => Unit, limit: Int): Int  // drain up to limit elements
+def fill(supplier: () => A, limit: Int): Int      // fill up to limit slots
+```
+
+All `size`/`isEmpty`/`isFull` values are **approximate** under concurrency—they are snapshots that may be stale by the time the caller acts on them.
+
+---
+
+## Choosing a variant
+
+Use the most constrained variant that fits your threading model:
+
+| Scenario | Recommended |
+|----------|-------------|
+| Dedicated pipeline: one writer thread, one reader thread | `SpscRingBuffer` |
+| Fan-in: many writers, one reader (e.g., logging, event aggregation) | `MpscRingBuffer` |
+| Fan-out: one writer, many readers (e.g., work distribution) | `SpmcRingBuffer` |
+| General purpose: any number of writers and readers | `MpmcRingBuffer` |
+
+---
+
+## Usage examples
+
+### SPSC with drain/fill
+
+```scala
+import zio.blocks.ringbuffer.SpscRingBuffer
+
+val buf = SpscRingBuffer[java.lang.Integer](64)
+
+// Producer: batch-fill from a data source
+var seq = 0
+val filled = buf.fill(() => { seq += 1; Integer.valueOf(seq) }, 32)
+println(s"Filled $filled elements")
+
+// Consumer: batch-drain into a processor
+val drained = buf.drain(e => println(s"Processing $e"), 32)
+println(s"Drained $drained elements")
+```
+
+### MPSC fan-in (multiple producers, single consumer)
+
+```scala
+import zio.blocks.ringbuffer.MpscRingBuffer
+
+val buf = MpscRingBuffer[String](256)
+
+// Multiple producer threads
+for (i <- 0 until 4) {
+  new Thread(() => {
+    for (j <- 0 until 100)
+      buf.offer(s"producer-$i: message-$j")
+  }).start()
+}
+
+// Single consumer thread
+new Thread(() => {
+  var msg = buf.take()
+  while (msg != null) {
+    println(msg)
+    msg = buf.take()
+  }
+}).start()
+```
+
+### SPMC fan-out (single producer, multiple consumers)
+
+```scala
+import zio.blocks.ringbuffer.SpmcRingBuffer
+
+val buf = SpmcRingBuffer[String](256)
+
+// Single producer thread
+new Thread(() => {
+  for (i <- 0 until 400)
+    while (!buf.offer(s"task-$i")) {} // retry if full
+}).start()
+
+// Multiple consumer (worker) threads
+for (w <- 0 until 4) {
+  new Thread(() => {
+    var msg = buf.take()
+    while (msg != null) {
+      println(s"worker-$w: $msg")
+      msg = buf.take()
+    }
+  }).start()
+}
+```
+
+### Non-blocking try-once with fallback
+
+```scala
+import zio.blocks.ringbuffer.MpmcRingBuffer
+
+val buf = MpmcRingBuffer[String](64)
+
+// Try to offer without blocking; handle backpressure yourself
+if (!buf.offer("data")) {
+  // buffer is full — drop, log, or retry later
+  println("Buffer full, applying backpressure")
+}
+
+// Try to take without blocking
+val result = buf.take()
+if (result != null) {
+  println(s"Got: $result")
+} else {
+  // buffer is empty — do other work
+}
+```
+
+---
+
+## Design notes
+
+### FastFlow pattern (SPSC)
+
+`SpscRingBuffer` uses the FastFlow algorithm: the **null/non-null state of an array slot** is the synchronization signal. The producer never reads `consumerIndex`; the consumer never reads `producerIndex`. This minimizes cross-core cache traffic to a single cache line per operation.
+
+A **look-ahead step** (`capacity/4`, capped at 4096) lets the producer batch-check multiple future slots at once, further reducing the frequency of slow-path reads.
+
+### Vyukov/Dmitry sequence buffer (MPMC)
+
+`MpmcRingBuffer` uses a parallel `Long` sequence buffer alongside the data array. Each slot carries a stamp indicating whether it is available for writing or reading. Both `producerIndex` and `consumerIndex` are advanced via CAS, allowing any number of threads on both sides. The minimum capacity is 2 (the algorithm requires at least 2 slots to distinguish written from consumed).
+
+### CAS-based producers (MPSC)
+
+`MpscRingBuffer` follows the JCTools `MpscArrayQueue` design: producers claim a slot via CAS on `producerIndex`, then write the element with release semantics. A cached `producerLimit` avoids reading `consumerIndex` on every offer, reducing cross-core traffic. The consumer side uses relaxed poll semantics—a `null` slot means either empty or a producer mid-write.
+
+### Index-based SPMC
+
+`SpmcRingBuffer` uses index-based capacity checking on the producer side (no CAS needed for a single producer). Consumers use a CAS loop on `consumerIndex`. Consumers read the element *before* the CAS to avoid a race with the producer overwriting the slot. Consumers do not null array slots after reading—the producer overwrites them on the next lap.
+
+### Cache-line padding
+
+All ring buffers use **128-byte padding regions** (16 `Long` fields) between producer and consumer fields. This prevents false sharing on all architectures, including Apple Silicon which uses 128-byte cache lines (most x86 CPUs use 64-byte lines).
+
+The padding is implemented via a class hierarchy:
+
+```
+Pad0 → ProducerFields → Pad1 → ConsumerFields → Pad2
+```
+
+### VarHandle for memory ordering
+
+All JVM implementations use `java.lang.invoke.VarHandle` (Java 9+) for acquire/release semantics instead of `sun.misc.Unsafe`. This is the recommended modern approach for lock-free data structures on the JVM.
+
+### Power-of-two masking
+
+Capacity must be a power of two. This allows `index & (capacity - 1)` instead of `index % capacity`, which is significantly faster because bitwise AND compiles to a single CPU instruction.
+
+---
+
+## Thread-safety contract
+
+Violating the threading contract (e.g., calling `take` from multiple threads on an `SpscRingBuffer`) results in **undefined behavior**. No runtime check is performed—this is enforced by contract for maximum performance.
+
+| Type | `offer` | `take` |
+|------|---------|--------|
+| `SpscRingBuffer` | Single producer thread only | Single consumer thread only |
+| `SpmcRingBuffer` | Single producer thread only | Any number of consumer threads |
+| `MpscRingBuffer` | Any number of producer threads | Single consumer thread only |
+| `MpmcRingBuffer` | Any number of producer threads | Any number of consumer threads |
+
+---
+
+## Performance characteristics
+
+| Operation | Complexity |
+|-----------|-----------|
+| `offer` | Lock-free (SPSC/SPMC: wait-free) |
+| `take` | Lock-free (SPSC/MPSC: wait-free) |
+
+**SPSC** is the fastest: no CAS, no locks, minimal cache-line traffic. Use it whenever your threading model allows a dedicated producer-consumer pair.
+
+---
+
+## Cross-platform support
+
+On **Scala.js**, all ring buffer types compile and provide the same API surface. Since Scala.js is single-threaded, the JS implementations use plain reads and writes with no memory ordering primitives.
+
+| Platform | Support |
+|----------|---------|
+| JVM | Full concurrency support |
+| Scala.js | Sequential (same API) |

package/sidebars.js

@@ -13,7 +13,6 @@ const sidebars = {
          "reference/binding-resolver",
          "reference/registers",
          "reference/typeid",
-         "reference/allows",
          "reference/modifier",
          "reference/dynamic-value",
          "reference/dynamic-schema",
@@ -40,14 +39,27 @@ const sidebars = {
            ]
          },
          "reference/context",
-         "scope",
+         {
+           type: "category",
+           label: "Resource Management & DI",
+           link: { type: "doc", id: "reference/resource-management-di/index" },
+           items: [
+             "reference/resource-management-di/resource",
+             "reference/resource-management-di/scope",
+             "reference/resource-management-di/wire",
+           ]
+         },
+         "reference/combinators",
          "reference/docs",
          "reference/json",
          "reference/json-patch",
+         "reference/json-differ",
          "reference/json-schema",
          "reference/xml",
          "reference/syntax",
          "reference/media-type",
+         "reference/http-model",
+         "ringbuffer",
       ]
     },
     {