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§
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.