page_db/
lib.rs

1//! # page-db
2//!
3//! The paging substrate beneath B-tree and heap storage engines: fixed-size
4//! pages on disk, each carrying a versioned header with a CRC32C integrity
5//! check and an LSN slot for write-ahead-log coordination, read and written
6//! through cross-platform Direct I/O that bypasses the OS page cache.
7//!
8//! Three layers ship today. The [`PageFile`] is the durable foundation: an array
9//! of fixed-size [`Page`]s addressed by [`PageId`], read and written through
10//! Direct I/O, every read verified against its header and checksum. The
11//! [`BufferPool`] sits on top: a bounded cache of frames with pinning and dirty
12//! tracking, so hot pages stay resident and the engine above asks for a page by
13//! id and gets back a pinned frame. The [`PageAllocator`] manages the id space:
14//! it hands out unused ids and reclaims freed ones through an on-disk free-list.
15//! Compose them over one shared store with `Arc` (see [`PageStore`]). The public
16//! API is feature-frozen as of v0.4.0; see `dev/ROADMAP.md`.
17//!
18//! ## Straight to the file
19//!
20//! Every page carries a header; on write the header's checksum is stamped over
21//! the page bytes, and on read it is verified before the page is handed back —
22//! a corrupt or misdirected page is a typed [`PageError`], never a silent read.
23//!
24//! ```no_run
25//! use page_db::{PageFile, PageId, Lsn};
26//!
27//! # fn main() -> Result<(), page_db::PageError> {
28//! // A 4 KiB-page file, Direct I/O, created if absent.
29//! let file = PageFile::open("data.pages", page_db::DEFAULT_PAGE_SIZE)?;
30//!
31//! // Allocate a fresh page, fill its payload, tag it with a log sequence number.
32//! let mut page = file.allocate_page();
33//! page.set_lsn(Lsn::new(1));
34//! page.payload_mut()[..5].copy_from_slice(b"hello");
35//!
36//! // Write it to slot 0 and make it durable.
37//! let id = PageId::new(0);
38//! file.write_page(id, &mut page)?;
39//! file.sync()?;
40//!
41//! // Read it back — the header and checksum are verified on the way out.
42//! let read = file.read_page(id)?;
43//! assert_eq!(&read.payload()[..5], b"hello");
44//! assert_eq!(read.lsn(), Lsn::new(1));
45//! # Ok(())
46//! # }
47//! ```
48//!
49//! ## Through the buffer pool
50//!
51//! ```no_run
52//! use page_db::{BufferPool, PageId, Lsn, DEFAULT_PAGE_SIZE};
53//!
54//! # fn main() -> Result<(), page_db::PageError> {
55//! let pool = BufferPool::open("data.pages", DEFAULT_PAGE_SIZE, 256)?;
56//!
57//! // Create a page; writing through the guard marks the frame dirty.
58//! {
59//!     let guard = pool.new_page(PageId::new(0))?;
60//!     guard.write().set_lsn(Lsn::new(1));
61//! }
62//! pool.checkpoint()?;   // flush dirty frames, then make the file durable
63//!
64//! // Fetch it — served from cache, the page stays pinned for the guard's life.
65//! let guard = pool.fetch(PageId::new(0))?;
66//! assert_eq!(guard.read().lsn(), Lsn::new(1));
67//! # Ok(())
68//! # }
69//! ```
70
71#![cfg_attr(docsrs, feature(doc_cfg))]
72#![deny(missing_docs)]
73#![deny(unsafe_op_in_unsafe_fn)]
74#![deny(unused_must_use)]
75#![deny(unused_results)]
76#![deny(clippy::unwrap_used)]
77#![deny(clippy::expect_used)]
78#![deny(clippy::todo)]
79#![deny(clippy::unimplemented)]
80#![deny(clippy::print_stdout)]
81#![deny(clippy::print_stderr)]
82#![deny(clippy::dbg_macro)]
83#![deny(clippy::undocumented_unsafe_blocks)]
84
85mod alloc;
86mod buffer;
87pub mod checksum;
88mod error;
89mod file;
90mod page;
91mod pool;
92mod store;
93mod sync;
94mod sys;
95#[cfg(test)]
96mod test_store;
97
98pub use crate::alloc::PageAllocator;
99pub use crate::checksum::crc32c;
100pub use crate::error::{PageError, PageResult};
101pub use crate::file::{PageFile, PageFileOptions};
102pub use crate::page::{
103    DEFAULT_PAGE_SIZE, Lsn, MAX_PAGE_SIZE, MIN_PAGE_SIZE, PAGE_HEADER_SIZE, Page, PageId, PageSize,
104};
105pub use crate::pool::{BufferPool, PageGuard, PageMut, PageRef};
106pub use crate::store::PageStore;
page_db/lib.rs

page_db/
lib.rs
