Struct DurableEventQueue 

pub struct DurableEventQueue<T> { /* private fields */ }

RocksDB-backed event queue with at-least-once delivery.

Implementations

impl<T> DurableEventQueue<T>

where T: BorshSerialize + BorshDeserialize + Clone,

pub fn open<P: AsRef<Path>>(path: P) -> Result<Self, DurableEventQueueError>

Opens a RocksDB database dedicated to this durable queue.

The database must not be shared with unrelated data. Recovery scans all keys in this DB and treats them as durable queue entries.

pub fn open_with_options<P: AsRef<Path>>( path: P, options: DurableEventQueueOptions, ) -> Result<Self, DurableEventQueueError>

Opens a durable queue with explicit options.

pub fn push(&self, event: T) -> Result<DurableEvent<T>, DurableEventQueueError>

Durably stores event and enqueues it for consumption.

Partial-failure note

The DB write and the in-memory enqueue are not atomic. If queue.push fails after db.put succeeds (only possible when the internal lock is poisoned), the event is already durable and will be replayed on the next open call. Callers should treat this as at-least-once delivery.

pub fn get( &self, id: u64, ) -> Result<Option<DurableEvent<T>>, DurableEventQueueError>

Reads an unacked event by id without marking it in flight.

pub fn poll(&self) -> Result<Option<DurableEvent<T>>, DurableEventQueueError>

Waits briefly for an available durable event.

pub fn pop(&self) -> Result<Option<DurableEvent<T>>, DurableEventQueueError>

Returns the next available durable event immediately.

pub fn ack(&self, id: u64) -> Result<(), DurableEventQueueError>

Marks an event as handled by deleting it from RocksDB.

This method is intentionally not strict for performance: acking an unknown or already-acked id succeeds because RocksDB deletes are idempotent and avoid an extra read.

pub fn ack_many<I>(&self, ids: I) -> Result<(), DurableEventQueueError>

where I: IntoIterator<Item = u64>,

Marks multiple events as handled with a single RocksDB batch write.

Like ack, this is intentionally not strict: unknown or already-acked ids succeed because RocksDB deletes are idempotent and avoid extra reads.

pub fn nack(&self, id: u64) -> Result<(), DurableEventQueueError>

Re-enqueues an in-flight event at the front of the ready queue without removing it from the durable store. Use this when a consumer cannot handle an event and wants it available for the next poll/pop without restarting.

pub fn len(&self) -> Result<usize, DurableEventQueueError>

Counts unacked events in RocksDB.

This scans the dedicated queue DB, so it is O(n) in the number of unacked events. Prefer using it for diagnostics/tests rather than hot path metrics.

pub fn is_empty(&self) -> Result<bool, DurableEventQueueError>

Returns true when there are no unacked events in RocksDB.

pub fn ready_len(&self) -> Result<usize, DurableEventQueueError>

Counts events currently available for processing.

pub fn iterator(&self) -> DurableEventQueueIterator<'_, T>

Iterates over all unacked events in id order.