Crate persistent_queue 

A durable, at-least-once MPSC queue backed by in-memory and durable backends.

Items are written to a Store and survive process and machine crashes. Delivery is at-least-once: an item is removed only once the consumer acks it, so a crash between handling and ack redelivers it. The core is synchronous and runtime-agnostic.

use persistent_queue::{Builder, MemStore};

let (tx, rx) = Builder::new(MemStore::new()).capacity(1024).open().unwrap();
tx.push(b"job").unwrap();
let item = rx.reserve().unwrap().unwrap();
assert_eq!(&*item, b"job");
item.ack().unwrap();

For typed messages, Builder::open_typed wraps the queue with a Codec that encodes on push and decodes on reserve (serde and bincode behind the serde feature). With the tokio feature, [Builder::open_async] gives async producer/consumer handles that run store I/O on tokio’s blocking pool and wait (for capacity, or the next item) asynchronously.

See DESIGN.md for the on-disk layout, crash recovery, and durability model.

Structs

Builder

Builds a queue over a Store.

CodecError

An encode or decode failure, carrying the underlying codec’s message.

Consumer

The consumer half. Single consumer, so it does not implement Clone.

MemStore

In-memory Store backed by a BTreeMap. Not persistent; durable is a no-op. Useful as the default, for tests, and as a benchmark baseline.

Producer

The producer half. Clone it for multiple producers.

Reserved

A reserved (in-flight) item. Derefs to its bytes; ack removes it, nack or drop returns it for redelivery.

TypedConsumer

The consumer half of a typed queue. Single consumer.

TypedProducer

The producer half of a typed queue. Clone it for multiple producers.

TypedReserved

A reserved, decoded item. Derefs to the value; ack removes it while nack or drop returns it for redelivery.

Enums

Durability

How writes are made durable.

Op

A single write in a Store::commit batch.

OpenError

Error from opening a queue over a store.

PushError

Error from a blocking Producer::push.

ReserveError

Error from TypedConsumer::reserve.

TryPushError

Error from Producer::try_push.

TypedPushError

Error from TypedProducer::push.

Traits

Codec

Encodes a message type to bytes for the store and decodes it back.

Store

An ordered key/value byte store: the durable substrate under the queue.

Type Aliases

Ends

The producer and consumer ends returned by Builder::open.

KeyValue

A key/value pair returned by a store seek.

TypedEnds

The producer/consumer pair returned by Builder::open_typed.