This library is in flux. APIs may change without notice. Generated from source with koruc 0.1.7 on 11/4/2026.

Rings

import std/rings

Koru Standard Library: Lock-Free Ring Buffers

rings.kz · 3 tors

Koru Standard Library: Lock-Free Ring Buffers · 37 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: - Tors 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 — the named surface (the std/store model: a ring is a static, named at the declaration, addressed by name everywhere it is used): import std/rings std/rings:new(feed, capacity: 256) { value: u64 } std/rings:new(feed, capacity: 256) { reading: Reading } // proto element std/rings:enqueue(feed, v: 42) | ok |> ... | full |> handle_backpressure() std/rings:dequeue(feed) | some v |> process(v) // v IS the element, 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 tor = ALL observers see EVERY message - Perfect for telemetry, logging, PGO, debugging - Zero cost when no taps attached

~part new koru_std/rings.new.kz

Koru Standard Library: the `new` part of rings.kz — a named ring with a Koru declaration surface. Joined via `~part new` in rings.kz. std/rings:new(feed, capacity: 256) { value: u64 } std/rings:new(feed, capacity: 256) { reading: Reading } The `{ }` body is the shared declaration grammar — `name: Type` entries, the same shape `std/proto` writes its fields and `std/channel:new` writes its kinds. A ring declares exactly ONE: the element. The name labels the element for diagnostics and generated units; the type is a proto name or a scalar — protos collapse to structs and scalars ride the same machinery (the degenerate one-word element). What the declaration emits into the ring's home module: - `pub const <Proto> = struct { ... }` when the element is a proto and no other consumer derived it yet (the one-name-one-layout ruling). - `__KoruRingT_<n>` / `__koru_ring_<n>` — the typed MpmcRing cell. - `__ring_<n>_enqueue` { value: Elem } | ok | full - `__ring_<n>_dequeue` {} | some Elem | none - a `__rings_decl_<n>` marker line carrying `elem=<name>` so the chain steps validate the ring without re-reading this item. The ops are name-addressed (`std/rings:enqueue(feed, v)`) — a ring exists to be shared across flows and threads, so it is a named static, not a flow-bound handle: the std/list handle model refuses a handle that crosses a flow boundary, which is precisely where a ring does its work. No top-level imports — part files share the merged module's consts; a second `const std` per part lands as a duplicate member in the emitted program. Shared helpers — the channel.kz set, cut to what rings needs.

new

keywordcomptimetransform koru_std/rings.new.kz:259

~part leafgate koru_std/rings.leafgate.kz

Koru Standard Library: the `leafgate` part of rings.kz — proto-leaf reading for `new`. Joined via `~part leafgate` in rings.kz; merged into the rings module at load. The proto door's two forms (live `std/proto(Name)` decl, erased `// proto Name: ...` marker), the flattening walk, the host-type lower, and the emitted-struct dedup — everything `new` needs to read an element proto's leaves.

~part ops koru_std/rings.ops.kz

Koru Standard Library: the name-addressed ring ops — joined via `~part ops` in rings.kz. std/rings:enqueue(feed, v) | ok |> .. | full |> .. std/rings:dequeue(feed) | some v |> .. | none |> .. The subject is the ring's declared name, not a handle: a ring is a named static (the std/store model), shared across flows and threads by construction. Each site rewrites to the tor `std/rings:new` generated — `__ring_<n>_enqueue` / `__ring_<n>_dequeue` — so the call carries the element type the declaration fixed, and the site's `|` arms ride untouched. Ordering law (same as store/channel): the declaration precedes its uses in document order — transforms run in source order and a site finds the ring by the `__rings_decl_<n>` marker `new` emitted. No top-level imports — part files share the merged module's consts.

enqueue

keywordcomptimetransform koru_std/rings.ops.kz:121

dequeue

keywordcomptimetransform koru_std/rings.ops.kz:135

~part home koru_std/rings.home.kz

Ring home resolution — where a ring declaration lives, spelled for synthesized path qualifiers. Joined via `~part home` in rings.kz; merged into the rings module. The generic tree walk (moduleHome) lives in ast_functional — every comptime module needs it and .kz parts cannot share private fns. This file declares the module's ast_functional import; rings.kz's `std`/`ast` are already module-wide.