bchan

A high-performance, lock-free multi-producer single-consumer (MPSC) channel implementation in Zig, designed for low-latency concurrent messaging.

Features

• Lock-free MPSC: Per-producer tail pointers eliminate contention
• Zero-copy batch API: Reserve/commit for efficient bulk operations
• Futex-based blocking: Energy-efficient waiting with exponential backoff
• Dynamic producers: Safe registration and retirement with termination guarantees
• SPSC/SPMC support: Unified API for different producer/consumer patterns
• Production-ready: Comprehensive tests and benchmarks

Installation

Add to your build.zig.zon:

.{
    .name = "your-project",
    .version = "0.1.0",
    .dependencies = .{
        .bchan = .{
            .url = "https://github.com/boonzy00/bchan/archive/refs/tags/v0.2.0.tar.gz",
            .hash = "1220xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", // Run `zig fetch --save <url>` to get the actual hash
        },
    },
}

Then in build.zig:

const bchan = b.addModule("bchan", .{
    .source_file = .{ .path = "deps/bchan/src/lib.zig" },
});

Usage

Basic MPSC Channel

const std = @import("std");
const bchan = @import("bchan");

pub fn main() !void {
    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
    defer _ = gpa.deinit();
    const allocator = gpa.allocator();

    // Create MPSC channel with 4 max producers
    const ch = try bchan.Channel(u64).init(allocator, 1024, .MPSC, 4);
    defer ch.deinit();

    // Register a producer
    const producer = try ch.registerProducer();
    defer ch.unregisterProducer(producer);

    // Send messages
    try std.testing.expect(producer.trySend(42));
    try std.testing.expect(producer.trySend(1337));

    // Receive messages
    const val1 = ch.tryReceive();
    const val2 = ch.tryReceive();

    std.debug.print("Received: {} {}\n", .{val1.?, val2.?});
}

Batch Operations

// Reserve space for batch
var ptrs: [64]?*u64 = undefined;
const reserved = producer.reserveBatch(&ptrs);
if (reserved > 0) {
    // Fill the batch
    for (0..reserved) |i| {
        if (ptrs[i]) |ptr| {
            ptr.* = i;
        }
    }
    // Commit atomically
    producer.commitBatch(reserved);
}

// Receive batch
var buf: [64]u64 = undefined;
const received = ch.tryReceiveBatch(&buf);

Blocking Operations

// Blocking send
producer.send(42);

// Blocking receive
const val = ch.receive();

Examples

See examples/simple.zig for a basic usage example, and benches/ for complete benchmark examples.

• benches/batch.zig - High-throughput MPSC with batching
• benches/spsc.zig - SPSC performance test
• benches/mpsc_vyukov.zig - Vyukov MPMC comparison

Benchmarks

Run benchmarks with:

# Build optimized binaries
zig build -Doptimize=ReleaseFast

# Run MPSC benchmark 5 times with stats
./scripts/run_bench_mpsc.sh

# Run Vyukov comparison
./scripts/run_vyukov.sh

Benchmarks (AMD Ryzen 7 5700G • Zig 0.15.0 • ReleaseFast)

Scenario	Producers	Throughput	Notes
MPSC (batched, zero-copy)	16	968 M msg/s	Mean of 5 runs
MPSC (batched, zero-copy)	4	798 M msg/s	Mean of 5 runs
SPSC (batched, zero-copy)	1	150 M msg/s	Mean of 7 runs, σ ≈ 10 M msg/s, governor-locked
SPSC (single-message)	1	8–15 M msg/s	For comparison
Vyukov MPMC (4p4c)	4	19 M msg/s	Reference implementation

Performance Comparison

bchan MPSC (16p, batched)      ██████████████████████████████ 968 M/s
bchan SPSC (batched, 1p1c)     ████████████████████ 150 M/s
bchan SPSC (single-msg)        ███████ 8–15 M/s
Vyukov MPMC                    ██ 19 M/s

All figures measured with CPU governor locked to performance and cores 0/1 isolated via cset shield. Reproducibility note: Batched SPSC throughput measured via scripts/run_peak_locked.sh (batch=64, 35 s duration, 7 repetitions). Individual run values ranged from 128–156 M msg/s; mean 150 M msg/s, σ ≈ 10 M msg/s. See scripts/run_peak_locked.sh (SPSC) and scripts/run_scaling_locked.sh (batch sweep) for one-click reproducible commands.

API Reference

Channel Creation

pub fn init(allocator: std.mem.Allocator, capacity: u64, mode: Mode, max_producers: u32) !Channel(T)
pub fn deinit(self: *Channel(T)) void

Producer Registration

pub fn registerProducer(self: *Channel(T)) !ProducerHandle
pub fn unregisterProducer(self: *Channel(T), handle: ProducerHandle) void

Send Operations

pub fn trySend(self: ProducerHandle, item: T) bool
pub fn send(self: ProducerHandle, item: T) void
pub fn trySendBatch(self: ProducerHandle, items: []const T) usize
pub fn sendBatch(self: ProducerHandle, items: []const T) usize

Batch Reserve/Commit

pub fn reserveBatch(self: ProducerHandle, ptrs: []?*T) usize
pub fn commitBatch(self: ProducerHandle, count: usize) void

Receive Operations

pub fn tryReceive(self: *Channel(T)) ?T
pub fn receive(self: *Channel(T)) T
pub fn tryReceiveBatch(self: *Channel(T), buffer: []T) usize
pub fn receiveBatch(self: *Channel(T), buffer: []T) usize

See bchan_algorithm.md for detailed algorithm documentation.

Documentation

• API Reference: Complete API documentation with examples
• Performance Guide: Optimization techniques and benchmarking
• Development Guide: Contributing and development workflows
• Algorithm Details: Technical implementation details

Testing

Run the full test suite:

zig build test

Includes correctness tests for all modes, edge cases, and concurrent scenarios.

Contributing

Contributions welcome! Please see CONTRIBUTING.md for guidelines.

License

MIT License - see LICENSE file.

Changelog

See CHANGELOG.md for version history.

Related Projects

• crossbeam-channel - Rust channels
• moodycamel::ConcurrentQueue - C++ lock-free queues
• zig-gamedev - Zig game development ecosystem
• Experiment with backoff strategies, padding/alignment, and futex thresholds to tune performance.
• Add CI jobs to run tests and (optionally) quick benches on supported runners. Add CI jobs to run tests and (optionally) quick benches on supported runners.