Struct Queue 

pub struct Queue<E: Context, V: CodecShared> { /* private fields */ }

A durable, at-least-once delivery queue with per-item acknowledgment.

Items are durably stored in a journal and survive crashes. Queue::init returns the queue, which writes items, and its Reader, which delivers them. The reader must acknowledge each item individually after processing. Items can be acknowledged out of order, enabling parallel processing.

Operations

• append / commit: Write items to the journal, then persist them and publish them to the reader. Appended items are lost on restart if not committed.
• enqueue: Append + commit in one step. The item is durable before return.
• sync: Commit, then prune completed sections below the reader’s ack floor.
• Reader::recv / Reader::try_recv: Return the next unacked committed item in FIFO order.
• Reader::ack / Reader::ack_up_to: Mark items as processed (in-memory only).

Acknowledgment

Acks are tracked in-memory with an ack_floor (all positions below are acked) plus an RMap of acked positions above the floor. When items are acked contiguously from the floor, the floor advances automatically.

Acks are not persisted. The durable equivalent is the journal’s pruning boundary, advanced by sync. On restart, all non-pruned items are re-delivered regardless of prior ack state.

Crash Recovery

On restart, ack_floor is set to the journal’s pruning boundary. Items that were pruned are gone. Everything else is re-delivered. Applications must handle duplicates (idempotent processing).

Storage-mutating functions consume the queue and return it only on success: an error (or a dropped future) destroys the handle. The reader then delivers every published item and returns None.

Implementations

impl<E: Context, V: CodecShared> Queue<E, V>

pub async fn init( context: E, cfg: Config<V::Cfg>, ) -> Result<(Self, Reader<E, V>), Error>

Initialize a queue from storage, returning it with its Reader.

On first initialization, creates an empty queue. On restart, the reader begins from the journal’s pruning boundary (providing at-least-once delivery for all non-pruned items). Both handles must be dropped before the queue is reopened.

Errors

Returns an error if the underlying journal cannot be initialized.

pub async fn enqueue(self, item: &V) -> Result<(Self, u64), Error>

Append and commit an item, returning its position. The reader can receive the item once this returns.

Errors

Returns an error if the underlying storage operation fails.

pub async fn enqueue_bulk( self, items: impl IntoIterator<Item = impl Borrow<V>>, ) -> Result<(Self, Range<u64>), Error>

Append a batch of items with a single commit, returning positions [start, end). The reader can receive the items once this returns.

Errors

Returns an error if any append or the final commit fails.

pub async fn append(self, item: &V) -> Result<(Self, u64), Error>

Append an item without committing, returning its position. The reader can receive the item after the next Self::commit or Self::sync.

Errors

Returns an error if the underlying storage operation fails.

pub async fn commit(self) -> Result<Self, Error>

Durably persist appended items and publish them to the reader.

This does not persist acknowledgements. For a stronger guarantee that eliminates potential recovery and prunes acknowledged items, use Self::sync instead.

pub async fn sync(self) -> Result<Self, Error>

Durably persist the queue, guaranteeing the current state will survive a crash, and that no recovery will be needed on startup.

This also prunes items below the reader’s ack floor and publishes the result to the reader.

pub fn size(&self) -> u64

Returns the total number of items that have been appended.

pub async fn destroy(self) -> Result<(), Error>

Destroy the queue, removing all data from disk.

Trait Implementations

impl<E: Context, V: CodecShared> Debug for Queue<E, V>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.