Struct Pager 

pub struct Pager { /* private fields */ }

Native host adapter for the shared pager.

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_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 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 prefetch_hint(&self, page_id: u32)

Issue a best-effort OS read-ahead hint under the page-I/O lock.

Methods from Deref<Target = SharedPager<NativePagerFile, NativeWalBarrier>>

pub fn wal_barrier(&self) -> &W

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

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 Deref for Pager

type Target = Pager<NativePagerFile, NativeWalBarrier>

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

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.

impl PageStore for Pager

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, id: u32)