lanebag
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 channel;
let = ;
let workers: =
.map
.collect;
drop;
let mut received = 0;
while received < 40_000
for w in workers
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 onT. Handles areSendiffT: Send(with anRcyou just get a single-thread channel),Syncand'staticare never needed, so borrowed items work understd::thread::scope.- The slice/batch calls want
T: Copybecause they skip destructors. For other types useenqueue_iterandconsume_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 theProducerdocs 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.