feat: introduce closure-based transaction API

See CHANGELOG.md for more information

Author: abbycin

.github/workflows/ci.yml

@@ -2,9 +2,9 @@ name: Cross-platform CI
 
 on:
   push:
-    branches: [ main, master ]
+    branches: [ master ]
   pull_request:
-    branches: [ main, master ]
+    branches: [ master ]
 
 env:
   CARGO_TERM_COLOR: always

CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+All notable changes to the **btree_store** project will be documented in this file.
+
+## [0.1.1] - 2026-01-18
+
+### Added
+- **Atomic Multi-Bucket Transactions**: Introduced `exec_multi` API and `MultiTxn` handle. This allows performing multiple operations across different buckets in a single atomic transaction with only one disk sync, significantly improving batch performance.
+- **Enhanced Data Validation**: Reinforced `Node::validate` with physical invariant checks.
+- **Torn Write Detection**: Enhanced `MetaNode::validate` to identify and reject zeroed-out blocks caused by power failures during I/O.
+- **8-Byte Memory Alignment**: Guaranteed alignment for zero-copy serialization via `AlignedPage`.
+
+### Changed
+- **Closure-based Transaction API**: Introduced `exec` and `view` methods.
+- **Unified Reclamation**: Consolidated page release via `Store::free_pages`.
+- **Log Management**: Switched to `.pending` log truncation (`set_len(0)`).
+- **Auto-Refresh**: Implicit superblock sync at transaction start.
+- **API Simplification**: Continued the transition to closure-based APIs across all internal and external logic.
+- **Shared Transaction State**: Clones share `pending` containers within the same process.
+
+### Fixed
+- **Double-Write Protocol**: Refined the superblock update sequence to guarantee zero-leak and zero-corruption recovery by splitting the commit into two distinct disk-sync phases.

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "btree-store"
-version = "0.1.0"
+version = "0.1.1"
 edition = "2024"
 authors = ["AbbyCin <abbytsing@gmail.com>"]
 readme = "README.md"

README.md

@@ -1,57 +1,70 @@
 # btree_store
 
-**btree_store** is a high-performance, persistent, embedded key-value storage engine written in Rust. It implements a robust Copy-On-Write (COW) B-Tree architecture to ensure data integrity, crash safety, and efficient concurrent access.
+**btree_store** is a persistent, embedded key-value storage engine written in Rust. It implements a robust Copy-On-Write (COW) B-Tree architecture to ensure data integrity, crash safety, and efficient concurrent access.
 
 ## Features
 
 *   **ACID Compliance:** Atomic commits using COW, Snapshot Isolation, and double-buffered meta pages.
-*   **Conflict Detection:** Built-in "First-Committer-Wins" strategy ensures data integrity in multi-process environments.
-*   **Crash Safety:** A dedicated `.pending` log recovery mechanism reclaims leaked pages from interrupted transactions.
-*   **Buckets:** Logical namespaces for data separation within a single database file.
-*   **Zero-Allocation Iterators:** High-performance iterators returning `(&[u8], &[u8])` with internal buffer reuse.
-*   **Efficient Concurrency:** Shared bucket handles and Snapshot Isolation (SI) using `parking_lot` for scalable access.
-*   **Data Integrity:** Full CRC32C checksum validation for every page (nodes, meta, and free lists).
-*   **Zero External Dependencies:** Core engine built using native Rust standard library.
+*   **Closure-based Transactions:** Simplified `exec` (read-write) and `view` (read-only) APIs with automatic commit and rollback.
+*   **Auto-Refresh:** Every transaction automatically starts from the freshest disk state. No manual snapshot management required.
+*   **Conflict Detection:** Built-in "First-Committer-Wins" strategy for concurrent handles.
+*   **Batch Operations:** `exec_multi` for atomic updates across multiple buckets with a single disk sync, significantly reducing I/O overhead.
+*   **Crash Safety:** Double-write superblock updates and a `.pending` log recovery mechanism ensure zero-leak recovery even from torn writes.
+*   **Logical Namespaces:** Direct support for multiple buckets within a single database file.
+*   **Zero-Copy Access:** 8-byte aligned memory layouts allow direct pointer-to-reference conversion for maximum performance.
+*   **Robust Data Integrity:** Strengthened physical invariant checks and CRC32C checksum validation for every node and metadata page.
+*   **Shared Transaction State:** `clone()` creates a new handle that shares the same transaction context, optimized for multi-threaded components.
+
+> **Warning:** Multi-process concurrent access is NOT supported. Only one process should access the database file at a time.
 
 ## Architecture
 
-*   **Store (`src/store.rs`):** Low-level page management, sharded LRU caching, and positional I/O.
-*   **Node (`src/node.rs`):** B-Tree node serialization, splitting, compacting, and checksumming.
-*   **Tree (`src/lib.rs`):** Core B+ Tree algorithms and Snapshot Isolation logic.
-*   **Bucket (`src/lib.rs`):** High-level API with shared handle caching.
+*   **Store (`src/store.rs`):** Low-level page management, sharded LRU caching with mandatory invalidation on sync, and positional I/O.
+*   **Node (`src/node.rs`):** 8-byte aligned memory management (`AlignedPage`), zero-copy serialization, and checksumming.
+*   **Tree Logic (`src/lib.rs`):** Core B+ Tree algorithms and Transactional Snapshot Isolation logic.
 
 ## Usage
 
 Add this to your `Cargo.toml`:
 
 ```toml
 [dependencies]
-btree-store = "0.1.0"
+btree-store = "0.1.1"
 ```
 
-### Basic Example (with Conflict Handling)
+### Basic Example
 
 ```rust
 use btree_store::{BTree, Error};
 
 fn main() -> Result<(), Error> {
     let db = BTree::open("data.db")?;
-    let bucket = db.get_bucket("users").or_else(|_| db.new_bucket("users"))?;
-
-    loop {
-        // Perform operations
-        bucket.put(b"id:100", b"Alice")?;
-
-        // Commit changes
-        match db.commit() {
-            Ok(_) => break,
-            Err(Error::Conflict) => {
-                // Another instance committed first, refresh and retry
-                db.refresh()?;
-            }
-            Err(e) => return Err(e),
-        }
-    }
+
+    // Read-Write Transaction
+    db.exec("users", |txn| {
+        txn.put(b"id:100", b"Alice")?;
+        let val = txn.get(b"id:100")?;
+        assert_eq!(val, b"Alice");
+        Ok(())
+    })?;
+
+    // Read-Only View
+    db.view("users", |txn| {
+        let val = txn.get(b"id:100")?;
+        println!("User: {:?}", String::from_utf8_lossy(&val));
+        Ok(())
+    })?;
+
+    // Multi-Bucket Atomic Transaction
+    db.exec_multi(|multi| {
+        multi.execute("users", |txn| {
+            txn.put(b"id:101", b"Bob")
+        })?;
+        multi.execute("stats", |txn| {
+            txn.put(b"total_users", b"2")
+        })?;
+        Ok(())
+    })?;
 
     Ok(())
 }
@@ -60,18 +73,17 @@ fn main() -> Result<(), Error> {
 ## Performance Design
 
 The engine is optimized for high-throughput scenarios:
-*   **Snapshot Isolation (SI)** allows concurrent readers and writers to operate without blocking each other.
-*   **Bucket Handle Caching** ensures all threads share the same metadata locks, preventing structural corruption.
-*   **Cursor-based path traversal** avoids redundant tree searches.
-*   **RAII CommitContext** ensures zero-leak automatic rollbacks on failure.
-*   **Transmute-based lifetime extension** in iterators allows returning direct references to internal buffers under a read lock.
+*   **8-Byte Alignment:** Every page is allocated with 8-byte alignment, allowing direct casting of raw bytes to internal structures without memory copies.
+*   **Snapshot Isolation (SI):** Readers and writers operate on stable snapshots without blocking each other (non-blocking reads).
+*   **Automatic Page Reclamation:** Failed or conflicted transactions automatically trigger page reclamation to prevent database bloat.
+*   **Transmute-based lifetime extension:** Iterators return direct references to internal buffers under a read lock, achieving near-zero allocation.
 
 ## Testing
 
 The project includes a comprehensive suite of integration tests:
 *   `smo_stress_test`: Structural Modification Operations under heavy load.
 *   `crash_safety_tests`: Verifies data integrity across simulated crashes.
-*   `concurrency_tests`: Parallel readers and writers.
+*   `concurrency_tests`: Parallel readers and writers with auto-refresh validation.
 *   `leak_safety_tests`: Ensures no pages are lost during failed operations.
 
 Run tests with:
@@ -81,4 +93,4 @@ cargo test
 
 ## License
 
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.