✓
Passing This code compiles and runs correctly.
Code
// ============================================================================
// Koru Implementation: Producer/Consumer with MPMC Ring
// ============================================================================
// Tests idiomatic Koru concurrent programming:
// - MPMC ring (Vyukov's lock-free algorithm — byte-identical to
// koru_std.koru_rings.MpmcRing, the impl std/rings lowers to)
// - Producer spawned via std.Thread inside a ~proc host step, sharing the
// ring through a *Ring passed tor-to-tor — no generated-name reach
// - Consumer loop expressed as a #loop/@label jump pair
// - All control flow visible as event transitions
//
// The ring impl is byte-identical to the Zig baseline's and verified
// instruction-identical in the binary (objdump diff 2026-09-30: same
// ldapr/cas/stlr sequence both sides). The #loop driver switches on an
// in-loop `const` handler result, so the consumer loop carries no
// union-tag stores or tests: success path is Zig's plus one branch
// (loop-exit ordering), 0 strb/tbz/cset in the loop body.
// The ~25-30% deficit this test once measured was neither: it was
// ring PLACEMENT — create-ring heap-allocates (a tor's frame cannot
// host a cross-thread ring) while the baseline stack-allocated.
// Stack placement is ~25% faster on this machine for BOTH languages
// (zig+heap measured ~121ms ≈ koru ~120ms; zig+stack ~92ms).
// baseline.zig now page_allocator-allocates to match — at equal
// allocation the programs measure parity (104.6 vs 107.5 min).
// The perf table's job: bound drift around this normalized floor.
//
// Below the transports sits a layer this benchmark cannot see: taps
// and effect-branch watches fuse the listener into the producer's
// continuation tree at compile time — the same mechanism either way,
// emitting the same static-call shape (measured identical at equal
// workload). Fusion is only valid while both sides share a stack;
// a ring is what the fusion becomes when it cannot fuse. Go has no
// equivalent layer — its channel is always transport.
// ============================================================================
const std = @import("std");
// ============================================================================
// MPMC Ring Implementation (vendored — same Vyukov algorithm std/rings emits)
// ============================================================================
const atomic = std.atomic;
const BUFFER_SIZE = 1024;
fn MpmcRing(comptime T: type, comptime capacity: usize) type {
if (capacity & (capacity - 1) != 0) {
@compileError("Ring capacity must be power of 2");
}
const CacheLine = 64;
const Slot = struct {
seq: atomic.Value(usize),
value: T,
};
return struct {
const Self = @This();
head: atomic.Value(usize) align(CacheLine),
_pad1: [CacheLine - @sizeOf(atomic.Value(usize))]u8 = undefined,
tail: atomic.Value(usize) align(CacheLine),
_pad2: [CacheLine - @sizeOf(atomic.Value(usize))]u8 = undefined,
slots: [capacity]Slot align(CacheLine),
pub fn init() Self {
var self = Self{
.head = atomic.Value(usize).init(0),
.tail = atomic.Value(usize).init(0),
.slots = undefined,
};
for (&self.slots, 0..) |*slot, i| {
slot.seq = atomic.Value(usize).init(i);
slot.value = undefined;
}
return self;
}
pub fn tryEnqueue(self: *Self, value: T) bool {
var pos = self.head.load(.monotonic);
while (true) {
const slot = &self.slots[pos & (capacity - 1)];
const seq = slot.seq.load(.acquire);
const dif = @as(isize, @intCast(seq)) -% @as(isize, @intCast(pos));
if (dif == 0) {
if (self.head.cmpxchgWeak(
pos,
pos + 1,
.monotonic,
.monotonic,
) == null) {
slot.value = value;
slot.seq.store(pos + 1, .release);
return true;
}
pos = self.head.load(.monotonic);
} else if (dif < 0) {
return false;
} else {
pos = self.head.load(.monotonic);
std.Thread.yield() catch {};
}
}
}
pub fn tryDequeue(self: *Self) ?T {
var pos = self.tail.load(.monotonic);
while (true) {
const slot = &self.slots[pos & (capacity - 1)];
const seq = slot.seq.load(.acquire);
const dif = @as(isize, @intCast(seq)) -% @as(isize, @intCast(pos + 1));
if (dif == 0) {
if (self.tail.cmpxchgWeak(
pos,
pos + 1,
.monotonic,
.monotonic,
) == null) {
const value = slot.value;
slot.seq.store(pos + capacity, .release);
return value;
}
pos = self.tail.load(.monotonic);
} else if (dif < 0) {
return null;
} else {
pos = self.tail.load(.monotonic);
std.Thread.yield() catch {};
}
}
}
};
}
const Ring = MpmcRing(u64, BUFFER_SIZE);
const MESSAGES: u64 = 10_000_000;
// ============================================================================
// Koru Events - Ring Operations
// ============================================================================
~tor create-ring {} -> *Ring
~proc create-ring|zig {
// Allocate ring on heap (needs to outlive this function)
const ring_storage = std.heap.page_allocator.create(Ring) catch unreachable;
ring_storage.* = Ring.init();
return ring_storage;
}
~tor spawn-producer { ring: *Ring }
~proc spawn-producer|zig {
// Spawn producer thread
const producer = std.Thread.spawn(.{}, struct {
fn run(r: *Ring) void {
var i: u64 = 0;
while (i < MESSAGES) : (i += 1) {
while (!r.tryEnqueue(i)) {
std.Thread.yield() catch {};
}
}
}
}.run, .{ring}) catch unreachable;
// Detach - we don't need to join
producer.detach();
}
~tor dequeue { ring: *Ring }
| some u64
| none
~proc dequeue|zig {
if (ring.tryDequeue()) |value| {
return .{ .some = value };
}
return .none;
}
~tor consume-loop { ring: *Ring, sum: u64, received: u64 }
| continue { sum: u64, received: u64 }
| done u64
~consume-loop = dequeue(ring)
| some msg |> check-if-done(sum: sum + msg, received: received + 1)
| continue s => continue { s.sum, s.received }
| done s => done s
| none |> yield-then-continue(sum, received): s => continue { s.sum, s.received }
~tor check-if-done { sum: u64, received: u64 }
| continue { sum: u64, received: u64 }
| done u64
~proc check-if-done|zig {
if (received >= MESSAGES) {
return .{ .done = sum };
} else {
return .{ .continue = .{ .sum = sum, .received = received } };
}
}
~tor yield-then-continue { sum: u64, received: u64 } -> { sum: u64, received: u64 }
~proc yield-then-continue|zig {
std.Thread.yield() catch {};
return .{ .sum = sum, .received = received };
}
~tor validate { sum: u64 }
~proc validate|zig {
const expected: u64 = MESSAGES * (MESSAGES - 1) / 2;
if (sum == expected) {
std.debug.print("✓ Koru: Validated {} messages (checksum: {})\n", .{ MESSAGES, sum });
} else {
std.debug.print("✗ Koru: CHECKSUM MISMATCH! got {}, expected {}\n", .{ sum, expected });
}
}
// ============================================================================
// Main Flow - Idiomatic Koru Consumer Loop
// ============================================================================
~create-ring(): r |> spawn-producer(ring: r) |> #loop consume-loop(ring: r, sum: 0, received: 0)
| continue s |> @loop(ring: r, s.sum, s.received)
| done s |> validate(sum: s)
Supporting Files
[package]
name = "rust_baseline"
version = "0.0.0"
edition = "2021"
[[bin]]
name = "rust_baseline"
path = "baseline.rs"
[dependencies]
crossbeam = "=0.8.4"
[profile.release]
opt-level = 3
lto = true
codegen-units = 1
# Handoff — union-tag dispatch weight in emitted flow loops
**Objective:** make `#loop` / flow continuation dispatch emit register/jump
dispatch instead of materializing union tags through memory. This is a
general emitter improvement — every flow loop in every program pays it,
not just this benchmark. Fix lands in `src/`, never in emitted artifacts.
**Tree pin:** authored against koru main @ 714b76d3c (2026-10-01).
Verify file:line refs against current HEAD before trusting them.
## Verified facts (evidence, not narration)
The benchmark: 10M u64 messages, 1 producer thread + 1 consumer thread,
capacity-256 Vyukov MPMC ring, checksum-validated. `input.kz` (Koru) vs
`baseline.zig` (hand-written Zig), both `std.heap.page_allocator`-allocated.
- **Ring loop instruction-identical.** objdump of `koru_output` vs
`zig_output` shows the same acquire-load/CAS/release-store sequence.
- **Producer thread instruction-shape-identical.** Both `entryFn`
functions have the same branch skeleton at the same offsets.
- **Consumer carries real debris:** ~9 flag-byte ops (`strb`/`ldrb`/`tbz`)
per unrolled pair of iterations vs 0 in Zig. These are union-tag stores
and constant-folded tag tests surviving instruction selection.
- **The debris is ~free in this workload.** A hand-fused emitted variant
(4 flag ops vs Zig's 3) ran the same wall time. Emitted weight, zero
measured cost here — but "free" is workload-dependent.
- **Head-to-head: Koru won 31/80 interleaved runs**; mins within 2%
(109.9 vs 108.0), medians/means within ~4%, tilting Zig. Residual tilt
unresolved — could be unroll packing (Koru 2 CAS sites vs Zig 1),
layout luck, or laptop spin noise.
## Ruled out by measurement (do not retry)
- `inline fn` on `__koru_handler_impl` — identical flag traffic.
- Deleting `_ = &x` discards — identical flag traffic.
- Flattening intermediate unions (keeping outer contract) — 17→15 flags,
no wall-time change.
- Full hand-fused consumer — 4 flags, same wall time. The flags are a
symptom worth deleting, not the perf driver in THIS benchmark.
- Stack-vs-heap ring placement WAS the ~25% earlier "deficit" — now
normalized; both sides page-allocate.
## Emitter anatomy (the fix surface)
`src/visitor_emitter.zig` (5363 lines):
- `:2387` — `__koru_self_loop: switch (@as(enum { ... }))` — self-tail
dispatch loop EXISTS.
- `:3028` — "dispatch loop — the mutual generalization of the
self-tail-loop" — the generalization point.
- `:3430`–`:3469` — `is_self_loop` / `self_loop_canonical` detection,
`while (true)` wrapper emission.
- `:1873` — "OPTIMIZED: Native loop from IR" path.
- `emitSelfTailReentry` — re-entry emission.
- `emitSubflowContinuations` (:3582, :3900 call sites) — where chain
continuation dispatch is emitted.
**Key observation:** `output_emitted.zig` in this dir contains NO
`__koru_self_loop` — the consume chain (`consume_loop` → `dequeue` →
`check_if_done`, re-entered by the `#loop` driver `flow0`) does not take
the self-loop path. Two candidate root causes:
1. The chain is not self-recursive — it's a multi-tor cycle — so
`is_self_loop` never fires. The `:3028` "mutual generalization" may be
the intended home for this case and may not be complete.
2. Even where dispatch loops fire, the driver emits
`var result_N = handler(...)` + memory-resident union + switch on the
tag byte, instead of switching directly on the call result — an
address-taken aggregate that survives SROA as a lone i8 alloca
(`%.sroa.0...alloca i8` in LLVM IR).
Lars's hypothesis to check first: a loop jumping into a **single-branch**
target may already have (or deserve) a tag-free fast path — a one-variant
dispatch needs no tag at all, just the jump.
## Verification protocol (non-negotiable)
- Decisive check is `objdump -d` on the real test binaries — count flag
ops in the consumer region. Target: 0–1, matching Zig.
- Rebuild via `./run_regression.sh 420_006_rings_vs_channels` — checksum
must still print 49999995000000.
- Interleaved timing (K,Z,K,Z alternating, ≥30 pairs) is the honest
estimator; block-ordered hyperfine means on a laptop are noise-grade.
- Wall-time improvement may be ~0 on this workload — that is a FINE
result: the win is less emitted weight, verified at instruction level.
- Do NOT patch `output_emitted.zig` and call it a fix — artifact edits
are diagnostics only ("patch the artifact, not a mock" measures the
ceiling; the emitter change is the fix).
## Droplet note
`koru-benchmarks/scripts/bench-on-droplet.sh` runs the benchmarks suite
on a dedicated-vCPU DO droplet (x86_64 — separate board from M2). As of
2026-10-01 `doctl` auth is 401 — Lars must `doctl auth init`. This test
is NOT in that suite; either port it or `KEEP=1` and run binaries by hand.
// Go Baseline: Producer/Consumer with Buffered Channels
//
// Tests idiomatic Go concurrency:
// - Buffered channel (1024 capacity, like MPMC ring)
// - Goroutines (2 threads: producer + consumer)
// - Channel send/receive (10M messages)
// - Synchronization (WaitGroup)
// - Data integrity (checksum validation)
//
// This is how you'd actually write concurrent Go code.
package main
import (
"fmt"
"sync"
)
const MESSAGES = 10_000_000
const BUFFER_SIZE = 1024
func main() {
// Buffered channel - like MPMC ring with 1024 capacity
messages := make(chan uint64, BUFFER_SIZE)
var wg sync.WaitGroup
wg.Add(1)
// Producer goroutine - send 10M messages
go func() {
defer wg.Done()
for i := uint64(0); i < MESSAGES; i++ {
messages <- i
}
close(messages)
}()
// Consumer runs on MAIN THREAD (same as Zig, Rust, and Koru!)
var sum uint64
for msg := range messages {
sum += msg
}
// Wait for producer to complete
wg.Wait()
// Validate checksum (sum of 0 to N-1 = N*(N-1)/2)
expected := uint64(MESSAGES * (MESSAGES - 1) / 2)
if sum == expected {
fmt.Printf("✓ Go: Validated %d messages (checksum: %d)\n", MESSAGES, sum)
} else {
fmt.Printf("✗ Go: CHECKSUM MISMATCH! got %d, expected %d\n", sum, expected)
}
}
// Rust Baseline: Producer/Consumer with Crossbeam Channels
//
// Tests idiomatic Rust concurrency:
// - Bounded channel (1024 capacity, like MPMC ring and Go channels)
// - Threads (2 threads: producer + consumer)
// - Channel send/receive (10M messages)
// - Zero-cost abstractions (no runtime overhead)
// - Data integrity (checksum validation)
//
// Uses crossbeam for fair comparison:
// - Bounded channels (matching Go's buffered channels)
// - Lock-free implementation (matching Zig's MPMC ring)
// - No async runtime overhead (matching Zig's approach)
//
// This is how you'd actually write concurrent Rust code with channels.
use crossbeam::channel::bounded;
use std::thread;
const MESSAGES: u64 = 10_000_000;
const BUFFER_SIZE: usize = 1024;
fn main() {
// Bounded channel - like Go's buffered channel and Zig's MPMC ring
let (tx, rx) = bounded(BUFFER_SIZE);
// Producer thread - send 10M messages
let producer = thread::spawn(move || {
for i in 0..MESSAGES {
tx.send(i).unwrap();
}
// Channel automatically closed when tx is dropped
});
// Consumer runs on MAIN THREAD (same as Zig and Koru!)
let mut sum = 0u64;
for msg in rx {
sum += msg;
}
// Wait for producer to finish
producer.join().unwrap();
// Validate checksum (sum of 0 to N-1 = N*(N-1)/2)
let expected = MESSAGES * (MESSAGES - 1) / 2;
if sum == expected {
println!(
"✓ Rust: Validated {} messages (checksum: {})",
MESSAGES, sum
);
} else {
println!(
"✗ Rust: CHECKSUM MISMATCH! got {}, expected {}",
sum, expected
);
}
}
// Zig Baseline: Producer/Consumer with MPMC Ring
//
// Tests Vyukov's lock-free MPMC ring buffer:
// - MPMC ring (1024 capacity, lock-free atomics)
// - Threads (2 threads: producer + consumer)
// - Enqueue/dequeue (10M messages)
// - Synchronization (thread join)
// - Data integrity (checksum validation)
//
// MPMC ring vendored from beist-rings (https://github.com/...)
// Algorithm: Dmitry Vyukov's bounded MPMC queue
const std = @import("std");
const atomic = std.atomic;
const MESSAGES = 10_000_000;
const BUFFER_SIZE = 1024;
/// Vyukov's bounded MPMC ring buffer
fn MpmcRing(comptime T: type, comptime capacity: usize) type {
if (capacity & (capacity - 1) != 0) {
@compileError("Ring capacity must be power of 2");
}
const CacheLine = 64;
const Slot = struct {
seq: atomic.Value(usize),
value: T,
};
return struct {
const Self = @This();
head: atomic.Value(usize) align(CacheLine),
_pad1: [CacheLine - @sizeOf(atomic.Value(usize))]u8 = undefined,
tail: atomic.Value(usize) align(CacheLine),
_pad2: [CacheLine - @sizeOf(atomic.Value(usize))]u8 = undefined,
slots: [capacity]Slot align(CacheLine),
pub fn init() Self {
var self = Self{
.head = atomic.Value(usize).init(0),
.tail = atomic.Value(usize).init(0),
.slots = undefined,
};
for (&self.slots, 0..) |*slot, i| {
slot.seq = atomic.Value(usize).init(i);
slot.value = undefined;
}
return self;
}
pub fn tryEnqueue(self: *Self, value: T) bool {
var pos = self.head.load(.monotonic);
while (true) {
const slot = &self.slots[pos & (capacity - 1)];
const seq = slot.seq.load(.acquire);
const dif = @as(isize, @intCast(seq)) -% @as(isize, @intCast(pos));
if (dif == 0) {
if (self.head.cmpxchgWeak(
pos,
pos + 1,
.monotonic,
.monotonic,
) == null) {
slot.value = value;
slot.seq.store(pos + 1, .release);
return true;
}
pos = self.head.load(.monotonic);
} else if (dif < 0) {
return false;
} else {
pos = self.head.load(.monotonic);
std.Thread.yield() catch {};
}
}
}
pub fn tryDequeue(self: *Self) ?T {
var pos = self.tail.load(.monotonic);
while (true) {
const slot = &self.slots[pos & (capacity - 1)];
const seq = slot.seq.load(.acquire);
const dif = @as(isize, @intCast(seq)) -% @as(isize, @intCast(pos + 1));
if (dif == 0) {
if (self.tail.cmpxchgWeak(
pos,
pos + 1,
.monotonic,
.monotonic,
) == null) {
const value = slot.value;
slot.seq.store(pos + capacity, .release);
return value;
}
pos = self.tail.load(.monotonic);
} else if (dif < 0) {
return null;
} else {
pos = self.tail.load(.monotonic);
std.Thread.yield() catch {};
}
}
}
};
}
pub fn main() !void {
// Heap-allocated to match the Koru program's create-ring — a stack
// ring here measured ~25% faster than the same ring on a fresh
// mmap page (verified 2026-09-30: stack ~92ms vs heap ~121ms min),
// which silently taxed the Koru side of this comparison. Both
// programs now pay the same allocation cost so the table measures
// emitted code, not placement luck.
const ring_storage = std.heap.page_allocator.create(MpmcRing(u64, BUFFER_SIZE)) catch unreachable;
ring_storage.* = MpmcRing(u64, BUFFER_SIZE).init();
const ring = ring_storage;
var sum: u64 = 0;
// Producer thread
const producer = try std.Thread.spawn(.{}, struct {
fn run(r: *MpmcRing(u64, BUFFER_SIZE)) void {
var i: u64 = 0;
while (i < MESSAGES) : (i += 1) {
while (!r.tryEnqueue(i)) {
std.Thread.yield() catch {};
}
}
}
}.run, .{ring});
// Consumer runs on MAIN THREAD (same as Koru!)
var received: u64 = 0;
while (received < MESSAGES) {
if (ring.tryDequeue()) |value| {
sum +%= value;
received += 1;
} else {
std.Thread.yield() catch {};
}
}
producer.join();
// Validate checksum
const expected: u64 = MESSAGES * (MESSAGES - 1) / 2;
if (sum == expected) {
std.debug.print("✓ Zig: Validated {} messages (checksum: {})\n", .{ MESSAGES, sum });
} else {
std.debug.print("✗ Zig: CHECKSUM MISMATCH! got {}, expected {}\n", .{ sum, expected });
}
}
#!/bin/bash
# Benchmark: Concurrent Message Passing
# Compare Go channels vs Zig MPMC rings vs Rust channels vs Koru ring flow
#
# Tests:
# - Go: Buffered channels (idiomatic Go)
# - Zig: MPMC ring (Vyukov's lock-free algorithm)
# - Rust: Crossbeam bounded channels (lock-free)
# - Koru: MPMC ring fed by a spawned host thread, flow consumer
#
# All send/receive 10M messages between producer/consumer threads.
# Koru is the reference column; the guard is Koru/Zig < THRESHOLD.
#
# (The bchan MPSC leg referenced by the original script was never committed —
# vendor_bchan is an empty gitlink and baseline_bchan.zig never existed.
# Taps and effect-branch watches are excluded by design, not omission: both
# fuse the listener into the producer's continuation tree at compile time —
# the same mechanism, emitting the same static-call shape (measured identical
# at 4.3ms/10M). That is a language-native layer BELOW transports, valid only
# while both sides share a stack. A ring is what the fusion becomes when it
# cannot fuse. There is no transport here to benchmark.)
set -e
echo "============================================"
echo " CONCURRENT MESSAGE PASSING BENCHMARK"
echo " Koru vs Zig vs Rust vs Go"
echo "============================================"
echo ""
# Clean up previous builds
rm -f go_baseline zig_baseline rust_baseline koru_output backend backend.zig output_emitted.zig results.json
rm -rf zig-out .zig-cache target Cargo.lock
echo "Building Go baseline (channels)..."
go build -o go_baseline baseline.go
echo "Building Zig baseline (MPMC ring)..."
zig build-exe baseline.zig -O ReleaseFast -femit-bin=zig_baseline
echo "Building Rust baseline (crossbeam channels)..."
cargo build --release --quiet
cp target/release/rust_baseline ./rust_baseline
echo "Building Koru version (MPMC ring + spawned producer)..."
koruc build --release=fast "${KORU_INPUT:-input.kz}"
mv a.out koru_output
echo ""
echo "Running benchmarks with hyperfine..."
echo ""
# Check if hyperfine is installed
if ! command -v hyperfine &> /dev/null; then
echo "ERROR: hyperfine not installed"
echo "Install with: brew install hyperfine (macOS) or cargo install hyperfine"
exit 1
fi
# Run benchmark
# - warmup: 3 runs to stabilize (message passing can vary)
# - runs: 10 (fewer than simple loop since this takes longer)
# - shell=none: avoid shell overhead
hyperfine --warmup 3 --runs 10 --shell=none \
--export-json results.json \
--command-name "Koru (ring flow)" './koru_output' \
--command-name "Zig (MPMC)" './zig_baseline' \
--command-name "Rust (crossbeam)" './rust_baseline' \
--command-name "Go (channels)" './go_baseline'
echo ""
echo "============================================"
echo "Benchmark complete! Results saved to results.json"
echo "============================================"
{
"results": [
{
"command": "Koru (ring flow)",
"mean": 0.14188093350000003,
"stddev": 0.01695179154907399,
"median": 0.144013729,
"user": 0.2720103,
"system": 0.0058107,
"min": 0.11253233300000001,
"max": 0.16333729200000002,
"times": [
0.16333729200000002,
0.13909000000000002,
0.116171167,
0.15239866700000002,
0.154324167,
0.142468,
0.158177959,
0.11253233300000001,
0.145559458,
0.13475029200000002
],
"memory_usage_byte": [
1523712,
1523712,
1523712,
1523712,
1523712,
1523712,
1523712,
1523712,
1523712,
1523712
],
"exit_codes": [
0,
0,
0,
0,
0,
0,
0,
0,
0,
0
]
},
{
"command": "Zig (MPMC)",
"mean": 0.1362536417,
"stddev": 0.011093989509763643,
"median": 0.13332900000000003,
"user": 0.2607015,
"system": 0.0055829,
"min": 0.11835816700000001,
"max": 0.155625875,
"times": [
0.11835816700000001,
0.12912937500000002,
0.155625875,
0.1369805,
0.13339604200000002,
0.13111075,
0.144740417,
0.150400042,
0.133261958,
0.129533291
],
"memory_usage_byte": [
1523712,
1523712,
1523712,
1523712,
1523712,
1523712,
1523712,
1523712,
1523712,
1523712
],
"exit_codes": [
0,
0,
0,
0,
0,
0,
0,
0,
0,
0
]
},
{
"command": "Rust (crossbeam)",
"mean": 0.1492820497,
"stddev": 0.013709233333345136,
"median": 0.149467125,
"user": 0.2872684,
"system": 0.0036785000000000003,
"min": 0.12487187500000001,
"max": 0.17078500000000002,
"times": [
0.15131845800000002,
0.13402091600000002,
0.15511766600000002,
0.17078500000000002,
0.147615792,
0.12487187500000001,
0.145213958,
0.16664720800000002,
0.14412116600000002,
0.153108458
],
"memory_usage_byte": [
1638400,
1638400,
1638400,
1638400,
1638400,
1638400,
1638400,
1638400,
1638400,
1638400
],
"exit_codes": [
0,
0,
0,
0,
0,
0,
0,
0,
0,
0
]
},
{
"command": "Go (channels)",
"mean": 0.44552231249999996,
"stddev": 0.010023165155622273,
"median": 0.447945146,
"user": 0.4569507,
"system": 0.21629179999999998,
"min": 0.42631454100000005,
"max": 0.45510325,
"times": [
0.445299792,
0.4505905,
0.445225792,
0.45510325,
0.453259,
0.45459379200000005,
0.452653083,
0.44092637500000004,
0.431257,
0.42631454100000005
],
"memory_usage_byte": [
4341760,
4407296,
4407296,
4407296,
4407296,
4407296,
4407296,
4407296,
4407296,
4407296
],
"exit_codes": [
0,
0,
0,
0,
0,
0,
0,
0,
0,
0
]
}
]
}
Flows
subflow ~consume-loop click a branch to expand · @labels scroll to their anchor
dequeue (ring)
flow ~create-ring click a branch to expand · @labels scroll to their anchor
create-ring
Test Configuration
THRESHOLD 1.30
Post-validation Script:
#!/bin/bash
# Post-validation: Report performance comparison
#
# Koru is the reference column. Zig, Rust, and Go are measured
# against it — the question is what it costs them to match us.
set -e
if [ ! -f "results.json" ]; then
echo "⚠️ No benchmark results found (results.json missing)"
echo " Running benchmark..."
bash benchmark.sh
fi
if [ ! -f "results.json" ]; then
echo "❌ FAIL: Benchmark did not produce results.json"
exit 1
fi
# Check if jq is installed
if ! command -v jq &> /dev/null; then
echo "⚠️ jq not installed (needed to parse benchmark results)"
echo " Install with: brew install jq (macOS) or apt install jq (Linux)"
echo " Skipping performance validation..."
exit 0
fi
# Parse results (order matches benchmark.sh command-name order)
KORU_TIME=$(jq -r '.results[0].mean' results.json)
ZIG_TIME=$(jq -r '.results[1].mean' results.json)
RUST_TIME=$(jq -r '.results[2].mean' results.json)
GO_TIME=$(jq -r '.results[3].mean' results.json)
# Calculate ratios — Koru is the reference column: every row is
# expressed as <other> / Koru, so >1.0 means slower than Koru.
ZIG_VS_KORU=$(echo "scale=4; $ZIG_TIME / $KORU_TIME" | bc -l)
RUST_VS_KORU=$(echo "scale=4; $RUST_TIME / $KORU_TIME" | bc -l)
GO_VS_KORU=$(echo "scale=4; $GO_TIME / $KORU_TIME" | bc -l)
KORU_VS_ZIG=$(echo "scale=4; $KORU_TIME / $ZIG_TIME" | bc -l)
RUST_VS_ZIG=$(echo "scale=4; $RUST_TIME / $ZIG_TIME" | bc -l)
ZIG_VS_GO=$(echo "scale=4; $ZIG_TIME / $GO_TIME" | bc -l)
echo ""
echo "=========================================="
echo " PERFORMANCE COMPARISON"
echo "=========================================="
echo ""
echo "Koru (ring flow): ${KORU_TIME}s"
echo "Zig (MPMC ring): ${ZIG_TIME}s"
echo "Rust (crossbeam): ${RUST_TIME}s"
echo "Go (channels): ${GO_TIME}s"
echo ""
echo "Ratios (>1.0 = slower than Koru):"
echo " Zig/Koru: ${ZIG_VS_KORU}x"
echo " Rust/Koru: ${RUST_VS_KORU}x"
echo " Go/Koru: ${GO_VS_KORU}x"
echo " Koru/Zig: ${KORU_VS_ZIG}x (regression guard)"
echo " Rust/Zig: ${RUST_VS_ZIG}x"
echo " Zig/Go: ${ZIG_VS_GO}x"
echo ""
# Interpret: Zig vs Koru — parity at equal allocation. The old
# stack-vs-heap asymmetry was normalized 2026-09-30 after it was
# measured as the dominant gap driver (~25%: placement, not codegen).
# The emitted consumer loop carries no union-tag traffic, so a
# deficit here means NEW weight, not the known noise.
echo "Zig vs Koru (parity at equal allocation):"
if (( $(echo "$ZIG_VS_KORU > 1.05" | bc -l) )); then
MARGIN=$(echo "scale=1; ($ZIG_VS_KORU - 1) * 100" | bc -l)
echo " Koru is ${MARGIN}% faster this run (Zig slower)"
elif (( $(echo "$ZIG_VS_KORU < 0.95" | bc -l) )); then
MARGIN=$(echo "scale=1; (1 - $ZIG_VS_KORU) * 100" | bc -l)
echo " Zig is ${MARGIN}% faster this run"
else
echo " Within ±5% — union-tag overhead below this run's noise floor"
fi
echo ""
# Regression guard: Koru must stay within THRESHOLD of Zig at equal
# allocation. THRESHOLD is 1.30 because measured inter-run noise on
# this workload is ~±20% — a tighter bound fires on jitter; 1.30
# still catches real new weight around the identical ring.
THRESHOLD=$(cat THRESHOLD)
echo "Regression guard (Koru/Zig, noise-adjusted):"
if (( $(echo "$KORU_VS_ZIG < $THRESHOLD" | bc -l) )); then
echo " ✅ PASS (${KORU_VS_ZIG}x < ${THRESHOLD}x)"
else
OVERHEAD=$(echo "scale=1; ($KORU_VS_ZIG - 1) * 100" | bc -l)
echo " ❌ PERFORMANCE REGRESSION!"
echo " Koru is ${OVERHEAD}% slower than Zig"
echo " This means abstractions have cost - investigate!"
fi
echo ""
# Interpret: Rust vs Koru
echo "Rust (crossbeam) vs Koru:"
if (( $(echo "$RUST_VS_KORU > 1.05" | bc -l) )); then
MARGIN=$(echo "scale=1; ($RUST_VS_KORU - 1) * 100" | bc -l)
echo " Koru is ${MARGIN}% faster than crossbeam this run"
elif (( $(echo "$RUST_VS_KORU < 0.95" | bc -l) )); then
MARGIN=$(echo "scale=1; (1 - $RUST_VS_KORU) * 100" | bc -l)
echo " Crossbeam is ${MARGIN}% faster than Koru this run"
else
echo " Roughly equal (within 5%)"
fi
echo ""
# Interpret: Go vs Koru
echo "Go (channels) vs Koru:"
if (( $(echo "$GO_VS_KORU > 1.05" | bc -l) )); then
MARGIN=$(echo "scale=1; ($GO_VS_KORU - 1) * 100" | bc -l)
echo " Koru is ${MARGIN}% faster than Go channels this run"
elif (( $(echo "$GO_VS_KORU < 0.95" | bc -l) )); then
MARGIN=$(echo "scale=1; (1 - $GO_VS_KORU) * 100" | bc -l)
echo " Go is ${MARGIN}% faster than Koru this run"
else
echo " Roughly equal (within 5%)"
fi
echo ""
# Interpret: Rust vs Zig (context row — the two foreign systems langs)
echo "Rust vs Zig (context):"
if (( $(echo "$RUST_VS_ZIG < 0.95" | bc -l) )); then
IMPROVEMENT=$(echo "scale=1; (1 - $RUST_VS_ZIG) * 100" | bc -l)
echo " Rust is ${IMPROVEMENT}% faster than Zig"
elif (( $(echo "$RUST_VS_ZIG > 1.05" | bc -l) )); then
SLOWDOWN=$(echo "scale=1; ($RUST_VS_ZIG - 1) * 100" | bc -l)
echo " Zig is ${SLOWDOWN}% faster than Rust"
else
echo " Roughly equal (within 5%)"
fi
echo ""
echo ""
echo "=========================================="
exit 0