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.

Three layers ship today. The PageFile is the durable foundation: an array of fixed-size Pages addressed by PageId, read and written through Direct I/O, every read verified against its header and checksum. The BufferPool sits on top: a bounded cache of frames with pinning and dirty tracking, so hot pages stay resident and the engine above asks for a page by id and gets back a pinned frame. The PageAllocator manages the id space: it hands out unused ids and reclaims freed ones through an on-disk free-list. Compose them over one shared store with Arc (see PageStore). The public API is feature-frozen as of v0.4.0; see dev/ROADMAP.md.

Straight to the file

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));

Through the buffer pool

use page_db::{BufferPool, PageId, Lsn, DEFAULT_PAGE_SIZE};

let pool = BufferPool::open("data.pages", DEFAULT_PAGE_SIZE, 256)?;

// Create a page; writing through the guard marks the frame dirty.
{
    let guard = pool.new_page(PageId::new(0))?;
    guard.write().set_lsn(Lsn::new(1));
}
pool.checkpoint()?;   // flush dirty frames, then make the file durable

// Fetch it — served from cache, the page stays pinned for the guard's life.
let guard = pool.fetch(PageId::new(0))?;
assert_eq!(guard.read().lsn(), Lsn::new(1));

Re-exports

pub use crate::checksum::crc32c;

Modules

checksum

CRC32C (Castagnoli) page checksums.

Structs

BufferPool

A bounded cache of pages over a PageStore.

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.

PageAllocator

A page-id allocator over a PageStore.

PageFile

A file of fixed-size pages.

PageFileOptions

Options for opening a PageFile.

PageGuard

A pin on a cached page.

PageId

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

PageMut

An exclusive write borrow of a pinned page. Dereferences to Page.

PageRef

A shared read borrow of a pinned page. Dereferences to Page.

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.

Traits

PageStore

A backing store of fixed-size pages addressed by PageId.

Type Aliases

PageResult

A convenience alias for results returned by this crate.