Skip to main content

Crate lanebag

Crate lanebag 

Source
Expand description

Lock-free MPSC bag channel. Each producer thread writes to its own SPSC ring (its lane); the single consumer scans and drains all lanes. Lanes are created on first use and cleaned up when producer threads go away, so the producer set can change freely at runtime.

Items from one producer thread arrive in FIFO order. There is no ordering between producers, which is why this is a bag and not a queue. That is enough for fan-in work like metrics collection, buffer recycling, deferred destruction, or completion events.

Once a thread’s lane exists, its enqueues touch no state shared with other producers (creating the lane does: registration goes through one shared atomic stack, once per thread). The trade-offs are on the other side: the consumer’s scan cost grows with the number of live lanes, and buffered memory is lanes * capacity_per_lane * size_of::<T>().

§Example

use lanebag::mpsc::channel;

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

let handles: Vec<_> = (0..4)
    .map(|t| {
        let p = producer.clone();
        std::thread::spawn(move || {
            for i in 0..1000 {
                while p.enqueue(t * 1000 + i).is_err() {
                    std::hint::spin_loop();
                }
            }
        })
    })
    .collect();
drop(producer);

let mut received = 0;
while received < 4000 {
    received += consumer.consume_all(|item| {
        let _ = item;
    });
}
for h in handles {
    h.join().unwrap();
}

§Limitations

  • No cross-producer ordering.
  • The consumer polls and never parks. No select!, no async. If you need global FIFO or blocking receive, use std::sync::mpsc, crossbeam-channel or flume instead.
  • The slice/batch operations need T: Copy because they skip destructors; other types go through enqueue_iter and consume_all.
  • Enqueueing from a thread_local! destructor panics; that is the one panic reachable in normal use. See TLS teardown.

§Bounds

mpsc::channel::<T>() has no bounds on T. Handles are Send iff T: Send; Sync and 'static are never required, so borrowed items work under std::thread::scope, and a !Send type gives a channel confined to one thread:

ⓘ
use std::rc::Rc;
let (_, producer) = lanebag::mpsc::channel::<Rc<u8>>(8);
std::thread::spawn(move || producer.enqueue(Rc::new(1))); // Rc is !Send

Modules§

mpsc
Multiple-producer single-consumer lock-free bag.