Struct Writer 

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

Unique writer to a cache-wrapped Blob.

Implementations

impl<B: Blob> Writer<B>

pub async fn new( blob: B, original_blob_size: u64, capacity: usize, cache_ref: CacheRef, ) -> Result<Self, Error>

Wrap blob in a Writer. blob must already hold original_blob_size physical bytes; reads are cached through cache_ref and appends stage in a write buffer of capacity capacity. Rewinds the blob if necessary so it only contains checksum-validated data.

pub async fn append(&mut self, buf: &[u8]) -> Result<u64, Error>

Append all bytes in buf to the tip of the blob, returning the logical offset at which the first byte was written.

pub async fn append_owned(&mut self, buf: IoBuf) -> Result<u64, Error>

Append owned bytes to the tip of the blob.

Large appends fill the current tip to a page boundary, write complete pages directly to the blob, and leave only a sub-page suffix in the write buffer. This avoids copying full-page payloads while preserving the invariant that the buffer starts at current_page.

pub const fn size(&self) -> u64

Returns the size of the blob.

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

Read into buf if it can be done synchronously without I/O. Returns true only if all buf.len() bytes were satisfied from the page cache and/or the in-memory tail. When false is returned, the contents of buf are unspecified.

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

Read exactly len immutable bytes starting at offset.

pub async fn read_up_to( &self, offset: u64, len: usize, bufs: impl Into<IoBufMut> + Send, ) -> Result<(IoBufMut, usize), Error>

Reads up to len bytes starting at offset, but only as many as are available.

Returns the buffer (truncated to actual bytes read) and the number of bytes read. Returns an error if no bytes are available at the given offset.

pub async fn read_many_into( &self, buf: &mut [u8], offsets: &[u64], item_size: NonZeroUsize, ) -> Result<usize, Error>

Read multiple fixed-size items at sorted byte offsets into a contiguous caller buffer.

buf must be exactly offsets.len() * item_size bytes. All offsets must be sorted, non-overlapping, and within bounds.

Returns the number of items fully served without a blob read (from the in-memory tail and the page cache). The remaining items required at least one blob read.

pub fn try_read_many_sync_into( &self, buf: &mut [u8], offsets: &[u64], item_size: NonZeroUsize, ) -> Vec<usize>

Like Self::read_many_into, but synchronous and cache-only. Returns the indices of items that require a blob read. Their slots in buf hold unspecified bytes.

pub fn try_read_ranges_sync_into( &self, buf: &mut [u8], ranges: &[(u64, usize)], ) -> Vec<usize>

Like Self::try_read_many_sync_into, but for variable-length (offset, len) ranges: buf holds one slot per range, back to back.

pub async fn read_into(&self, buf: &mut [u8], offset: u64) -> Result<(), Error>

Reads bytes starting at offset into buf.

pub async fn replay( &mut self, buffer_size: NonZeroUsize, ) -> Result<Replay<B>, Error>

Flushes any buffered data, then returns a Replay for the underlying blob.

The returned replay can be used to sequentially read all pages from the blob while ensuring all data passes integrity verification. CRCs are validated but not included in the output.

This is not a durable operation. Buffered data may be plainly written so the replay can read it, but callers must still use sync if that data must survive a crash.

pub async fn snapshot(&mut self) -> Result<Sealed<B>, Error>

Flush buffered data and capture an immutable super::Sealed view without consuming the writer.

This writes buffered bytes to the blob layout but does not make them durable. Call Self::sync or super::Sealed::sync if the returned handle’s bytes must survive a crash.

If this writer later rewinds or truncates into the returned handle’s range, reads from that handle may observe unspecified contents.

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

Flushes buffered data and makes all pending mutations durable.

A single physical write can be persisted with Blob::write_at_sync. If there are earlier unsynced mutations, or if the flush emits multiple physical writes, durability is completed with Blob::sync.

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

Flushes buffered data and begins making all pending mutations durable, returning a completion handle.

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 first wait for any outstanding start_sync handles.

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

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

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

Resize the blob to the provided logical size.

This truncates the blob to contain only size logical bytes. The physical blob size will be adjusted to include the necessary CRC records for the remaining pages.

Warning

• Concurrent mutable operations (append, resize) are not supported and will cause data loss.
• Concurrent readers which try to read past the new size during the resize may error.
• The resize is not guaranteed durable until the next sync.

pub async fn seal(self) -> Result<Sealed<B>, Error>

Consume the write handle and return an immutable super::Sealed handle for the same blob.

Buffered bytes (full and partial pages) are written to the underlying blob, but the blob is not fsynced. The returned super::Sealed handle can be made durable later via super::Sealed::sync.