Struct Read 

pub struct Read<B: Blob> { /* private fields */ }

A reader that buffers content from a Blob to optimize the performance of a full scan of contents.

Allocation Semantics

• The internal read buffer is allocated eagerly in Self::new.
• Refills try to reclaim mutable ownership of that same backing allocation.
• If backing is still shared (for example, previously returned slices are alive), a pooled replacement is allocated and existing backing is left alive until all aliases drop.
• Self::read returns zero-copy slices into refill buffers. Holding those slices may force allocation on subsequent refills.

Example

use commonware_utils::NZUsize;
use commonware_runtime::{Runner, buffer::Read, Blob, Error, Storage, deterministic, BufferPooler};

let executor = deterministic::Runner::default();
executor.start(|context| async move {
    // Open a blob and add some data (e.g., a journal file)
    let (blob, size) = context.open("my_partition", b"my_data").await.expect("unable to open blob");
    let data = b"Hello, world! This is a test.".to_vec();
    let size = data.len() as u64;
    blob.write_at(0, data).await.expect("unable to write data");

    // Create a buffer
    let buffer = 64 * 1024;
    let mut reader = Read::from_pooler(&context, blob, size, NZUsize!(buffer));

    // Read data sequentially
    let header = reader.read(16).await.expect("unable to read data");
    println!("Read header: {:?}", header.coalesce().as_ref());

    // Position is still at 16 (after header)
    assert_eq!(reader.position(), 16);
});

Implementations

impl<B: Blob> Read<B>

pub fn new( blob: B, blob_size: u64, buffer_size: NonZeroUsize, pool: BufferPool, ) -> Self

Creates a new Read that reads from the given blob with the specified buffer size.

pub fn from_pooler( pooler: &impl BufferPooler, blob: B, blob_size: u64, buffer_size: NonZeroUsize, ) -> Self

Creates a new Read, extracting the storage BufferPool from a BufferPooler.

pub const fn buffer_remaining(&self) -> usize

Returns how many valid bytes are remaining in the buffer.

pub const fn blob_remaining(&self) -> u64

Returns how many bytes remain in the blob from the current position.

pub const fn blob_size(&self) -> u64

Returns the number of bytes in the blob, as provided at construction.

pub async fn read(&mut self, len: usize) -> Result<IoBufs, Error>

Reads exactly len bytes and returns them as immutable bytes.

Returned bytes are composed of zero-copy slices from the internal read buffer. Holding returned slices can keep the current backing shared, which may require allocation on later refills.

Returns an error if not enough bytes are available.

pub const fn position(&self) -> u64

Returns the current absolute position in the blob.

pub const fn seek_to(&mut self, position: u64) -> Result<(), Error>

Repositions the buffer to read from the specified position in the blob.

pub async fn resize(self, len: u64) -> Result<(), Error>

Resizes the blob to the specified len and syncs the blob.

This may be useful if reading some blob after unclean shutdown.