Struct BufferedQueue 

pub struct BufferedQueue<S: NorFlash, C: CacheImpl, const RAM_BYTES: usize> { /* private fields */ }

A write-buffered queue that accepts items into a RAM ring and drains them to NOR flash.

Type parameters

• S: NOR flash driver implementing NorFlash.
• C: Cache implementation from crate::cache.
• RAM_BYTES: Capacity of the RAM ring buffer in bytes (includes 2-byte per-item overhead).

Usage pattern

// Fast path — called from a tight loop:
queue.enqueue(&sample, OverflowPolicy::Err)?;

// Slow path — called from a lower-priority task or on a timer:
queue.drain_all(&mut scratch, false).await?;

// Read path — flash items are popped first, then RAM items:
if let Some(data) = queue.pop(&mut buf).await? {
    // process data
}

For ISR-safe use, enable the shared-ram-ring feature and use [SharedRamRing] instead.

Implementations

impl<S: NorFlash, C: CacheImpl, const RAM_BYTES: usize> BufferedQueue<S, C, RAM_BYTES>

pub fn new(storage: QueueStorage<S, C>) -> Self

Wrap an existing QueueStorage with a RAM ring buffer.

pub fn enqueue(&mut self, data: &[u8], policy: OverflowPolicy) -> Result<(), ()>

Enqueue an item into the RAM ring buffer.

This is synchronous and never touches flash. When the ring is full the behaviour is determined by policy: return Err(()) or evict the oldest item.

pub async fn drain_one( &mut self, scratch: &mut [u8], allow_overwrite: bool, ) -> Result<bool, Error<S::Error>>

Drain one item from the RAM ring to flash.

scratch is caller-provided temporary storage; it must be at least as large as the oldest pending item.

Returns Ok(true) if an item was committed to flash, Ok(false) if the ring was empty.

pub async fn drain_all( &mut self, scratch: &mut [u8], allow_overwrite: bool, ) -> Result<(), Error<S::Error>>

Drain all RAM-buffered items to flash.

scratch must be large enough for the largest pending item.

pub async fn pop<'d>( &mut self, data_buffer: &'d mut [u8], ) -> Result<Option<&'d mut [u8]>, Error<S::Error>>

where S: MultiwriteNorFlash,

Pop the oldest item from the queue.

Flash items are always older than RAM items, so flash is read first. If flash is empty the oldest item is taken directly from the RAM ring without writing to flash.

pub async fn peek<'d>( &mut self, data_buffer: &'d mut [u8], ) -> Result<Option<&'d mut [u8]>, Error<S::Error>>

where S: MultiwriteNorFlash,

Peek at the oldest item without removing it.

Flash items are always older than RAM items, so flash is read first. If flash is empty the oldest item is read directly from the RAM ring without writing to flash.

pub const fn ram_capacity_bytes() -> usize

Total capacity of the RAM ring in bytes (including 2-byte per-item length prefixes).

pub fn ram_free_bytes(&self) -> usize

Free bytes remaining in the RAM ring.

pub fn ram_pending_count(&self) -> usize

Number of items currently buffered in RAM (not yet committed to flash).

pub fn ram_bytes_used(&self) -> usize

Bytes currently occupied in the RAM ring (including 2-byte per-item length prefixes).

pub fn into_storage(self) -> QueueStorage<S, C>

Consume this BufferedQueue and return the inner QueueStorage.

Any items still in the RAM ring are discarded.