Struct RetryQueue 

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

A queue for storing requests to be retried.

Implementations

impl<T> RetryQueue<T>

where T: Retryable,

pub fn new(queue_name: String, max_in_memory_bytes: u64) -> Self

Creates a new RetryQueue instance with the given name and maximum size.

The queue will only hold as many entries as can fit within the given maximum size. If the queue is full, the oldest entries will be removed (or potentially persisted to disk, see with_disk_persistence) to make room for new entries.

pub fn with_flush_to_disk_mem_ratio(self, flush_to_disk_mem_ratio: f64) -> Self

Configures the ratio of in-memory queue bytes to flush to disk when the queue is full.

When disk persistence is enabled and the queue does not have enough room for a new entry, this ratio controls how much in-memory data is moved to disk. For example, a value of 0.5 moves at least half of max_in_memory_bytes to disk when the queue overflows. Values less than or equal to zero disable extra batch flushing, but entries evicted to make room are still persisted when disk persistence is enabled.

pub async fn with_disk_persistence( self, args: PersistedQueueArgs, ) -> Result<Self, GenericError>

Configures the queue to persist pending entries to disk.

Disk persistence is used as a fallback to in-memory storage when the queue is full. When attempting to add a new entry to the queue, and the queue can’t fit the entry in-memory, in-memory entries will be persisted to disk, oldest first.

When reading entries from the queue, in-memory entries are read first, followed by persisted entries. This provides priority to the most recent entries added to the queue, but allows for bursting over the configured in-memory size limit without having to immediately discard entries.

Files are stored in a subdirectory, with the same name as the given queue name, within args.root_path.

Errors

If there is an error initializing the disk persistence layer, an error is returned.

pub fn is_empty(&self) -> bool

Returns true if the queue is empty.

This includes both in-memory and persisted entries.

pub fn len(&self) -> usize

Returns the number of entries in the queue

This includes both in-memory and persisted entries.

pub const fn max_in_memory_bytes(&self) -> u64

Returns the maximum in-memory capacity, in bytes.

pub const fn available_in_memory_capacity_bytes(&self) -> u64

Returns the available in-memory capacity, in bytes.

pub async fn available_on_disk_capacity_bytes( &self, ) -> Result<u64, GenericError>

Returns the available on-disk capacity, in bytes.

Returns 0 when disk persistence is not enabled.

Errors

If disk persistence is enabled and there is an error while retrieving the underlying disk capacity, an error is returned.

pub fn take_persisted_entries_dropped(&mut self) -> u64

Returns the number of persisted entries that have been permanently dropped due to errors since the last call to this method, resetting the counter.

Always returns 0 if disk persistence isn’t enabled.

pub async fn push(&mut self, entry: T) -> Result<PushResult, GenericError>

Enqueues an entry.

If the queue is full and the entry can’t be enqueued in-memory, in-memory entries (oldest first) are evicted until there is room for the new entry. When disk persistence is enabled, evicted entries are moved to disk. If the flush-to-disk ratio is greater than zero, eviction moves at least max_in_memory_bytes * flush_to_disk_mem_ratio bytes of in-memory data to disk before admitting the new entry. If disk persistence is disabled, evicted entries are dropped instead. If an in-memory entry can’t be persisted due to a disk error, that entry is dropped and counted in the returned PushResult; the new entry is still enqueued.

Errors

If the entry is too large to fit into the queue, an error is returned.

pub async fn pop(&mut self) -> Result<Option<T>, GenericError>

Consumes an entry.

In-memory entries are consumed first, followed by persisted entries if disk persistence is enabled.

If no entries are available, None is returned.

Errors

If there is an error when consuming an entry from disk, whether due to reading or deserializing the entry, an error is returned.

pub async fn flush(self) -> Result<PushResult, GenericError>

Flushes all entries, potentially persisting them to disk.

When disk persistence is configured, this will flush all in-memory entries to disk. Flushing to disk still obeys the normal limiting behavior in terms of maximum on-disk size. When disk persistence isn’t enabled, all in-memory entries will be dropped.

Errors

If an error occurs while persisting an entry to disk, an error is returned.