Struct Pager 

pub struct Pager { /* private fields */ }

Page I/O Manager

Handles reading/writing pages and manages the page cache.

Implementations

impl Pager

pub fn open<P: AsRef<Path>>( path: P, config: PagerConfig, ) -> Result<Self, PagerError>

Open or create a database file

pub fn open_default<P: AsRef<Path>>(path: P) -> Result<Self, PagerError>

Open with default configuration

pub fn read_page(&self, page_id: u32) -> Result<Page, PagerError>

Read a page (cache-aware)

pub fn read_page_no_checksum(&self, page_id: u32) -> Result<Page, PagerError>

Read a page without verifying checksum (for encrypted pages)

Use this when the page content has its own integrity protection (e.g., AES-GCM authentication tag for encrypted pages).

pub fn write_page(&self, page_id: u32, page: Page) -> Result<(), PagerError>

Write a page (cache-aware)

pub fn read_page_decrypted(&self, page_id: u32) -> Result<Page, PagerError>

Read a page through the configured encryptor if any. Page 0 is always returned plaintext (it carries the encryption marker

• header). Callers that want raw cipher bytes can use read_page_no_checksum directly.

pub fn write_page_encrypted( &self, page_id: u32, page: Page, ) -> Result<(), PagerError>

Write a page through the configured encryptor if any. Page 0 bypasses encryption and goes through the normal checksummed path. Encrypted pages skip the checksum update because AES-GCM’s authentication tag is the integrity guarantee.

pub fn write_page_no_checksum( &self, page_id: u32, page: Page, ) -> Result<(), PagerError>

Write a page without updating checksum (for encrypted pages)

Use this when the page content has its own integrity protection (e.g., AES-GCM authentication tag for encrypted pages).

pub fn allocate_page(&self, page_type: PageType) -> Result<Page, PagerError>

Allocate a new page

pub fn free_page(&self, page_id: u32) -> Result<(), PagerError>

Free a page (return to freelist)

pub fn header(&self) -> Result<DatabaseHeader, PagerError>

Get database header

pub fn physical_header(&self) -> Result<PhysicalFileHeader, PagerError>

pub fn update_physical_header( &self, physical: PhysicalFileHeader, ) -> Result<(), PagerError>

pub fn page_count(&self) -> Result<u32, PagerError>

Get page count

pub fn set_wal_writer(&self, wal: Arc<Mutex<WalWriter>>)

Attach a WAL writer to enforce WAL-first flush ordering.

After this call, Pager::flush computes the maximum header.lsn over all dirty pages and calls WalWriter::flush_until(max_lsn) before any page is written to the data file. This is the postgres rule: a page on disk implies its WAL record is already durable on disk.

Existing call sites that construct a Pager without a WAL keep their previous behaviour (no LSN check) — wiring is strictly opt-in.

pub fn clear_wal_writer(&self)

Detach the WAL writer (test / shutdown path).

pub fn has_wal_writer(&self) -> bool

Has a WAL writer been attached?

pub fn flush(&self) -> Result<(), PagerError>

Flush all dirty pages to disk

pub fn sync(&self) -> Result<(), PagerError>

Sync file to disk (fsync)

pub fn cache_stats(&self) -> CacheStats

Get cache statistics

pub fn dirty_page_count(&self) -> usize

Count dirty pages currently in the page cache.

pub fn dirty_fraction(&self) -> f64

Estimated fraction of the page cache holding dirty pages. Returned in [0, 1]. Used by the background writer to decide when to kick in aggressive flushing.

pub fn flush_some_dirty(&self, max: usize) -> Result<usize, PagerError>

Flush up to max dirty pages from the cache. Returns the number actually written. Background-writer entry point — reuses the same persistence path as flush() but bounded.

pub fn path(&self) -> &Path

Get database file path

pub fn is_read_only(&self) -> bool

Check if database is read-only

pub fn file_size(&self) -> Result<u64, PagerError>

Get file size in bytes

pub fn prefetch_hint(&self, page_id: u32)

Issue an OS-level read-ahead hint for page_id.

A6 prefetch wire: called from BTreeCursor::next when the cursor passes 50% of the current leaf, so the kernel fetches the next leaf page while CPU processes the remaining half of the current one. Failures are silent — a missed prefetch is a performance miss, never a correctness bug.

pub fn write_meta_shadow(&self, page: &Page) -> Result<(), PagerError>

Write a shadow copy of the metadata page to .rdb-meta

pub fn recover_meta_from_shadow(&self) -> Result<Page, PagerError>

Recover metadata page from shadow file when page 1 is corrupted

pub fn write_header_and_sync(&self) -> Result<(), PagerError>

Write header and sync to disk (public for checkpointer).

pub fn set_checkpoint_in_progress( &self, in_progress: bool, target_lsn: u64, ) -> Result<(), PagerError>

Set the checkpoint_in_progress flag in the header.

pub fn complete_checkpoint(&self, lsn: u64) -> Result<(), PagerError>

Update the checkpoint LSN and clear the in-progress flag.

Trait Implementations

impl Drop for Pager

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.