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 shared 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 with WriteOptions::SYNC, which is not a durability barrier for those external mutations.

Storage-mutating functions consume the writer and return it only on success: an error (or a dropped future) destroys the handle.

Example

use commonware_runtime::{Runner, 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 blob = Write::new(blob, 0, NZUsize!(16));
    let blob = blob.write_at(0, b"hello").await.expect("write failed");
    let blob = blob.sync().await.expect("sync failed");

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

    // Release the writer and read back the persisted data through a new open.
    drop(blob);
    let (blob, size) = context.open("my_partition", b"my_data").await.expect("unable to reopen blob");
    let mut reader = Read::new(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) -> 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 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 const fn needs_sync(&self) -> bool

Whether Self::sync would write buffered bytes, sync the blob, or observe a started sync.

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

Read exactly len immutable bytes starting at offset.

pub fn try_write_at(&mut self, offset: u64, buf: &[u8]) -> bool

Merge buf into the in-memory tip buffer at offset.

Returns whether buf fit. Returns false without changing the writer when it does not fit. Performs no I/O and does not make the write durable. Callers can fall back to Self::write_at when it does not fit.

pub async fn write_at( self, offset: u64, bufs: impl Into<IoBufs> + Send, ) -> Result<Self, 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<Self, 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<Self, Error>

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

pub async fn start_sync(self) -> Result<(Self, Handle<()>), Error>

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. A failure of the started sync is reported by the handle and by the next such call. Flush errors are returned directly.

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

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