Struct Append 

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

A Blob wrapper that supports write-cached appending of data, with checksums for data integrity and page cache managed caching.

Implementations

impl<B: Blob> Append<B>

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

Create a new Append wrapper of the provided blob that is known to have blob_size underlying physical bytes, using the provided cache_ref for read caching, and a write buffer with capacity capacity. Rewinds the blob if necessary to ensure it only contains checksum-validated data.

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

Append all bytes in buf to the tip of the blob.

pub async fn size(&self) -> u64

Returns the logical size of the blob. This accounts for both written and buffered data.

pub fn try_size(&self) -> Option<u64>

Returns the logical size of the blob if it can be observed without waiting.

This is useful for opportunistic fast paths that should fall back rather than contend with concurrent writers.

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

Read into buf if it can be done synchronously (e.g. without I/O), returning false otherwise.

Returns true only if all buf.len() bytes were satisfied. The caller must have already validated that offset + buf.len() is within the blob’s logical size.

The page cache is consulted first to minimize the risk of writer starvation from a burst of buffer reads (which jump ahead of queued writers on the buffer lock).

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, logical_offset: u64, len: usize, bufs: impl Into<IoBufMut> + Send, ) -> Result<(IoBufMut, usize), Error>

Reads up to buf.len() bytes starting at logical_offset, but only as many as are available.

This is useful for reading variable-length prefixes (like varints) where you want to read up to a maximum number of bytes but the actual data might be shorter.

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: usize, ) -> Result<(), 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. This amortizes lock acquisition and avoids per-item buffer allocation compared to calling read_at in a loop.

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

Reads bytes starting at logical_offset into buf.

This method allows reading directly into a mutable slice without taking ownership of the buffer or requiring a specific buffer type.

pub async fn replay( &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.

impl<B: Blob> Append<B>

pub async fn sync(&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 resize(&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.

Trait Implementations

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

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

Returns a duplicate of the value.

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

Performs copy-assignment from source.