Crate page_db 

page-db

The paging substrate beneath B-tree and heap storage engines: fixed-size pages on disk, each carrying a versioned header with a CRC32C integrity check and an LSN slot for write-ahead-log coordination, read and written through cross-platform Direct I/O that bypasses the OS page cache.

This is the v0.2.0 layer: the page format and the durable file underneath it. The LRU buffer pool, pinning, and the page allocator land in later 0.x releases (see dev/ROADMAP.md). The buffer pool that will sit on top of PageFile is not here yet; today you read and write pages straight through to disk.

The shape of it

A PageFile is an array of fixed-size Pages addressed by PageId. Every page carries a header; on write the header’s checksum is stamped over the page bytes, and on read it is verified before the page is handed back — a corrupt or misdirected page is a typed PageError, never a silent read.

use page_db::{PageFile, PageId, Lsn};

// A 4 KiB-page file, Direct I/O, created if absent.
let file = PageFile::open("data.pages", page_db::DEFAULT_PAGE_SIZE)?;

// Allocate a fresh page, fill its payload, tag it with a log sequence number.
let mut page = file.allocate_page();
page.set_lsn(Lsn::new(1));
page.payload_mut()[..5].copy_from_slice(b"hello");

// Write it to slot 0 and make it durable.
let id = PageId::new(0);
file.write_page(id, &mut page)?;
file.sync()?;

// Read it back — the header and checksum are verified on the way out.
let read = file.read_page(id)?;
assert_eq!(&read.payload()[..5], b"hello");
assert_eq!(read.lsn(), Lsn::new(1));

Re-exports

pub use crate::checksum::crc32c;

Modules

checksum

CRC32C (Castagnoli) page checksums.

Structs

Lsn

A write-ahead-log sequence number stamped into a page header.

Page

A single fixed-size page: a header and a payload in one aligned buffer.

PageFile

A file of fixed-size pages.

PageFileOptions

Options for opening a PageFile.

PageId

The id of a page within a PageFile — its slot index.

PageSize

A validated page size.

Enums

PageError

Everything that can go wrong reading, writing, or framing a page.

Constants

DEFAULT_PAGE_SIZE

The default page size (4 KiB), matching the common OS and device page size.

MAX_PAGE_SIZE

The largest accepted page size, in bytes.

MIN_PAGE_SIZE

The smallest accepted page size, in bytes.

PAGE_HEADER_SIZE

The size of the page header, in bytes. The usable payload of a page is page_size - PAGE_HEADER_SIZE.

Type Aliases

PageResult

A convenience alias for results returned by this crate.