This library is in flux. APIs may change without notice. Generated from source with koruc 0.1.7 on 8/19/2026.
Rings
~import std/ringsKoru Standard Library: Lock-Free Ring Buffers
rings.kz · 2 tors
Koru Standard Library: Lock-Free Ring Buffers · 39 more lines
Koru Standard Library: Lock-Free Ring Buffers
High-performance MPMC (multi-producer, multi-consumer) ring buffers
based on Dmitry Vyukov's bounded queue algorithm.
DESIGN PHILOSOPHY:
- Events are implicitly tappable - no hooks, no callbacks
- Users observe via tap() without modifying this library
- Multicast: multiple taps = multiple observers, ALL see every message
- `when` clauses fuse predicates into the producer (zero-cost filtering)
USAGE:
const std = @import("std");
import std/rings
// Instantiate with your type (Zig generics - fully specialized at comptime)
const MyRing = std.rings.MpmcRing(u64, 1024);
var ring = MyRing.init();
// Enqueue (tappable!) - identity branches
std/rings:enqueue(ring: &ring, value: 42)
| ok |> ...
| full |> handle_backpressure()
// Dequeue (tappable!) - identity branch with value
std/rings:dequeue(ring: &ring)
| some v |> process(v) // v IS the u64, not v.value
| none |> wait_for_producer()
OBSERVABILITY (implicit - no library changes needed):
tap(std/rings:enqueue -> *) | ok e |> telemetry:record_enqueue()
tap(std/rings:enqueue -> *) | full |> metrics:backpressure()
tap(std/rings:dequeue -> *) | some v when v.ring == my_ring |> log(v)
MULTICAST:
Unlike traditional MPMC where one consumer wins, taps enable TRUE multicast:
- Multiple taps on same event = ALL observers see EVERY message
- Perfect for telemetry, logging, PGO, debugging
- Zero cost when no taps attached
enqueue
koru_std/rings.kz:167// KORU EVENTS (implicitly tappable)
//
// These events wrap the ring operations. Users instantiate MpmcRing with their
// concrete type, then use these events with that type.
//
// Example:
// const Ring = MpmcRing(u64, 1024);
// var ring = Ring.init();
// std/rings:enqueue(ring: &ring, value: 42)
//
// Generic type alias for event signatures
// Users replace with their concrete Ring type
// (Future: derive handler to auto-generate typed events)
~pub tor enqueue { ring: *anyopaque, value: u64 }
| ok
| fulldequeue
koru_std/rings.kz:180~pub tor dequeue { ring: *anyopaque }
| some u64
| none