outcry 0.2.2

Single-writer, many-reader broadcast queue over shared memory: variable-length frames, readers never block the writer, a lagging reader is overrun and told so
Documentation
//! 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++*][talk] (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.
//!
//! [talk]: https://www.youtube.com/watch?v=sX2nF1fW7kI
//!
//! # 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);
//! # Ok::<(), outcry::Error>(())
//! ```
//!
//! 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.

#![warn(missing_docs)]
#![deny(rustdoc::broken_intra_doc_links)]
#![deny(unsafe_op_in_unsafe_fn)]

pub mod consumer;
pub mod copy;
pub mod error;
pub mod layout;
mod mapping;
pub mod producer;

use std::path::Path;
use std::sync::atomic::{AtomicBool, Ordering};
use std::sync::Arc;

pub use consumer::Consumer;
pub use error::{Error, Result};
pub use producer::Producer;

/// A handle to a queue. Clone it freely; make producers and consumers from it.
#[derive(Clone)]
pub struct Queue {
    map: Arc<mapping::Mapping>,
    producer_taken: Arc<AtomicBool>,
}

impl Queue {
    /// Create a queue in a file at `path`, replacing any existing file.
    ///
    /// Put it in shared memory — `/dev/shm/<name>` on Linux — so the mapping never
    /// touches disk. `capacity` is the ring size in bytes; a power of two, at least
    /// [`layout::MIN_CAPACITY`].
    ///
    /// **Replacing, not truncating.** The new queue is built beside the target and renamed
    /// into place, so it has a new inode. Readers already attached to the old queue are
    /// not killed and not corrupted; they keep an intact mapping of a file that will never
    /// change again, and from inside it a replaced writer is indistinguishable from an
    /// idle one — [`Consumer::try_read`] simply returns `Ok(None)` forever. A reader that
    /// must survive a writer restart compares [`Queue::instance`] with the value currently
    /// at the path and re-opens when they differ. The crate does not do that for you.
    pub fn create(path: impl AsRef<Path>, capacity: u64) -> Result<Self> {
        Ok(Self::wrap(mapping::Mapping::create(
            path.as_ref(),
            capacity,
        )?))
    }

    /// Attach to a queue another process created at `path`.
    ///
    /// Fails if the file is not an `outcry` queue of this layout version.
    pub fn open(path: impl AsRef<Path>) -> Result<Self> {
        Ok(Self::wrap(mapping::Mapping::open(path.as_ref())?))
    }

    /// A queue in anonymous memory, visible only inside this process.
    pub fn anon(capacity: u64) -> Result<Self> {
        Ok(Self::wrap(mapping::Mapping::anon(capacity)?))
    }

    fn wrap(map: mapping::Mapping) -> Self {
        Self {
            map: Arc::new(map),
            producer_taken: Arc::new(AtomicBool::new(false)),
        }
    }

    /// Ring size in bytes.
    pub fn capacity(&self) -> u64 {
        self.map.capacity()
    }

    /// Identifier assigned when this queue was created.
    ///
    /// [`Queue::create`] replaces the file at a path atomically rather than truncating
    /// it, so a reader that was attached across a writer restart keeps a valid mapping of
    /// the *previous* queue — one that is intact and will never change again. From inside
    /// that mapping, a replaced writer and a merely quiet one look identical. Comparing
    /// this value with the one currently at the path tells them apart:
    ///
    /// ```no_run
    /// # use outcry::Queue;
    /// # fn check(mine: &Queue, path: &str) -> Result<(), outcry::Error> {
    /// if Queue::open(path)?.instance() != mine.instance() {
    ///     // The writer restarted. Re-open and make a new consumer; anything the
    ///     // replacement queue published before now is already gone.
    /// }
    /// # Ok(())
    /// # }
    /// ```
    ///
    /// Nanoseconds since the epoch at the moment of creation, so it is also readable as a
    /// timestamp. [`Queue::anon`] assigns one too, though nothing can observe it from
    /// another handle.
    pub fn instance(&self) -> u64 {
        self.map.instance()
    }

    /// The producer. At most one per queue.
    ///
    /// Two writers on one queue corrupt it, and the corruption is silent: both advance
    /// `published`, their frames interleave, and a reader returns bytes that satisfy every
    /// check it makes and were never written as one frame. So the claim is enforced twice.
    ///
    /// Within this handle and its clones, by a flag. Across handles and across processes,
    /// by an exclusive advisory lock on the queue file — two [`Queue::open`] calls on one
    /// file see each other, whether or not they are in the same process. The kernel
    /// releases that lock when the holding process dies, so a writer that crashed leaves
    /// nothing to clean up.
    ///
    /// Dropping the returned [`Producer`] releases both, and a later call succeeds.
    ///
    /// The lock belongs to the queue rather than to the path. A writer that restarts by
    /// calling [`Queue::create`] builds a *new* queue and takes that one's claim, without
    /// contending with a writer still feeding the old one; the two are separate queues and
    /// nothing interleaves. A writer that restarts by calling [`Queue::open`] resumes the
    /// same queue, and there the lock is what guarantees its predecessor is gone.
    ///
    /// [`Queue::anon`] has no file, so only the flag applies — which is sufficient, since
    /// nothing outside this process can reach an anonymous mapping.
    pub fn producer(&self) -> Result<Producer> {
        if self.producer_taken.swap(true, Ordering::AcqRel) {
            return Err(Error::Io(std::io::Error::new(
                std::io::ErrorKind::AlreadyExists,
                "this queue already has a producer",
            )));
        }
        if !self.map.claim_producer() {
            // Someone else holds the queue. Give the flag back, or this handle could never
            // produce again even once they are gone.
            self.producer_taken.store(false, Ordering::Release);
            return Err(Error::Io(std::io::Error::new(
                std::io::ErrorKind::AlreadyExists,
                "another handle or process is already the producer for this queue",
            )));
        }
        Ok(Producer::new(
            Arc::clone(&self.map),
            Arc::clone(&self.producer_taken),
        ))
    }

    /// A new consumer, starting at the current head of the stream.
    pub fn consumer(&self) -> Consumer {
        Consumer::new(Arc::clone(&self.map))
    }
}