Module pager 

Pager (L1) — fixed-size page allocator, freelist, bounded LRU cache, and the WAL-aware write path.

The pager is the lowest-level component that handles named pages: PageIds are non-zero u64s, page bodies are exactly PAGE_SIZE bytes. The pager hides the difference between a file-backed database and an in-memory one (Pager::memory) so higher layers see a single uniform interface.

Power-of-ten posture

• Rule 2. Every loop is bounded by the page count or the cache capacity — both are integers known at function entry.
• Rule 3. No heap allocation occurs on the read hot path: cache frames are allocated at Pager::open and reused. The freelist walks a single page at a time using stack-only state.
• Rule 7. No unwrap/expect in production code paths. Internal invariant violations use debug_assert! (Rule 5).
• Rule 8. All syscalls go through crate::platform; this module is #![forbid(unsafe_code)].

Re-exports

pub use crate::pager::page::PAGE_SIZE as PAGER_PAGE_SIZE;

Modules

cache

Bounded LRU page cache.

checksum

CRC32C helpers used by both the page-0 header and the page trailer.

freelist

Freelist representation.

header

Page-0 file header — encode / decode.

page

Page primitives: the fixed page size, the strongly-typed page id, and the owned page buffer.

Structs

Config

Pager construction options.

HeaderSnapshot

Snapshot of the page-0 header fields that the M5 catalog + freelist code mutates directly (not through the WAL).

PageRef

A borrowed view of a cached or WAL-staged page.

Pager

The pager.

ReaderSnapshot

A reader-side MVCC snapshot of the database.

SnapshotId

Opaque identifier for a single live MVCC reader snapshot.

Enums

CompressionMode

Phase 3 (issue #8): per-pager compression knob. Selects whether newly-created files use the transparent LZ4 page-compression layer (format_minor = 1, feature_flags bit 0 set) or stay at the original uncompressed format_minor = 0 layout.

PageHandle

Owning handle to a page returned by ReaderSnapshot::read_page.

Constants

DEFAULT_CACHE_FRAMES

Default LRU cache size when Config::default is used. 64 frames = 256 KiB of cached pages, comfortably within an embedded budget.

Functions

decode_page_v1

Phase 3 (issue #8): decode a 4096-byte on-disk page from a format_minor = 1 file into its raw 4092-byte body representation (with a v0 trailer re-stamped so downstream consumers that call page_trailer_valid continue to work).

encryption_feature_compiled_in

Phase 4 (issue #9): true iff this build was compiled with the encryption Cargo feature. Exposed for diagnostic tooling and integration tests that need to dispatch on the feature without embedding a cfg! of their own.

lock_path_for

Construct the cross-process lock sidecar path for a given main-file path. We append -lock to the file name (mirroring the <db>-wal sidecar convention); the lock file lives next to the main DB and is the byte-range target for WRITER_LOCK / READER_LOCK_RANGE (see platform::lock).

wal_path_for

Construct the WAL sidecar path for a given main-file path. We append -wal to the file name (mirroring SQLite’s convention); the WAL lives next to the main file.

Type Aliases

MasterKeyBytes

See MasterKeyBytes — no-encryption build (bare array, no secret material is ever stored so nothing to wipe).