wasm_dbms_memory/
lib.rs

1// Rust guideline compliant 2026-04-28
2// X-WHERE-CLAUSE, M-CANONICAL-DOCS
3
4#![crate_name = "wasm_dbms_memory"]
5#![crate_type = "lib"]
6#![cfg_attr(docsrs, feature(doc_cfg))]
7#![deny(clippy::print_stdout)]
8#![deny(clippy::print_stderr)]
9
10//! # wasm-dbms-memory
11//!
12//! Runtime-agnostic memory abstraction and page management for the
13//! [`wasm-dbms`](https://crates.io/crates/wasm-dbms) framework.
14//!
15//! This crate sits between the raw byte storage exposed by a WASM
16//! runtime (heap, file, IC stable memory, ...) and the higher-level
17//! DBMS engine. It defines the [`MemoryProvider`] trait that abstracts
18//! over the storage backend and the on-top-of-it data structures that
19//! the engine uses to persist tables, schema, and indexes.
20//!
21//! All structures use 64 KiB pages so the on-disk layout is byte-for-byte
22//! identical across providers — a heap-built database can be dumped and
23//! reopened as IC stable memory or a WASI file with no conversion.
24//!
25//! ## What this crate provides
26//!
27//! Storage backends:
28//!
29//! - [`MemoryProvider`] — trait every backend implements (read, write,
30//!   grow, page count).
31//! - [`HeapMemoryProvider`] — in-memory provider for tests and embedded
32//!   use cases.
33//!
34//! Engine-facing data structures:
35//!
36//! - [`MemoryManager`] — page allocator and low-level read/write
37//!   helpers. See [`RESERVED_PAGES`] for the reserved layout.
38//! - [`SchemaRegistry`] — persistent table-schema store backed by
39//!   [`TableRegistryPage`].
40//! - [`TableRegistry`] — record-level storage, free-segment tracking,
41//!   and read iterators ([`TableReader`], [`RawTableReader`],
42//!   [`NextRecord`], [`RecordAddress`], [`RawRecordBytes`]).
43//! - [`IndexLedger`] / [`IndexTreeWalker`] — secondary index storage
44//!   and traversal.
45//! - [`table_registry::AutoincrementLedger`] — per-column
46//!   autoincrement counters.
47//! - [`UnclaimedPages`] — free page pool ([`UNCLAIMED_PAGES_CAPACITY`]
48//!   entries per ledger page).
49//! - [`align_up`] / [`WASM_PAGE_SIZE`] — alignment helpers.
50//!
51//! ## Memory layout
52//!
53//! Reserved pages followed by per-table page sets:
54//!
55//! ```text
56//! +0:  Schema Registry            (1 page)
57//! +1:  Unclaimed Pages Ledger     (1 page)
58//! +N:  Per-table Page Ledger      (1 page)
59//! +N:  Per-table Free Segments    (1 page)
60//! +N:  Per-table Record Pages     (grown on demand)
61//! ```
62//!
63//! ## Quick start
64//!
65//! ```rust
66//! use wasm_dbms_memory::prelude::*;
67//!
68//! let mut provider = HeapMemoryProvider::default();
69//! provider.grow(1).unwrap();
70//! provider.write(0, b"hello").unwrap();
71//!
72//! let mut buf = vec![0u8; 5];
73//! provider.read(0, &mut buf).unwrap();
74//! assert_eq!(&buf, b"hello");
75//! ```
76//!
77//! Most users do not interact with this crate directly: the
78//! [`wasm-dbms`](https://crates.io/crates/wasm-dbms) engine consumes a
79//! [`MemoryProvider`] and exposes the higher-level CRUD/transaction
80//! API on top.
81
82#![doc(html_playground_url = "https://play.rust-lang.org")]
83#![doc(
84    html_favicon_url = "https://raw.githubusercontent.com/veeso/wasm-dbms/main/assets/images/cargo/logo-128.png"
85)]
86#![doc(
87    html_logo_url = "https://raw.githubusercontent.com/veeso/wasm-dbms/main/assets/images/cargo/logo-512.png"
88)]
89
90extern crate self as wasm_dbms_memory;
91
92mod memory_access;
93mod memory_manager;
94mod provider;
95mod schema_registry;
96pub mod table_registry;
97mod unclaimed_pages;
98
99pub use self::memory_access::MemoryAccess;
100pub use self::memory_manager::{MemoryManager, RESERVED_PAGES, align_up};
101pub use self::provider::{HeapMemoryProvider, MemoryProvider, WASM_PAGE_SIZE};
102pub use self::schema_registry::{SchemaRegistry, TableRegistryPage};
103pub use self::table_registry::{
104    IndexLedger, IndexTreeWalker, NextRecord, RawRecordBytes, RawTableReader, RecordAddress,
105    TableReader, TableRegistry,
106};
107pub use self::unclaimed_pages::{UNCLAIMED_PAGES_CAPACITY, UnclaimedPages};
108
109/// Prelude re-exports for convenient use.
110pub mod prelude {
111    pub use super::memory_access::MemoryAccess;
112    pub use super::memory_manager::{MemoryManager, RESERVED_PAGES, align_up};
113    pub use super::provider::{HeapMemoryProvider, MemoryProvider, WASM_PAGE_SIZE};
114    pub use super::schema_registry::{SchemaRegistry, TableRegistryPage};
115    pub use super::table_registry::{
116        AutoincrementLedger, IndexLedger, IndexTreeWalker, NextRecord, RawRecordBytes,
117        RawTableReader, RecordAddress, TableReader, TableRegistry,
118    };
119    pub use super::unclaimed_pages::{UNCLAIMED_PAGES_CAPACITY, UnclaimedPages};
120}
wasm_dbms_memory/lib.rs

wasm_dbms_memory/
lib.rs
