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`]
19//! (`serde` + `bincode`, or `rkyv`, behind their features), and
20//! [`Builder::open_archived`] (rkyv) reads an item as `&Archived<T>` without decoding
21//! it. With the `tokio` feature, [`Builder::open_async`] gives async producer/consumer
22//! handles that run store I/O on tokio's blocking pool and wait (for capacity, or the
23//! next item) asynchronously.
24//!
25//! See `DESIGN.md` for the on-disk layout, crash recovery, and durability model.
26#![warn(missing_docs)]
27
28#[cfg(feature = "rkyv")]
29mod archived;
30#[cfg(feature = "tokio")]
31mod async_queue;
32mod codec;
33mod error;
34mod queue;
35mod store;
36mod sync;
37mod typed;
38
39pub use codec::{Codec, CodecError};
40pub use error::{OpenError, PushError, TryPushError};
41pub use queue::{Builder, Consumer, Durability, Ends, Producer, Reserved};
42pub use store::{KeyValue, MemStore, Op, Store};
43pub use typed::{
44 ReserveError, TypedConsumer, TypedEnds, TypedProducer, TypedPushError, TypedReserved,
45};
46
47#[cfg(feature = "rkyv")]
48pub use archived::{
49 Archivable, ArchivedConsumer, ArchivedEnds, ArchivedProducer, ArchivedReserved,
50};
51#[cfg(feature = "tokio")]
52pub use async_queue::{AsyncConsumer, AsyncEnds, AsyncProducer, AsyncReserved};
53#[cfg(feature = "serde")]
54pub use codec::Bincode;
55#[cfg(feature = "rkyv")]
56pub use codec::Rkyv;
57
58#[cfg(feature = "redb")]
59pub use store::RedbStore;
60#[cfg(feature = "rocksdb")]
61pub use store::RocksStore;
62#[cfg(feature = "sled")]
63pub use store::SledStore;