Skip to main content

Crate outcry

Crate outcry 

Source
Expand description

One writer, many readers, shared memory, nobody waits.

outcry is a broadcast queue: a single producer appends variable-length frames and any number of consumers each read every frame, in order, in their own time. Readers never slow the writer down. A reader that falls more than a full queue behind is overrun — it is told so, and it can resync to the head — but the writer never knew it was there. The name is from open outcry: one voice on the floor, everyone hears it, nobody repeats it for you.

It is an implementation in Rust of the FastQueue design David Gross presented in When Nanoseconds Matter: Ultrafast Trading Systems in C++ (CppCon 2024), including its three cache-line optimisations, with one deliberate difference: the reader’s copy is sound rather than a data race caught after the fact. See copy for why that costs nothing here.

§Example

use outcry::Queue;

let queue = Queue::anon(1 << 20)?;          // 1 MiB, this process only
let mut producer = queue.producer()?;
let mut consumer = queue.consumer();

producer.write(b"hello, floor")?;

let mut buf = [0u8; 64];
let n = consumer.try_read(&mut buf)?.expect("one frame is waiting");
assert_eq!(&buf[..n], b"hello, floor");
assert_eq!(consumer.try_read(&mut buf)?, None);

Across processes, the producer calls Queue::create with a path (under /dev/shm on Linux) and consumers call Queue::open on the same path. When the producer restarts and calls create again, existing consumers are left attached to the old queue, which goes silent rather than failing: see Queue::instance for how a consumer tells that apart from an idle producer, and examples/readme_reader.rs for a reader that does.

§What it is not

Not for multiple writers, not a work queue (every reader gets every frame), not durable, not cross-host. If you need any of those, this is the wrong tool and the README says which is the right one.

Re-exports§

pub use consumer::Consumer;
pub use error::Error;
pub use error::Result;
pub use producer::Producer;

Modules§

consumer
A reader. Any number may exist; each sees every frame.
copy
Moving bytes into and out of the ring.
error
Error type.
layout
On-disk (on-page) layout.
producer
The single writer.

Structs§

Queue
A handle to a queue. Clone it freely; make producers and consumers from it.