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.

Access

Write is a single-owner buffered handle that owns mutation ordering and durability bookkeeping for the wrapped Blob. Raw Blob handles cloned before wrapping observe only flushed data and may not see the latest buffered writes until Self::sync, Self::resize, or an overlapping Self::write_at flushes them. Those raw handles must not be used to write, resize, or otherwise mutate the blob while a Write exists. External mutations bypass the buffer state and Self::sync may use Blob::write_at_sync, which is not a durability barrier for those external mutations.

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 const 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( &mut 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(&mut 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(&mut self) -> Result<(), Error>

Flush buffered bytes and durably sync mutations tracked by this writer.

pub async fn start_sync(&mut self) -> Handle<()>

Flush buffered bytes and begin durably syncing mutations tracked by this writer.

Awaiting the returned Handle waits for the same durability guarantee as Self::sync for the state flushed by this call. Later calls to Self::sync and writer methods that mutate the blob wait before issuing blob operations.

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

Wait for any started sync to complete without starting a new sync.