Module paged 

Blob wrappers for reading and writing data with integrity guarantees, plus a page cache that manages read caching over the data.

Page-oriented structure

Blob data is stored in pages having a logical page size dictated by the managing page cache: the payload bytes stored per page. A physical page is what a page occupies on disk: the logical page followed by a 12-byte CRC record containing:

| len1 (2 bytes) |  crc1 (4 bytes) | len2 (2 bytes) | crc2 (4 bytes) |

Throughout this module, an unqualified page size always denotes the logical size (matching the configured value); only physical sizes carry a qualified physical_page_size name.

Storage-page alignment

Physical page p begins at blob offset p * physical_page_size, and a blob created with the default layout (crate::DEFAULT_BLOB_LAYOUT) begins its data on a 4096-byte boundary. Choosing a logical page size such that the physical page size is a power of two (see page_size) therefore makes every physical page either fit within a single 4096-byte storage page or start on a 4096-byte boundary and span whole storage pages. Blobs with the unaligned crate::BlobLayout::V0 layout begin their data at offset 8 and never align, regardless of the page size chosen.

Alignment is a performance property, not a correctness requirement: any page size works, but physical pages that straddle storage-page boundaries amplify cold random reads.

Two checksums are stored so that re-writing a partial page cannot destroy the valid checksum for its last durable contents. Each rewrite covers the whole physical page: the new checksum lands in the slot not protecting the durable contents, while the durable prefix and its protected checksum are resubmitted byte-identically, leaving their durable bytes unchanged even if the write tears. A checksum over a page is computed over the first [0,len) bytes in the page, with all other bytes in the page ignored. Ordinary partial-page payload writes 0-pad the range [len, page_size), but recovery does not depend on bytes outside [0,len). A checksum with length 0 is never considered valid. If both checksums are valid for the page, the one with the larger len is considered authoritative. Partial-page shrink first makes the shorter checksum durable in the alternate slot, then invalidates the old longer checksum.

A full page is one whose crc stores a len equal to the logical page size. Otherwise the page is called partial. All pages in a blob are full except for the very last page, which can be full or partial. A partial page’s durable prefix remains recoverable while it is rewritten.

Structs

CacheRef

A reference to a page cache that can be shared across threads via cloning, along with the page size that will be used with it. Provides the API for interacting with the page cache in a thread-safe manner.

Replay

Replays logical data from a blob containing pages with interleaved CRCs.

Sealed

An immutable, page-cache-backed read handle for a Blob. The read-only counterpart to super::Writer.

Writer

Unique writer to a cache-wrapped Blob.

Constants

CHECKSUM_SIZE

Size in bytes of the checksum record appended to each logical page.

Functions

page_size

The logical page size whose physical page occupies exactly physical_page_size bytes on disk (see the module docs on storage-page alignment).