Struct Write 

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

A writer that buffers the raw content of a Blob to optimize the performance of appending or updating data.

Allocation Semantics

• Self::new starts with a detached tip buffer and allocates backing on first buffered write.
• Subsequent writes reuse that backing, copy-on-write allocation only occurs when buffered data is shared (for example, after handing out immutable views) or a merge needs more capacity.
• Sparse writes merged into tip extend logical length and zero-fill any gap in-buffer.
• Flush paths (Self::sync, Self::resize, overlap flushes in Self::write_at) hand drained bytes to the blob and leave the tip detached until the next buffered write.

Example

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

let executor = deterministic::Runner::default();
executor.start(|context| async move {
    // Open a blob for writing
    let (blob, size) = context.open("my_partition", b"my_data").await.expect("unable to open blob");
    assert_eq!(size, 0);

    // Create a buffered writer with 16-byte buffer
    let mut blob = Write::from_pooler(&context, blob, 0, NZUsize!(16));
    blob.write_at(0, b"hello").await.expect("write failed");
    blob.sync().await.expect("sync failed");

    // Write more data in multiple flushes
    blob.write_at(5, b" world").await.expect("write failed");
    blob.write_at(11, b"!").await.expect("write failed");
    blob.sync().await.expect("sync failed");

    // Read back the data to verify
    let (blob, size) = context.open("my_partition", b"my_data").await.expect("unable to reopen blob");
    let mut reader = Read::from_pooler(&context, blob, size, NZUsize!(8));
    let buf = reader.read(size as usize).await.expect("read failed");
    assert_eq!(buf.coalesce().as_ref(), b"hello world!");
});

Implementations

impl<B: Blob> Write<B>

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

Creates a new Write that buffers up to capacity bytes of data to be appended to the tip of blob with the provided size.

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

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

pub async fn size(&self) -> u64

Returns the current logical size of the blob including any buffered data.

This represents the total size of data that would be present after flushing.

pub async fn read_at(&self, offset: u64, len: usize) -> Result<IoBufs, Error>

Read exactly len immutable bytes starting at offset.

pub async fn write_at( &self, offset: u64, bufs: impl Into<IoBufs> + Send, ) -> Result<(), Error>

Write bytes from buf at offset.

Data is merged into the in-memory tip buffer when possible, otherwise buffered data may be flushed and chunks are written directly to the underlying blob.

Returns Error::OffsetOverflow when offset + bufs.len() overflows.

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

Resize the logical blob to len.

If buffered data exists and the resize extends beyond current size, buffered data is flushed before resizing the underlying blob.

pub async fn sync(&self) -> Result<(), Error>

Flush buffered bytes and durably sync the underlying blob.

Trait Implementations

impl<B: Clone + Blob> Clone for Write<B>

fn clone(&self) -> Write<B>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.