persistent_queue/lib.rs
1//! A durable, at-least-once MPSC queue backed by in-memory and durable backends.
2//!
3//! Items are written to a [`Store`] and survive process and machine crashes.
4//! Delivery is at-least-once: an item is removed only once the consumer acks it,
5//! so a crash between handling and ack redelivers it. The core is synchronous and
6//! runtime-agnostic.
7//!
8//! ```
9//! use persistent_queue::{Builder, MemStore};
10//!
11//! let (tx, rx) = Builder::new(MemStore::new()).capacity(1024).open().unwrap();
12//! tx.push(b"job").unwrap();
13//! let item = rx.reserve().unwrap().unwrap();
14//! assert_eq!(&*item, b"job");
15//! item.ack().unwrap();
16//! ```
17//!
18//! For typed messages, [`Builder::open_typed`] wraps the queue with a [`Codec`] that
19//! encodes on push and decodes on reserve (serde and bincode behind the `serde`
20//! feature). With the `tokio` feature, [`Builder::open_async`] gives async
21//! producer/consumer handles that run store I/O on tokio's blocking pool and wait
22//! (for capacity, or the next item) asynchronously.
23//!
24//! See `DESIGN.md` for the on-disk layout, crash recovery, and durability model.
25#![warn(missing_docs)]
26
27#[cfg(feature = "rkyv")]
28mod archived;
29#[cfg(feature = "tokio")]
30mod async_queue;
31mod codec;
32mod error;
33mod queue;
34mod store;
35mod sync;
36mod typed;
37
38pub use codec::{Codec, CodecError};
39pub use error::{OpenError, PushError, TryPushError};
40pub use queue::{Builder, Consumer, Durability, Ends, Producer, Reserved};
41pub use store::{KeyValue, MemStore, Op, Store};
42pub use typed::{
43 ReserveError, TypedConsumer, TypedEnds, TypedProducer, TypedPushError, TypedReserved,
44};
45
46#[cfg(feature = "rkyv")]
47pub use archived::{
48 Archivable, ArchivedConsumer, ArchivedEnds, ArchivedProducer, ArchivedReserved,
49};
50#[cfg(feature = "tokio")]
51pub use async_queue::{AsyncConsumer, AsyncEnds, AsyncProducer, AsyncReserved};
52#[cfg(feature = "serde")]
53pub use codec::Bincode;
54#[cfg(feature = "rkyv")]
55pub use codec::Rkyv;
56
57#[cfg(feature = "redb")]
58pub use store::RedbStore;
59#[cfg(feature = "rocksdb")]
60pub use store::RocksStore;
61#[cfg(feature = "sled")]
62pub use store::SledStore;