Struct ZeroTree 

pub struct ZeroTree<K: Key, const V: usize, D: Durability = Bitcask, T: Copy = [u8; V], H: TypedWriteHook<K, T> = NoHook> { /* private fields */ }

A tree with fixed-size keys and zerocopy-compatible values.

Thin wrapper around ConstTree<K, V, D> that provides a typed API for values implementing [FromBytes] + [IntoBytes] + [Immutable]. Conversions are zero-cost — values are transmuted without serialization.

Generic over D: Durability (default: Bitcask). Use Fixed backend for frequent updates without compaction: ZeroTree::<K, V, Fixed, T>::open(...).

Requires size_of::<T>() == V (compile-time assertion in constructor).

Write hooks

Uses TypedWriteHook<K, T> — the hook receives &T directly (not raw bytes). on_write fires on put/insert/delete/cas/update. Does not fire inside atomic(). Old value is always provided (it lives in memory) — NEEDS_OLD_VALUE is ignored.

on_init fires once per live entry during migrate() or replay_init() (enable via NEEDS_INIT = true).

When to use

For T with trivial representation (no heap allocations, fixed layout): structs with #[derive(FromBytes, IntoBytes, Immutable, KnownLayout)]. All values live in memory — reads never touch disk.

For complex types (String, Vec, nested structs) use TypedTree instead.

Usage

use zerocopy::{FromBytes, IntoBytes, Immutable, KnownLayout};

#[derive(FromBytes, IntoBytes, Immutable, KnownLayout, Clone, Copy)]
#[repr(C)]
struct Counters {
    views: u64,
    likes: u64,
}

let tree = ZeroTree::<[u8; 16], { size_of::<Counters>() }, Counters>::open(
    "data/counters",
    Config::default(),
)?;
tree.put(&key, &Counters { views: 1, likes: 0 })?;
if let Some(c) = tree.get(&key) {
    println!("views: {}", c.views);
}

Iteration

iter(), range(), and prefix_iter() return ZeroIter which implements Iterator + DoubleEndedIterator with Item = (K, T).

Implementations

impl<K: Key, const V: usize, T: Copy> ZeroTree<K, V, Bitcask, T>

pub fn open(path: impl AsRef<Path>, config: Config) -> DbResult<Self>

Open or create a ZeroTree at the given path. Recovers the index from existing data files on disk.

impl<K: Key, const V: usize, T: Copy, H: TypedWriteHook<K, T>> ZeroTree<K, V, Bitcask, T, H>

pub fn open_hooked( path: impl AsRef<Path>, config: Config, hook: H, ) -> DbResult<Self>

Open or create a ZeroTree with a write hook for secondary index maintenance.

pub fn close(self) -> DbResult<()>

Graceful shutdown: write hint files, flush write buffers + fsync.

pub fn flush_buffers(&self) -> DbResult<()>

Flush all shard write buffers to disk (without fsync).

pub fn config(&self) -> &Config

Get the database configuration.

pub fn compact(&self) -> DbResult<usize>

Trigger a compaction pass across all shards.

pub fn sync_hints(&self) -> DbResult<()>

Write hint files for all active shard files. Call during graceful shutdown.

pub fn migrate(&self, f: impl Fn(&K, &T) -> MigrateAction<T>) -> DbResult<usize>

Iterate all entries and optionally mutate them. Call once at startup.

The callback receives each (key, &T) and returns MigrateAction:

• Keep — no change (fires on_init if NEEDS_INIT)
• Update(new_value) — replace value (hook-free write, fires on_init)
• Delete — remove entry (hook-free tombstone, no on_init)

on_write is never fired during migration. Returns the number of mutated entries.

pub fn as_inner(&self) -> &ConstTree<K, V, Bitcask, ZeroHookAdapter<K, T, H>>

Access the underlying ConstTree.

impl<K: Key, const V: usize, T: Copy> ZeroTree<K, V, Fixed, T>

pub fn open(path: impl AsRef<Path>, config: FixedConfig) -> DbResult<Self>

Open or create a ZeroTree with Fixed (fixed-slot) backend. Recovers the index from existing data files on disk.

impl<K: Key, const V: usize, T: Copy, H: TypedWriteHook<K, T>> ZeroTree<K, V, Fixed, T, H>

pub fn open_with_hook( path: impl AsRef<Path>, config: FixedConfig, hook: H, ) -> DbResult<Self>

Open or create a ZeroTree with a write hook, using Fixed (fixed-slot) backend.

pub fn close(self) -> DbResult<()>

Perform a clean shutdown (Fixed backend).

impl<K: Key, const V: usize, D: Durability, T: Copy, H: TypedWriteHook<K, T>> ZeroTree<K, V, D, T, H>

pub fn get(&self, key: &K) -> Option<T>

Get a value by key. Lock-free, zero disk I/O. Returns a copy of T.

pub fn get_or_err(&self, key: &K) -> DbResult<T>

Get a value by key, returning Err(KeyNotFound) if absent.

pub fn contains(&self, key: &K) -> bool

Check if a key exists.

pub fn first(&self) -> Option<(K, T)>

Return the first entry in index order, or None if empty. With reversed=true (default): the entry with the largest key. O(1) — follows head’s level-0 pointer.

pub fn last(&self) -> Option<(K, T)>

Return the last entry in index order, or None if empty. With reversed=true (default): the entry with the smallest key.

pub fn put(&self, key: &K, value: &T) -> DbResult<Option<T>>

Insert or update a key-value pair. Returns the old value if the key existed.

pub fn insert(&self, key: &K, value: &T) -> DbResult<()>

Insert a key-value pair only if the key does not exist. Returns Err(KeyExists) if the key is already present.

pub fn delete(&self, key: &K) -> DbResult<Option<T>>

Delete a key. Returns the old value if the key existed.

pub fn cas(&self, key: &K, expected: &T, new_value: &T) -> DbResult<()>

Compare-and-swap: if current value == expected, replace with new_value. Returns Ok(()) on success, Err(CasMismatch) if current != expected, Err(KeyNotFound) if key doesn’t exist.

pub fn update(&self, key: &K, f: impl FnOnce(&T) -> T) -> DbResult<Option<T>>

Atomically read-modify-write. Returns Some(T) (the new value) if key existed, None otherwise. The closure must not be heavy (shard lock is held).

pub fn fetch_update( &self, key: &K, f: impl FnOnce(&T) -> T, ) -> DbResult<Option<T>>

Like update(), but returns Some(T) with the old value.

pub fn atomic<R>( &self, shard_key: &K, f: impl FnOnce(&mut ZeroShard<'_, K, V, D, T>) -> DbResult<R>, ) -> DbResult<R>

Atomically execute multiple operations on a single shard. All keys must route to the same shard as shard_key. The closure must be short — shard lock is held for its duration.

pub fn prefix_iter(&self, prefix: &[u8]) -> ZeroIter<'_, K, V, D::Loc, T>

Iterate entries whose keys start with prefix.

reversed=true (default): yields matching keys in DESC order. next() is O(1), next_back() is O(log n).

pub fn iter(&self) -> ZeroIter<'_, K, V, D::Loc, T>

Iterate all entries in index order.

reversed=true (default): DESC. reversed=false: ASC. next() is O(1), next_back() is O(log n).

pub fn range(&self, start: &K, end: &K) -> ZeroIter<'_, K, V, D::Loc, T>

Iterate entries in [start, end) — start inclusive, end exclusive.

reversed=true (default): DESC within range. reversed=false: ASC. next() is O(1), next_back() is O(log n).

pub fn range_bounds( &self, start: Bound<&K>, end: Bound<&K>, ) -> ZeroIter<'_, K, V, D::Loc, T>

Iterate entries in range defined by start and end bounds.

Unlike range(), allows Included, Excluded, or Unbounded for each bound independently.

reversed=true (default): DESC within range. reversed=false: ASC. next() is O(1), next_back() is O(log n).

pub fn len(&self) -> usize

pub fn is_empty(&self) -> bool

pub fn shard_for(&self, key: &K) -> usize

pub fn flush(&self) -> DbResult<()>

Flush all shard data to disk.

Trait Implementations

impl<T, const V: usize, H> Collection for ZeroTree<T::SelfId, V, Bitcask, T, H>

where T: CollectionMeta + Copy + Send + Sync, H: TypedWriteHook<T::SelfId, T>, T::SelfId: Key + Ord,

Available on crate feature armour only.

fn name(&self) -> &str

Collection name (from CollectionMeta::NAME).

fn len(&self) -> usize

Number of entries in the collection.

fn compact(&self) -> DbResult<usize>

Run a compaction pass across all shards.

fn is_empty(&self) -> bool

impl<K: Key, const V: usize, T: Copy + Send + Sync, H: TypedWriteHook<K, T>> CompactionIndex<K> for ZeroTree<K, V, Bitcask, T, H>

fn update_if_match(&self, key: &K, old_loc: DiskLoc, new_loc: DiskLoc) -> bool

If the current index points to old_loc, it is updated to new_loc and returns true.

fn contains_key(&self, key: &K) -> bool

Returns true if the key currently exists in the index (i.e. has a live Put).

fn invalidate_blocks(&self, _shard_id: u8, _file_id: u32, _total_bytes: u64)

Invalidate cached blocks for a file after compaction replaces its contents.