Struct Pager 

pub struct Pager<F: VfsFile, W: WalBarrier> { /* private fields */ }

Implementations

impl<F: VfsFile, W: WalBarrier> Pager<F, W>

pub fn open_owned( file: F, path: PathBuf, config: PagerConfig, wal: W, create: bool, ) -> Result<Self, PagerError>

Use an already-owned file. The host retains exclusive ownership until this pager is dropped, and supplies the native WAL/encryption policy. create is explicit: a corrupt or empty existing file is never recreated.

pub fn wal_barrier(&self) -> &W

pub fn lock_ownership_mutations(&self) -> ReentrantMutexGuard<'_, ()>

Hold across an entire ownership publication, not just individual allocation calls. Readers may continue accessing already-published pages.

pub fn fence_interrupted_ownership(&self)

An interrupted publication must be recovered before any more writes.

pub fn fence_file_format_version(&self, version: u32) -> Result<(), PagerError>

Fence a file-format upgrade in both recoverable superblock copies.

The caller must exclude other mutators while the fence is in progress and may publish a new mandatory format only after this succeeds. A failed write fences subsequent mutation until reopen and recovery.

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 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 reserve_contig_extent( &self, n_pages: u32, ) -> Result<ExtentId, PagerError>

Reserve a contiguous extent of vector pages.

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

Free a page (return to freelist)

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

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

pub fn restore_deferred_reclamation( &self, pages: &[u32], ) -> Result<(), PagerError>

pub fn complete_deferred_publication( &self, retained: &[u32], released: &[u32], ) -> Result<(), PagerError>

The caller has durably published a catalog that retains retained and no longer names released, after waiting for old tree readers.

pub fn record_retirement_intent(&self, pages: &[u32]) -> Result<(), PagerError>

Record the pages whose catalog ownership is about to be retired.

pub fn free_retired_pages(&self, pages: &[u32]) -> Result<(), PagerError>

Return a fully validated, unpublished tree generation in one allocator mutation. Call only after its removal from the manifest is durable.

pub fn recover_unowned_pages(&self, pages: &[u32]) -> Result<(), PagerError>

Add proven-unowned pages to the allocator exactly once during recovery. The caller must exclude all allocation and publication until this state has been synced to both superblocks and the journal is completed.

pub fn validate_owned_pages(&self, pages: &[u32]) -> Result<(), PagerError>

Reject a recovery plan if any page it must preserve is already free. The caller must exclude allocation and freelist mutation during recovery.

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

Persist the current allocator in both fallback copies during recovery. The caller must exclude allocation until journal completion is durable.

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

Get database header Pages available to the allocator, including pages on unloaded trunks.

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

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 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 cache_len(&self) -> usize

Pages currently resident in the page cache. Slots are fixed size, so this times the page size is the cache’s memory footprint (ADR 0073 §2).

pub fn cache_capacity(&self) -> usize

Preallocated page-cache slots — the sizing this process derived from its page-cache budget share.

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 read_manifest_page(&self) -> Result<Page, PagerError>

Read the internal manifest page (page 1), the zone the superblock roots.

ADR 0074 §2: manifest corruption fails the open didactically, naming the zone — it never falls back to a sidecar and never returns garbage.

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<F: VfsFile, W: WalBarrier> PageStore for Pager<F, W>

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

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

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

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

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

fn prefetch_hint(&self, _page_id: u32)