Skip to main content

Crate takoude

Crate takoude 

Source
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) u64 position 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 progress counter 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 p and slot p & (N - 1), the producer stores seq = p + 1 after the payload; the consumer reads when seq == p + 1. Flags from earlier laps differ by a multiple of N, and only equality is used, so u64 wraparound is safe while N is a power of two (enforced at compile time).
  • Memory ordering. Acquire on availability checks, Release on publication; both compile to plain mov on 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 for AtomicValue payloads up to 4 bytes. Fully sound and portable. Use spsc_packed_channel to 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_push when the ring is full; gives the value back to the caller.
PackedConsumerpacked
Receiving half of a channel created by spsc_packed_channel.
PackedProducerpacked
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§

AtomicValuepacked
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 N slots (N must be a power of two and at least 2; enforced at compile time).
spsc_packed_channelpacked
Creates a bounded SPSC channel using the packed single-atomic encoding.