lanebag 0.1.4

Lock-free MPSC bag channel where each producer thread gets its own SPSC lane
Documentation

lanebag

crates.io docs.rs license

Lock-free MPSC bag channel for fan-in workloads. Every producer thread gets its own SPSC ring buffer (a lane), so producers never synchronize with each other. The consumer drains all lanes in one call. There are no mutexes, including in the dynamic parts (lane registration, retirement, reclamation).

Thread 0 / any Producer handle ──► [lane 0] ──┐
Thread 1 / any Producer handle ──► [lane 1] ──┤──► Consumer::consume_all
Thread 2 / any Producer handle ──► [lane 2] ──┘

Why

Shared-state multi-producer queues get slower as you add producers, since every enqueue fights over the same cache line. In the benchmarks below all of them peak somewhere between 1 and 4 producers. lanebag avoids the problem by not sharing anything on the enqueue path: an enqueue costs about 3 ns and that doesn't change with more producers.

The catch is ordering. Items from a single producer come out in FIFO order, but there is no order between producers, hence "bag" rather than queue. Plenty of fan-in workloads don't care: metrics collection, buffer recycling, deferred destruction, completion events.

Producers can come and go. Lanes are created on first use, retired when a producer thread exits (pending items are still delivered), resurrected if the thread comes back, and thread ids get recycled so memory depends on peak thread count, not on how many threads ever existed.

Example

use lanebag::mpsc::channel;

let (mut consumer, producer) = channel::<u64>(1024);

let workers: Vec<_> = (0..4)
    .map(|id| {
        let p = producer.clone();
        std::thread::spawn(move || {
            for seq in 0..10_000u64 {
                // full lane: the item comes back as Err(item)
                while p.enqueue(id * 10_000 + seq).is_err() {
                    std::hint::spin_loop();
                }
            }
        })
    })
    .collect();
drop(producer);

let mut received = 0;
while received < 40_000 {
    received += consumer.consume_all(|item| {
        let _ = item;
    });
}
for w in workers {
    w.join().unwrap();
}

API

Producer Behaviour
enqueue(item) Push one item. A full lane returns Err(item) so you keep ownership.
enqueue_batch(&[T]) T: Copy. Push as many as fit, returns the count written.
enqueue_all(&[T]) T: Copy. All-or-nothing batch push.
enqueue_iter(iter) Any T. By-value batch push until full, leftovers stay in the iterator.
Consumer Behaviour
consume_all(f) Drain every lane, calling f per item. Returns the count.
consume_all_slices(f) T: Copy. Drain via contiguous &[T] callbacks.
consume_up_to_slices(n, f) T: Copy. Slice drain capped at n items.
dequeue() Pop one item from the first non-empty lane.
is_empty() / published_lanes() Introspection.

Benchmarks

Fan-in throughput in million items/s. 400k u64 items spread over N producers, one consumer. Criterion medians on a Ryzen AI 9 HX 370; every contender is driven the same way (producers spin on full, consumer busy-polls, bounded queues get the same aggregate capacity). cargo bench reproduces this.

queue 1p 2p 4p 8p 16p
lanebag 41.6 139.6 542.6 500.2 394.4
lanebag, batch 32 577.1 892.8 1096.1 1143.2 689.7
crossbeam (bounded) 19.8 22.9 23.1 3.3 2.7
crossbeam (unbounded) 18.0 19.7 17.8 12.5 4.0
ArrayQueue 21.1 29.0 19.8 3.3 2.9
SegQueue 16.4 18.7 17.7 11.4 3.2
std::sync::mpsc 17.3 6.3 5.1 6.0 5.4
flume (bounded) 3.7 3.2 0.9 0.5 0.3

At 8 producers that's about 40x the best shared queue in this table, and the batch API goes past 1G items/s. Single-threaded with no contention the per-item cost is around 3.3 ns (2.5 via slices) against 20-49 ns for the rest. Usual caveats: one machine, and busy-spinning is close to a worst case for flume, which wants to park.

Notes

  • Exactly-once delivery, per-producer FIFO, everything lock-free.
  • channel::<T>() has no bounds on T. Handles are Send iff T: Send (with an Rc you just get a single-thread channel), Sync and 'static are never needed, so borrowed items work under std::thread::scope.
  • The slice/batch calls want T: Copy because they skip destructors. For other types use enqueue_iter and consume_all.
  • Memory is per lane: live_lanes * capacity_per_lane * size_of::<T>().
  • The consumer polls and never parks. No select!, no async. If you need global FIFO or blocking receive, crossbeam-channel or flume are better choices.
  • Don't enqueue from thread_local! destructors. It panics (the internal thread-id guard may already be gone). This is the only panic you can hit in normal use; details in the Producer docs under "TLS teardown".

Testing

Unit and integration tests, quickcheck properties, stress tests for producer churn, handle migration and thread-id recycling. The whole suite runs under Miri (cargo miri test). See examples/ for runnable examples.

MSRV is Rust 1.85 (edition 2024); bumping it counts as a minor version.

License

Apache-2.0 or MIT, at your option. Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above.