Expand description
A lock-free single-producer single-consumer (SPSC) ring buffer tuned for single-message latency.
§Design
A slot-sequence queue in the FastForward/Vyukov family, with the consumer’s slot write-back replaced by lazy flow control.
- No shared head/tail atomics on the hot path. Producer and consumer
each keep a plain (non-atomic, register-resident)
u64position counter. Publication happens through a per-slot flag in the same cache line as the payload, so a handoff costs one cache-line transfer. Cached-index Lamport queues need two serialized transfers per message, one for the index and one for the data. - The consumer never writes the slot line. A pop publishes the
consumer’s position to a cache-padded
progresscounter on a consumer-owned line; the producer spends a cached credit (limit = progress + N) and reloads it at most once per lap. The hot slot line moves in one direction only, producer to consumer. - Publication protocol. For position
pand slotp & (N - 1), the producer storesseq = p + 1after the payload; the consumer reads whenseq == p + 1. Flags from earlier laps differ by a multiple ofN, and only equality is used, sou64wraparound is safe whileNis a power of two (enforced at compile time). - Memory ordering.
Acquireon availability checks,Releaseon publication; both compile to plainmovon x86-64. Position arithmetic is local and non-atomic.
§Latency
A cross-core handoff is bounded by the coherency protocol moving one modified line between cores, roughly 20 to 100 ns one-way on current x86. Sub-nanosecond figures describe the amortized cost of an inlined push and pop pair on one core, not a cross-core message. This design minimizes what software controls: one line transfer per handoff, no shared-index traffic on top.
§Example
let (mut tx, mut rx) = takoude::spsc_channel::<u64, 8>();
std::thread::spawn(move || {
for i in 0..100 {
tx.push(i);
}
});
for i in 0..100 {
assert_eq!(rx.pop(), i);
}§Cargo features
All features are off by default; the default paths are safe and portable.
packed: single-atomic publication forAtomicValuepayloads up to 4 bytes. Fully sound and portable. Usespsc_packed_channelto get endpoints whose encoding cannot be mixed with scalar operations.readahead: the consumer prefetches the slot 32 positions ahead on each pop. Raises sustained throughput on hosts with slow cross-core interconnects; benchmark on the target before enabling.
Structs§
- Consumer
- Receiving half of the channel.
- Full
- Error returned by
Producer::try_pushwhen the ring is full; gives the value back to the caller. - Packed
Consumer packed - Receiving half of a channel created by
spsc_packed_channel. - Packed
Producer packed - Sending half of a channel created by
spsc_packed_channel. - Producer
- Sending half of the channel.
!Clone; owned by exactly one thread at a time (methods take&mut self).
Traits§
- Atomic
Value packed - A value whose initialized representation can be transported through an integer atomic without losing validity or pointer provenance.
Functions§
- spsc_
channel - Creates a bounded SPSC channel with
Nslots (Nmust be a power of two and at least 2; enforced at compile time). - spsc_
packed_ channel packed - Creates a bounded SPSC channel using the
packedsingle-atomic encoding.