wasm-dbms-memory 0.11.0

Memory abstraction and page management for the wasm-dbms framework
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120

// Rust guideline compliant 2026-04-28
// X-WHERE-CLAUSE, M-CANONICAL-DOCS

#![crate_name = "wasm_dbms_memory"]
#![crate_type = "lib"]
#![cfg_attr(docsrs, feature(doc_cfg))]
#![deny(clippy::print_stdout)]
#![deny(clippy::print_stderr)]

//! # wasm-dbms-memory
//!
//! Runtime-agnostic memory abstraction and page management for the
//! [`wasm-dbms`](https://crates.io/crates/wasm-dbms) framework.
//!
//! This crate sits between the raw byte storage exposed by a WASM
//! runtime (heap, file, IC stable memory, ...) and the higher-level
//! DBMS engine. It defines the [`MemoryProvider`] trait that abstracts
//! over the storage backend and the on-top-of-it data structures that
//! the engine uses to persist tables, schema, and indexes.
//!
//! All structures use 64 KiB pages so the on-disk layout is byte-for-byte
//! identical across providers — a heap-built database can be dumped and
//! reopened as IC stable memory or a WASI file with no conversion.
//!
//! ## What this crate provides
//!
//! Storage backends:
//!
//! - [`MemoryProvider`] — trait every backend implements (read, write,
//!   grow, page count).
//! - [`HeapMemoryProvider`] — in-memory provider for tests and embedded
//!   use cases.
//!
//! Engine-facing data structures:
//!
//! - [`MemoryManager`] — page allocator and low-level read/write
//!   helpers. See [`RESERVED_PAGES`] for the reserved layout.
//! - [`SchemaRegistry`] — persistent table-schema store backed by
//!   [`TableRegistryPage`].
//! - [`TableRegistry`] — record-level storage, free-segment tracking,
//!   and read iterators ([`TableReader`], [`RawTableReader`],
//!   [`NextRecord`], [`RecordAddress`], [`RawRecordBytes`]).
//! - [`IndexLedger`] / [`IndexTreeWalker`] — secondary index storage
//!   and traversal.
//! - [`table_registry::AutoincrementLedger`] — per-column
//!   autoincrement counters.
//! - [`UnclaimedPages`] — free page pool ([`UNCLAIMED_PAGES_CAPACITY`]
//!   entries per ledger page).
//! - [`align_up`] / [`WASM_PAGE_SIZE`] — alignment helpers.
//!
//! ## Memory layout
//!
//! Reserved pages followed by per-table page sets:
//!
//! ```text
//! +0:  Schema Registry            (1 page)
//! +1:  Unclaimed Pages Ledger     (1 page)
//! +N:  Per-table Page Ledger      (1 page)
//! +N:  Per-table Free Segments    (1 page)
//! +N:  Per-table Record Pages     (grown on demand)
//! ```
//!
//! ## Quick start
//!
//! ```rust
//! use wasm_dbms_memory::prelude::*;
//!
//! let mut provider = HeapMemoryProvider::default();
//! provider.grow(1).unwrap();
//! provider.write(0, b"hello").unwrap();
//!
//! let mut buf = vec![0u8; 5];
//! provider.read(0, &mut buf).unwrap();
//! assert_eq!(&buf, b"hello");
//! ```
//!
//! Most users do not interact with this crate directly: the
//! [`wasm-dbms`](https://crates.io/crates/wasm-dbms) engine consumes a
//! [`MemoryProvider`] and exposes the higher-level CRUD/transaction
//! API on top.

#![doc(html_playground_url = "https://play.rust-lang.org")]
#![doc(
    html_favicon_url = "https://raw.githubusercontent.com/veeso/wasm-dbms/main/assets/images/cargo/logo-128.png"
)]
#![doc(
    html_logo_url = "https://raw.githubusercontent.com/veeso/wasm-dbms/main/assets/images/cargo/logo-512.png"
)]

extern crate self as wasm_dbms_memory;

mod memory_access;
mod memory_manager;
mod provider;
mod schema_registry;
pub mod table_registry;
mod unclaimed_pages;

pub use self::memory_access::MemoryAccess;
pub use self::memory_manager::{MemoryManager, RESERVED_PAGES, align_up};
pub use self::provider::{HeapMemoryProvider, MemoryProvider, WASM_PAGE_SIZE};
pub use self::schema_registry::{SchemaRegistry, TableRegistryPage};
pub use self::table_registry::{
    IndexLedger, IndexTreeWalker, NextRecord, RawRecordBytes, RawTableReader, RecordAddress,
    TableReader, TableRegistry,
};
pub use self::unclaimed_pages::{UNCLAIMED_PAGES_CAPACITY, UnclaimedPages};

/// Prelude re-exports for convenient use.
pub mod prelude {
    pub use super::memory_access::MemoryAccess;
    pub use super::memory_manager::{MemoryManager, RESERVED_PAGES, align_up};
    pub use super::provider::{HeapMemoryProvider, MemoryProvider, WASM_PAGE_SIZE};
    pub use super::schema_registry::{SchemaRegistry, TableRegistryPage};
    pub use super::table_registry::{
        AutoincrementLedger, IndexLedger, IndexTreeWalker, NextRecord, RawRecordBytes,
        RawTableReader, RecordAddress, TableReader, TableRegistry,
    };
    pub use super::unclaimed_pages::{UNCLAIMED_PAGES_CAPACITY, UnclaimedPages};
}