Struct PageFile 

pub struct PageFile { /* private fields */ }

A file of fixed-size pages.

A PageFile is an array of Pages on disk, addressed by PageId: page n occupies the byte range n * page_size .. (n + 1) * page_size. Reads and writes are positioned and take &self, so the handle is shared freely across threads — there is no shared file cursor to contend on. (The cache that will front these reads is a later release; today every read goes to disk.)

Durability is two steps, deliberately: write_page places bytes, and sync makes them durable. Batch many writes, then sync once.

Examples

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

let file = PageFileOptions::new().direct_io(false).open(&path)?;

let mut page = file.allocate_page();
page.set_lsn(Lsn::new(1));
page.payload_mut()[..3].copy_from_slice(b"abc");
file.write_page(PageId::new(0), &mut page)?;
file.sync()?;

let got = file.read_page(PageId::new(0))?;
assert_eq!(&got.payload()[..3], b"abc");
assert_eq!(file.page_count()?, 1);

Implementations

impl PageFile

pub fn open<P: AsRef<Path>>(path: P, page_size: PageSize) -> PageResult<Self>

Open a page file at path with the given page size and the default options (Direct I/O on, create-if-absent).

For buffered I/O or other tuning, use PageFileOptions.

Errors

Returns PageError::Io if the file cannot be opened.

pub fn page_size(&self) -> usize

The page size of this file, in bytes.

pub fn page_count(&self) -> PageResult<u64>

The number of whole pages currently in the file.

Errors

Returns PageError::Io if the file metadata cannot be read.

pub fn allocate_page(&self) -> Page

Allocate a fresh, zeroed page sized and aligned for this file.

The page is in memory only; write it with write_page to place it in a slot.

pub fn read_page(&self, id: PageId) -> PageResult<Page>

Read the page at slot id, verifying its header and checksum.

The page’s magic, version, and CRC32C are checked, and its stamped id is matched against id, before it is returned — so a corrupt or misdirected page surfaces as an error rather than bad data.

Errors

• PageError::ShortRead if the slot is past the end of the file.
• PageError::BadMagic / PageError::UnsupportedVersion / PageError::ChecksumMismatch / PageError::MisdirectedPage if the page fails validation.
• PageError::Io on an I/O failure.

pub fn read_into(&self, id: PageId, page: &mut Page) -> PageResult<()>

Read the page at slot id into an existing buffer, verifying it.

This is the zero-allocation form of read_page: it reuses page’s buffer instead of allocating a fresh one, which is how a buffer pool recycles a frame on a cache miss. page.page_size() must match the file’s.

Errors

As read_page, plus PageError::InvalidPageSize if page’s size does not match the file’s.

pub fn write_page(&self, id: PageId, page: &mut Page) -> PageResult<()>

Write page to slot id, stamping the slot id and a fresh checksum.

The page’s id and checksum header fields are updated in place, so the same page can be written, mutated, and written again. The write places the bytes; call sync to make them durable.

Errors

• PageError::InvalidPageSize if the page’s size does not match the file’s.
• PageError::Io on an I/O failure.

pub fn sync(&self) -> PageResult<()>

Flush all written pages to stable storage.

Returns once the data is durable — fdatasync on Linux, FlushFileBuffers on Windows, F_FULLFSYNC on macOS.

Errors

Returns PageError::Io if the flush fails.

Trait Implementations

impl Debug for PageFile

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl PageStore for PageFile

fn page_size(&self) -> usize

The fixed page size of this store, in bytes.

fn allocate_page(&self) -> Page

Allocate a blank page sized for this store. The page is in memory only.

fn read_into(&self, id: PageId, page: &mut Page) -> PageResult<()>

Read the page at id into page, verifying it.

fn write_page(&self, id: PageId, page: &mut Page) -> PageResult<()>

Write page to slot id. The page’s header is stamped (id + checksum) as part of the write.

fn sync(&self) -> PageResult<()>

Flush all written pages to stable storage.