Struct Spool 

pub struct Spool { /* private fields */ }

Available on crate feature spool only.

A disk-backed async FIFO queue with optional compression.

Provides persistent storage for binary data with crash-safe writes. Items are stored in FIFO order and survive application restarts.

Built on yaque, a fast, async, persistent queue with transactional semantics.

Implementations

impl Spool

pub async fn open(config: SpoolConfig) -> Result<Self>

Open or create a spool at the configured path.

If the directory exists, opens the existing queue. If the directory doesn’t exist, creates a new queue.

Errors

Returns an error if the queue cannot be opened or created.

pub async fn create(path: impl AsRef<Path>) -> Result<Self>

Create a new spool at the given path with default settings.

Errors

Returns an error if the queue cannot be created.

pub async fn create_compressed(path: impl AsRef<Path>) -> Result<Self>

Create a new spool with compression enabled.

Errors

Returns an error if the queue cannot be created.

pub async fn push(&mut self, data: &[u8]) -> Result<()>

Push data onto the queue.

If compression is enabled, the data is compressed before storage.

Errors

Returns an error if:

• The queue has reached its maximum item count
• Compression fails
• I/O error occurs

pub async fn peek(&mut self) -> Result<Option<Vec<u8>>>

Peek at the first item in the queue without removing it.

Note: In yaque, there’s no direct peek. This uses try_recv and lets the guard rollback on drop.

Errors

Returns an error if decompression fails or an I/O error occurs.

pub async fn pop(&mut self) -> Result<()>

Remove the first item from the queue.

Errors

Returns an error if an I/O error occurs.

pub async fn pop_front(&mut self) -> Result<Option<Vec<u8>>>

Pop and return the first item from the queue.

This atomically receives and removes the item.

Errors

Returns an error if decompression fails or an I/O error occurs.

pub async fn recv(&mut self) -> Result<Vec<u8>>

Receive an item asynchronously, waiting if the queue is empty.

This is the preferred async method for consuming items.

Errors

Returns an error if decompression fails or an I/O error occurs.

pub fn len(&self) -> usize

Get the approximate number of items in the queue.

Note: This is tracked internally and may not be accurate if the queue was opened with existing data.

pub fn is_empty(&self) -> bool

Check if the queue is empty.

pub fn clear(&mut self) -> Result<()>

Clear all items from the queue.

This removes all files in the queue directory and recreates it.

Errors

Returns an error if an I/O error occurs.

pub fn config(&self) -> &SpoolConfig

Get the configuration for this spool.

pub fn file_size(&self) -> Result<u64>

Get the approximate directory size in bytes.

Errors

Returns an error if the directory cannot be read.

Trait Implementations

impl Debug for Spool

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

Formats the value using the given formatter.