Crate holt 

holt — adaptive radix tree metadata storage engine

holt is an embedded Rust library that stores path-shaped metadata with sub-microsecond lookups, per-blob concurrency, and crash-safe persistence. It is built around an Adaptive Radix Tree that spans multiple 512 KB blob frames.

See README.md for the elevator pitch and ARCHITECTURE.md for the deep dive.

Current status

All core layers — layout, walker (insert / lookup / erase / range / spillover / compact / merge), persistent store (O_DIRECT + optional io_uring), WAL with replay, sharded buffer manager, background checkpointer — are in place and covered by integration + property tests. See ROADMAP.md for the post-0.3 direction.

Quick taste

use holt::{RangeEntry, TreeBuilder};

let tree = TreeBuilder::new("/var/lib/myapp/meta.holt").open()?;
tree.put(b"img/01.jpg", b"rgb_data")?;
let v: Vec<u8> = tree.get(b"img/01.jpg")?.unwrap();
for entry in tree.scan(b"img/").into_iter().take(10) {
    if let RangeEntry::Key { key, value, .. } = entry? {
        println!("{key:?} -> {value:?}");
    }
}

Module map

The supported import surface is the flat crate root: Tree, TreeBuilder, AtomicBatch, Record, RecordVersion, View, range iterator types, stats snapshots, and the optional metrics renderer.

All implementation modules are crate-private. This keeps the on-disk format, WAL codec, walker, and buffer-manager internals free to change in minor releases without breaking downstream code.

Internal modules (pub(crate), not part of the SemVer surface):

• layout — extern struct layouts (BlobHeader, SlotEntry, per-NodeType bodies). Pinned at compile time via const _: () = assert!(...) blocks per file.
• journal — WAL codec + replay scanner + writer.
• store — buffer manager + blob-frame allocator + store trait machinery. The supported store surface (BlobStore, MemoryBlobStore, FileBlobStore, AlignedBlobBuf) is re-exported at the crate root for users who want to plug in a custom store.
• engine — recursive walker (insert / lookup / erase / scan / rename / compact). Record and key-only range iterator types and stats snapshots are re-exported at the crate root.
• concurrency — HybridLatch 3-mode lock plus the tree-wide maintenance gate.
• checkpoint — 3-thread background checkpointer. Users opt in via CheckpointConfig.

Platform support

holt is Unix-only by design: Linux (O_DIRECT fast path, io_uring on the file store) and macOS (F_NOCACHE). Windows is out of scope and the crate refuses to compile there — see the platform stance in ROADMAP.md.

Structs

AlignedBlobBuf

A heap-allocated, 4 KB-aligned, PAGE_SIZE-byte buffer.

AtomicBatch

Builder for an atomic batch. See super::tree::Tree::atomic.

BlobStats

Per-blob counters captured by Tree::stats.

CheckpointConfig

Background checkpointer policy + cadence.

CheckpointerStats

Snapshot of the background checkpointer’s accumulated counters. Returned inside TreeStats::checkpointer when the thread group is enabled. All counters are cumulative since the threads were spawned.

FileBlobStore

NVMe-backed, O_DIRECT, single-packed-file blob store.

JournalStats

Snapshot of the WAL group-commit worker’s counters.

KeyRangeBuilder

Builder produced by crate::Tree::range_keys.

KeyRangeIter

Active key-only iteration state — see KeyRangeBuilder::into_iter.

MemoryBlobStore

Concurrent in-memory blob store.

RangeBuilder

Builder produced by crate::Tree::range.

RangeIter

Active iteration state — see RangeBuilder::into_iter.

Record

Value plus the live record version observed by one lookup.

RecordVersion

Opaque per-record version returned by Tree::get_version.

RouteCacheStats

Root-route-cache counters captured by Tree::stats.

Tree

An holt tree — your handle to one metadata store.

TreeBuilder

Fluent constructor for Tree.

TreeConfig

Configuration passed to crate::Tree::open.

TreeStats

Tree-wide aggregate counters from Tree::stats.

View

Immutable read transaction over one captured prefix.

ViewKeyRangeBuilder

Key-only range builder scoped to a View.

ViewRangeBuilder

Record range builder scoped to a View.

Enums

Error

Top-level error type covering the union of every failure mode.

KeyRangeEntry

An entry yielded by KeyRangeIter.

KeyRangeEntryRef

Borrowed key-only range entry passed to KeyRangeBuilder::visit.

RangeEntry

An entry yielded by RangeIter.

Storage

Where the tree’s data lives.

WalCommit

Commit acknowledgement boundary for file-backed WAL writes.

Traits

BlobStore

A blob-granular storage interface.

Type Aliases

BlobGuid

128-bit blob identifier (stored as 16 bytes).

Result

Result alias used throughout the crate.