Crate armdb

Expand description

Embedded key-value storage engine optimized for NVMe.

Single process, multi-threaded. Sync read/write API. Each tree/map owns its storage — one tree = one database directory.

§Durability backends

Collections are generic over D: Durability (default: Bitcask):

Bitcask — append-only log + compaction. Good for general workloads.
FixedStore (Fixed) — fixed-slot pwrite, no compaction. Optimized for frequent updates of fixed-size values (counters, metrics, sessions).

FixedTree and FixedMap are type aliases for ConstTree<K, V, Fixed> and ConstMap<K, V, Fixed>. ZeroTree and ZeroMap also accept Fixed as backend.

§Collection types

Type	Index	Values	Ordered	FixedStore	Feature
`ConstTree`	SkipList	inline `[u8; V]`	yes	yes	(default)
`ConstMap`	HashMap	inline `[u8; V]`	no	yes	(default)
`TypedTree`	SkipList	typed `T` (in-memory, `TypedRef`)	yes	no	`typed-tree`
`TypedMap`	HashMap	typed `T` (in-memory, `TypedRef`)	no	no	`typed-tree`
`ZeroTree`	SkipList	zerocopy `T` (in-memory)	yes	yes	`typed-tree`
`ZeroMap`	HashMap	zerocopy `T` (in-memory)	no	yes	`typed-tree`
`VarTree`	SkipList	`ByteView` (disk + cache)	yes	no	`var-collections`
`VarMap`	HashMap	`ByteView` (disk + cache)	no	no	`var-collections`
`VarTypedTree`	SkipList	typed `T` (disk + cache)	yes	no	`typed-tree` + `var-collections`
`VarTypedMap`	HashMap	typed `T` (disk + cache)	no	no	`typed-tree` + `var-collections`

§Usage

// Bitcask backend (default)
let tree = ConstTree::<[u8; 16], 64>::open("data/users", Config::balanced().build())?;

// FixedStore backend
let tree = FixedTree::<[u8; 16], 64>::open("data/counters", FixedConfig::balanced().build())?;

tree.put(&key, &value)?;
let val = tree.get(&key);
tree.close()?;

§Durability

§Bitcask

Writes are buffered in memory (write_buffer_size per shard, default 1 MB). put() returns as soon as the entry is copied into the buffer and the in-memory index is updated — no disk I/O on the write path.

This means unflushed data is lost on crash. To control durability:

flush_buffers() — flush write buffers to disk (no fsync)
close() — flush + fsync + write hint files

§FixedStore

Each put() does a pwrite through the page cache (~200ns). fdatasync is called in batches (configurable interval/count), after releasing the shard lock. With enable_fsync = true, an additional per-write fdatasync runs inside the shard lock for immediate durability. No compaction, no write amplification, 1x space usage.

§Thread safety

All tree/map types are Send + Sync. Share via Arc for concurrent access:

let tree = Arc::new(ConstTree::<[u8; 8], 8>::open("data/mydb", Config::balanced().build())?);
let t = tree.clone();
std::thread::spawn(move || { t.put(&key, &value).unwrap(); });

Reads:

ConstTree / ZeroTree / TypedTree — lock-free: the index is a lock-free SkipList (TypedTree resolves the value through a seize RCU guard, no mutex).
VarTree — lock-free SkipList lookup; on a block-cache miss a brief shard lock fetches the file handles, then the pread runs outside the lock.
ConstMap / ZeroMap / TypedMap — a brief per-shard mutex guards the HashMap index. Values are inline for Const/Zero; TypedMap reads a pointer under the lock, then accesses the value lock-free via a seize guard.
VarMap / VarTypedMap — brief per-shard mutex on the index; a pread on a cache miss runs outside the lock.

Writes acquire the target key’s per-shard mutex (write buffer + index update), so writes to different shards never contend on the buffer or durability I/O. Tree writes additionally link the new node into the shared SkipList under its internal linking lock — briefly contended across shards, but the critical section is O(node height), not the full O(log n) search.

§Encryption at rest (feature `encryption`)

Page-level AES-256-GCM encryption. Key from env or direct config:

let key = PageCipher::key_from_env("ARMDB_KEY")?;
let config = Config::balanced().encryption_key(Some(key)).build();
let tree = ConstTree::<[u8; 16], 64>::open("data/encrypted", config)?;
// all data is transparently encrypted on disk

§Write hooks (secondary indexes)

Generic WriteHook<K> / TypedWriteHook<K, T> parameter for synchronous write and init notifications. Zero overhead when unused (NoHook default).

on_write — fires on every put/insert/delete/cas/compare_delete/update/fetch_update, including mutations inside atomic() (buffered under the shard lock and replayed once it is released, in application order). If the closure returns Err, hooks still fire for operations that were applied. On Const*/Zero* collections replay happens after the sync()? seam; Var/Typed collections have no per-write sync.
on_init — fires once per live entry during collection open (after recovery). Enable via NEEDS_INIT = true. See [armdb/docs/hooks.md] for details.
NEEDS_OLD_VALUE — only affects VarTree/VarMap (skips disk I/O for old value when false). In-memory collections (Const/Typed/Zero) always provide the old value at zero cost.

impl WriteHook<[u8; 16]> for MyIndex {
    const NEEDS_OLD_VALUE: bool = true;
    const NEEDS_INIT: bool = true;

    fn on_write(&self, key: &[u8; 16], old: Option<&[u8]>, new: Option<&[u8]>) {
        // update secondary index incrementally
    }

    fn on_init(&self, key: &[u8; 16], value: &[u8]) {
        // populate secondary index at startup
    }
}

let tree = ConstTree::<[u8; 16], 64, MyIndex>::open_hooked("data/indexed", config, my_index)?;
tree.migrate(|_, _| MigrateAction::Keep)?; // triggers on_init for all entries

§Compaction

Compaction is not automatic. Dead bytes accumulate as entries are overwritten or deleted. Use Compactor to run it in the background:

use std::sync::Arc;
use std::time::Duration;

let tree = Arc::new(ConstTree::<[u8; 16], 64>::open("data/mydb", Config::balanced().build())?);
let t = tree.clone();
let _compactor = Compactor::start(move || t.compact(), Duration::from_secs(60));

Or call tree.compact() manually when needed.

§Iteration

All Tree types provide iter(), range(), and prefix_iter() methods. Map types (HashMap index) do not support iteration.

Each method returns a dedicated iterator implementing Iterator + DoubleEndedIterator:

Tree	Iterator	Item
`ConstTree`	`ConstIter`	`(K, [u8; V])` — copy
`VarTree`	`VarIter`	`(K, ByteView)` — RC, possible disk I/O
`TypedTree`	`TypedIter`	`(K, TypedRef<T>)` — guard-protected reference, zero I/O
`ZeroTree`	`ZeroIter`	`(K, T)` — copy, zero I/O

Method	Description
`iter()`	All entries in index order
`range(start, end)`	Entries in `[start, end)` — start inclusive, end exclusive
`range_bounds(start, end)`	Entries with custom `Bound` — `Included`, `Excluded`, or `Unbounded`
`prefix_iter(prefix)`	Entries whose key starts with `prefix`

for (key, value) in tree.iter() { /* ... */ }

let latest = tree.prefix_iter(&user_id).take(20).collect::<Vec<_>>();

for (key, value) in tree.range(&start_key, &end_key) { /* ... */ }

// Custom bounds: (5, 10] — exclude 5, include 10
use std::ops::Bound;
let entries: Vec<_> = tree.range_bounds(
    Bound::Excluded(&5u64.to_be_bytes()),
    Bound::Included(&10u64.to_be_bytes()),
).collect();

// DoubleEndedIterator — .rev() or .next_back()
let oldest = tree.prefix_iter(&user_id).rev().take(10);

// TypedTree only: cheap scan — `&T` borrowed for the call, no per-row guard.
// `ControlFlow::Break` stops early.
tree.range(&start_key, &end_key).for_each_ref(|key, value| {
    std::ops::ControlFlow::Continue(())
});

§Complexity

Operation	Complexity	Notes
`next()`	O(1)	follows SkipList level-0 forward pointer
`next_back()`	first step: expected O(log n); an m-row reverse walk: expected/amortized O(log n + m)	resumes a read-only SkipList predecessor staircase; a fresh iterator still seeks from the top
`iter()` / `range()` / `prefix_iter()` setup	O(log n)	initial SkipList search

The reverse bound follows the geometric p = 0.25 tower distribution; an all-height-1 topology can fall back to the old search cost.

VarIter: both next() and next_back() may additionally perform a pread on block-cache miss. Use warmup() to pre-populate the cache.

§Weakly-consistent semantics

Iterators do not create a snapshot. They are weakly-consistent:

Concurrent inserts/updates may be visible during iteration
Deleted entries (marked nodes) are automatically skipped
The seize guard prevents memory reclamation for the lifetime of the iterator — no use-after-free, but the index is not frozen

§Ordering: `Config::reversed`

Config::reversed controls the SkipList comparator direction.

`reversed`	`iter()` / `prefix_iter()`	`.rev()` / `next_back()`
`true` (default)	DESC (newest first)	ASC (oldest first)
`false`	ASC (oldest first)	DESC (newest first)

// reversed=true (default) — DESC: идеально для "newest first" пагинации
let tree = ConstTree::<[u8; 16], 64>::open("data/posts", Config::balanced().build())?;
let latest = tree.prefix_iter(&user_id).take(20);    // newest 20
let oldest = tree.prefix_iter(&user_id).rev().take(5); // oldest 5

// reversed=false — ASC: естественный порядок ключей
let config = Config::balanced().reversed(false).build();
let tree = ConstTree::<[u8; 16], 64>::open("data/logs", config)?;
for (key, value) in tree.iter() { /* ascending order */ }

Keys are stored on disk as-is. reversed can be changed between restarts without migration — it only affects in-memory index ordering.

FixedStore collections take the same knob via FixedConfig::reversed (default true → DESC); it behaves identically and is likewise in-memory only.

§Prefix sharding

let config = Config::balanced().shard_prefix_bits(32).build();
let tree = ConstTree::<[u8; 16], 64>::open("data/users", config)?;

§Caveats

Iterators are weakly-consistent, not snapshot. Concurrent inserts and updates may be visible during iteration. Deleted entries are skipped. The seize guard prevents use-after-free but does not freeze the index.
CAS/update holds shard lock during possible disk I/O. VarTree::cas, VarTree::update, VarMap::cas, and VarMap::update read the current value under the shard mutex. On a block-cache miss this issues a pread — blocking all writes to that shard until the read completes. Pre-warm the cache or size it to cover the working set.
migrate() on HashMap trees allocates O(keys/shards) memory. ConstMap::migrate and VarMap::migrate collect all shard keys into a Vec before iterating. For very large shards this causes a transient memory spike. SkipList trees (ConstTree, VarTree) are not affected.

§Shutdown

// 1. Stop background tasks first
compactor.stop();
// 2. Close the tree (writes hint files, flushes, fsyncs)
Arc::try_unwrap(tree).expect("no other references").close()?;

If close() is not called (e.g. the tree is dropped via Arc::drop), Shard::Drop still flushes write buffers, fsyncs, and writes hint files automatically — no data loss and no slow recovery on next startup.

§Layers above the core

The items above are the storage core. Everything built on top has its own entry point and its own document:

Layer	Entry point	Document
Named collections, migrations, background workers, RPC	`armour::Db`	`docs/armour.md`
Ranges, pages, bulk range operations	`collection.scope::<N>()`	`docs/iterators.md`
Decoded-value cache	`get_shared` on Var typed families	`docs/tuning.md`
Cross-collection transactions	`db.tx()`	`docs/transactions.md`
TTL	`TtlPolicy` / `TtlHook`	`docs/hooks.md`
Secondary indexes, counters, unique namespaces, change streams	`schema::SchemaRegistry`	`docs/schema-metadata.md`
Durable queues	`db.open_queue::<N>()`	`docs/queues.md`
Realtime watches	`WatchHook` + `watch()`	`docs/watch.md`

§Features

typed-tree — enables TypedTree, TypedMap, ZeroTree, ZeroMap, Codec and codec implementations
var-collections — enables VarTree, VarMap (variable-length values with LRU cache)
rapira-codec — RapiraCodec for rapira serialization (implies typed-tree)
bytemuck-codec — BytemuckCodec / BytemuckSliceCodec (implies typed-tree)
bitcode-codec — [BitcodeCodec] (implies typed-tree)
postcard-codec — PostcardCodec for postcard/serde serialization (implies typed-tree)
encryption — AES-256-GCM page-level encryption at rest
replication — two independent replication stacks behind one flag: leader/follower log-shipping for Bitcask collections (replication/) and event-based slot replication for FixedStore ones (fixed_replication/; catch-up is a full slot scan on reconnect, its cursor is diagnostics-only)
armour — integration with armour ecosystem: Db, schema-versioned migrations, binary RPC server (TCP/UDS). See armour module docs.
rpc — TCP/UDS RPC server (implies armour)
schema — relation metadata over collections: engine-maintained secondary indexes, counters, unique namespaces and change streams, plus the CI validator and Mermaid ER export (implies armour)
fjall — LsmTree, an fjall-backed collection for datasets larger than RAM (implies armour)
io-uring — io_uring flush-path backend (Linux only). Off by default: the default IoBackend is Pwrite
solana — Solana pubkey/signature key types (implies armour)
uuid — Uuid key type
id-cipher — enables armour-core/cipher (wire-level id encryption)
hot-path-tracing — per-operation tracing::trace! calls

recommended is a convenience bundle for applications that embed the engine and do not serve it over the network: it takes the default set minus rpc (and the armour-rpc/ctrlc dependencies behind it) and minus replication, and adds encryption. Use it with default-features = false.

Internal/test-only: parking_lot (default; without it a panic under a shard lock poisons that mutex — see libfunc/armour#154), loom, proptest, ctx-gates, test-faults, queue-test-support, bench-internals.

Re-exports§

pub use codec::Codec;
pub use codec::InspectionEncoding;
pub use codec::RapiraCodec;
pub use codec::ZerocopyCodec;
pub use codec::BytemuckCodec;
pub use codec::BytemuckSliceCodec;
pub use codec::BytemuckVec;
pub use compaction::Compactor;
pub use fixed::FixedConfig;
pub use fixed::FixedMap;
pub use fixed::FixedTree;
pub use fixed::FixedWorkload;
pub use armour_core;
pub use zerocopy;

Modules§

armour: Integration with the armour ecosystem (feature armour).
codec
compaction
docs: In-depth documentation for armdb.
durability: Durability trait — abstracts Bitcask (append-only log) and FixedStore (fixed-slot pwrite) backends behind a common interface.
fixed
fixed_replication: Replication for the FixedStore backend.
replication
schema: Schema metadata, relation registry, CI validator and ER export. Spec: docs/superpowers/specs/26-06-11-armdb-schema-metadata.md

Macros§

const_map: Expands to ConstMap<<V as CollectionMeta>::SelfId, { size_of::<V>() } [, H, D]>.
const_tree: Expands to ConstTree<<V as CollectionMeta>::SelfId, { size_of::<V>() } [, H, D]>.
format_step: Declare a typed value-format migration step.
impl_key_bytemuck: Implement Key for a type that derives bytemuck::{Pod, Zeroable}.
impl_key_zerocopy: Implement Key for a type that derives zerocopy::{FromBytes, IntoBytes, Immutable}.
queue: Declare a durable queue marker type.
typed_map: Expands to TypedMap<<V as CollectionMeta>::SelfId, V, C [, H]>.
typed_tree: Expands to TypedTree<<V as CollectionMeta>::SelfId, V, C [, H]>.
unique_index: Declare a unique namespace type: a #[repr(transparent)] newtype over UniqueRow carrying a CollectionMeta impl (TTL wired to the row’s own expires_at via UniqueRow::deadline) and UniqueNamespace.
var_map: Expands to VarMap<<V as CollectionMeta>::SelfId [, H]>.
var_tree: Expands to VarTree<<V as CollectionMeta>::SelfId [, H]>.
var_typed_map: Expands to VarTypedMap<<V as CollectionMeta>::SelfId, V, C [, H]>.
var_typed_tree: Expands to VarTypedTree<<V as CollectionMeta>::SelfId, V, C [, H]>.
zero_map: Expands to ZeroMap<<V as CollectionMeta>::SelfId, { size_of::<V>() }, V [, H, D]>.
zero_tree: Expands to ZeroTree<<V as CollectionMeta>::SelfId, { size_of::<V>() }, V [, H, D]>.

Structs§

ByteView: Immutable byte slice: inline up to 20 bytes, heap-allocated with reference counting for larger. Total size: 24 bytes on 64-bit systems, alignment: 8.
CacheConfig: Configuration for the value cache used by VarTree.
ChunkedPage: A page of projected items and the cursor for its continuation.
ClaimSink: Buffer + budgets + declared target table for one claim-projection evaluation. Mirrors crate::ProjectionSink in shape and in how it accounts its budget: one row, key.len() + size_of::<UniqueRow>() bytes per claim, against the same DbError::ProjectionBudgetExceeded.
CoalescedMerge: Iterator returned by MergeSorted::coalesce_equal.
Config: Database configuration.
ConstIter: Iterator over entries in a ConstTree. Returned by iter(), range(), and prefix_iter().
ConstMap: A map with fixed-size keys and values. All values are stored inline in a per-shard HashMap. Reads never touch disk — zero I/O reads. O(1) lookup instead of O(log n) SkipList. Ordered iteration is available when opened with Config::iterable(true) via iter_view; otherwise use ConstTree for prefix/range scans.
ConstMapIterView: View over an iterable ConstMap; exposes ordered iteration over (K, [u8; V]) entries and cheap keys-only iteration. Obtained via ConstMap::iter_view.
ConstMapKeyIter: Key-only iterator over an iterable ConstMap scan.
ConstMapRowIter: Row iterator over an iterable ConstMap scan.
ConstMapShard: Handle for atomic multi-key operations within a single shard. Obtained via ConstMap::atomic. The shard + index locks are held for the lifetime of this struct — keep the closure short.
ConstShard: Handle for atomic multi-key operations within a single shard. Obtained via ConstTree::atomic. The shard lock is held for the lifetime of this struct — keep the closure short.
ConstTree: A tree with fixed-size keys and values. All values are stored inline in SkipList nodes. Reads never touch disk — zero I/O reads.
ConstTreeKeyIter: Key-only iterator over a ConstTree scan.
ConstTreeRowIter: Row iterator over a ConstTree scan.
CounterSink: Buffer + budgets + declared target table for one source’s projection evaluation (mirrors crate::projection::ProjectionSink).
CounterTargets: A declared set of counter targets, built with CounterTargets::with_counter and CounterTargets::one_of.
EmitSink: Admission and buffering sink for one source transition.
FencedShard: A shard that owes an unapplied committed write.
FixedQueueMode: Marker selected by the default queue! declaration.
Flusher: Background periodic-flush handle. Stops and joins its thread on stop() or Drop.
FormatMigration: One declared value-format transition.
FormatMigrationReport: Summary returned by an explicit format migration run.
IndexTargets: Static participant set for one source declaration.
KeyPage: Keys-only pagination result, returned by keys_paginate. Carries no values, so it is cheap to produce even for VarMap/VarTypedMap (no off-disk read).
LeaseToken: Capability authorizing an acknowledgement or retry of one leased row.
LeasedEntry: A payload claimed by a successful lease operation.
MapKeyIter: Key-only iterator over an iterable TypedMap scan.
MapRowIter: Row iterator over an iterable TypedMap scan.
MapScan: Opaque Map scan view. No public constructor. V is typically &'a S: ShardSource.
MappedPage: One page of mapped rows returned by Scope::page_by.
MergeSorted: Lazily merges homogeneous sources that are already ordered for dir.
NoHook: Default no-op hook. All branches are eliminated at compile time.
OneOfBuilder: Builder for a one_of group — started by CounterTargets::one_of.
Page: One page of key/value entries returned by paginate.
PageSpec: Configuration for bounded pagination over prepared row chunks.
PendingProjection: Encoded index rows and counter deltas computed before apply. Index rows are safe to retry idempotently; counter deltas are not — re-applying a delta that already landed double-counts. apply_or_incomplete’s returned remainder always excludes whatever already applied, for both halves.
Progress: The result of one Scope::delete_up_to call.
Projected: Write-hook carrier for a projecting source: maintains secondary indexes (Task 8), engine-maintained counters (T9), and, since T10 Task 3, unique-namespace claims — a source may legitimately need any combination of the three, so this holds one target set + one projection closure per kind rather than requiring nested hooks.
ProjectionSink: Buffer + budgets + declared target table for one project evaluation.
Queue: Opaque handle to an engine-owned durable queue.
QueueConfig: Runtime policy for a durable queue.
QueueDue: Runtime-agnostic future that resolves once queue work can be leased.
QueueKey: Physical key for a queue header row, ordered by class, visibility, then id.
QueueStats: Read-only operational counters for one queue process lifetime.
QueueTargets: Declared destination queues for one source’s change stream.
RecvFuture: Future returned by WatchReceiver::recv.
Scope: Field-granular prefix / range / page builder. Opaque.
Selection: Result of selecting source operations for a transactional range deletion.
ShutdownSignal: Shared shutdown signal for coordinating graceful termination of background workers (compactor, replication, RPC).
SweepOutcome: Result of one TTL sweep pass on a collection.
SweepPassResult: Aggregated result of one worker tick across all collections.
Sweeper: Background periodic TTL sweep handle. Stops and joins its thread on stop() or Drop.
TreeKeyIter: Key-only iterator over a skiplist TypedTree scan.
TreeMeta: Metadata about a named tree/map collection.
TreeRowIter: Row iterator over a skiplist TypedTree scan.
TreeScan: Opaque Tree/LSM scan view. No public constructor.
TtlHook: Outermost hook installed by managed Db openers.
TtlPolicy: Compile-time TTL policy for a CollectionMeta type.
Tx
TxConfig: Configuration for crash-atomic multi-collection transactions.
TxScope: Arc-owned typed prefix/range builder for transactional deletion.
TypedCounterTarget: One declared counter: the target collection plus the application’s read (stored value -> counter) and apply (new count -> write decision) closures.
TypedIter: Iterator over entries in a TypedTree. Returned by iter(), range(), and prefix_iter().
TypedMap: A map with fixed-size keys and typed values T. Values are encoded via a Codec for disk persistence but stored as T in memory — reads never touch disk and return TypedRef<T> (guard-protected reference).
TypedMapIterView: View over an iterable TypedMap; exposes ordered iteration yielding guard-protected TypedRef values.
TypedMapShard: Handle for atomic multi-key operations within a single shard. Obtained via TypedMap::atomic. The shard + index locks are held for the lifetime of this struct — keep the closure short.
TypedRef: Guard-protected reference to a typed value inside a TypedTree.
TypedShard: Handle for atomic multi-key operations within a single shard. Obtained via TypedTree::atomic. The shard lock is held for the lifetime of this struct — keep the closure short.
TypedTree: A tree with fixed-size keys and typed values T. Values are encoded via a Codec for disk persistence but stored as T in memory — reads never touch disk and return TypedRef<T> (guard-protected reference).
UniqueIndex: A unique namespace: key -> owner, engine-owned rows, no public write API. See the module docs for why this is not a crate::ProjectableIndex.
UniqueOwner: Who holds a key: a source collection and its row key, plus the deadline when the hold is a reservation.
UniqueRow: The engine-owned value of every unique namespace row.
UniqueTargets: The set of unique namespaces one source may claim into, declared on a crate::schema-style registry before the source is opened. Mirrors crate::IndexTargets in shape: a small Vec of erased handles, looked up by UniqueIndex::name.
VarIter: Iterator over entries in a VarTree. Returned by iter(), range(), and prefix_iter().
VarMap
VarMapKeyIter: Key-only iterator over an iterable VarMap scan.
VarMapRowIter: Row iterator over an iterable VarMap scan.
VarMapShard: Handle for atomic multi-key operations within a single shard. Obtained via VarMap::atomic. The shard + index locks are held for the lifetime of this struct — keep the closure short.
VarQueueMode: Marker selected by the var queue! declaration.
VarShard: Handle for atomic multi-key operations within a single shard. Obtained via VarTree::atomic. The shard lock is held for the lifetime of this struct — keep the closure short.
VarTree: A tree with fixed-size keys and variable-length values. Values are stored as ByteView (inline ≤20 bytes, heap with ref counting for larger). Disk reads are cached at 4096-byte block granularity via BlockCache.
VarTreeKeyIter: Key-only iterator over a VarTree scan.
VarTreeRowIter: Row iterator over a VarTree scan.
VarTypedHookAdapter: Adapter: wraps a TypedWriteHook<K, T> and implements WriteHook<K> by decoding raw bytes to T via a Codec. Used by VarTypedTree / VarTypedMap so their users get typed hook callbacks.
VarTypedIter: Iterator over entries in a VarTypedTree. Returned by iter(), range(), range_bounds(), and prefix_iter(). Wraps VarIter and decodes each value via the codec. Entries with decode errors are skipped (see tracing::debug!).
VarTypedMap: A map with fixed-size keys and typed values T. Values are encoded via a Codec and stored on disk (variable length), with a block cache (≤ 8 KB values) and a value cache (> 8 KB values) for reads. Uses per-shard HashMap for O(1) lookup. Ordered scans are available when opened with iterable(true) via iter_view. Use VarTypedTree for prefix/range scans without the iterable flag.
VarTypedMapIterView: View over an iterable VarTypedMap; exposes ordered iteration yielding freshly decoded T values.
VarTypedMapKeyIter: Key-only iterator over an iterable VarTypedMap scan.
VarTypedMapRowIter: Row iterator over an iterable VarTypedMap scan.
VarTypedMapShard: Handle for atomic multi-key operations on a single shard of a VarTypedMap. Obtained via VarTypedMap::atomic. The shard + index locks are held for the lifetime of this struct — keep the closure short.
VarTypedShard: Handle for atomic multi-key operations within a single shard. Obtained via VarTypedTree::atomic. The shard lock is held for the lifetime of this struct — keep the closure short.
VarTypedTree: A tree with fixed-size keys and typed values T. Values are encoded via a Codec and stored on disk (variable length), with a block cache (≤ 8 KB values) and a value cache (> 8 KB values) for reads — unlike TypedTree which keeps values in memory.
VarTypedTreeKeyIter: Key-only iterator over a VarTypedTree scan.
VarTypedTreeRowIter: Row iterator over a VarTypedTree scan.
WatchEvent: A decoded view of one shared raw watch event.
WatchHook: Runtime carrier that adds subscriptions around an existing collection hook.
WatchOptions: Per-subscription bounded-ring configuration.
WatchReceiver: A single-consumer subscription receiver.
ZeroHookAdapter: Adapter: wraps a TypedWriteHook<K, T> and implements WriteHook<K> by converting raw bytes to &T via zerocopy. Used by ZeroTree/ZeroMap so their users get typed hook callbacks.
ZeroIter: Iterator over entries in a ZeroTree. Wraps ConstIter and converts [u8; V] values to T via zerocopy.
ZeroMap: A map with fixed-size keys and zerocopy-compatible typed values.
ZeroMapIterView: View over an iterable ZeroMap; exposes ordered iteration over (K, T) entries and cheap keys-only iteration. Obtained via ZeroMap::iter_view.
ZeroMapKeyIter: Key-only iterator over an iterable ZeroMap scan.
ZeroMapRowIter: Row iterator over an iterable ZeroMap scan.
ZeroMapShard: Handle for atomic multi-key operations within a single shard. Obtained via ZeroMap::atomic.
ZeroShard: Handle for atomic multi-key operations within a single shard. Obtained via ZeroTree::atomic.
ZeroTree: A tree with fixed-size keys and zerocopy-compatible values.
ZeroTreeKeyIter: Key-only iterator over a ZeroTree scan.
ZeroTreeRowIter: Row iterator over a ZeroTree scan.

Enums§

Applied: What actually happened to one key — a self-sufficient application event channel (old + new are present here, so duplicating an on_write hook is optional).
DbError: P2-4: #[non_exhaustive] so future variants are additive — downstream crates must include a wildcard arm, and adding a variant (like DuplicateCollection) is no longer a source-breaking change to their exhaustive matches.
Dir: Iteration direction for ordered scans.
FormatAction: Decision returned by one value-format migration step.
FormatMigrationPolicy: Policy controlling whether an opener runs a pending value-format migration.
IoBackend: Bitcask flush-path I/O strategy. Tunable; in-memory effect only — the on-disk format is identical regardless. Default: Pwrite.
MigrateAction: Action returned by the migrate() callback for each entry.
OnMissingTarget: What to do when the target row a contribution names does not exist.
SchemaMismatchKind: Specific kind of schema mismatch (see DbError::SchemaMismatch).
StopReason: Why a chunked page stopped reading rows.
TxFailStage: Which step after the transaction log append failed.
Upsert: A write decision for one key.
WatchError: Receiver outcomes that are not decoded-value errors.
WatchKind: Delivery detail available from a raw mutation.
Workload: Bitcask deployment-intent presets for Config. Pick one as the builder start point: Config::for_workload(Workload::…) or a sugar method.

Constants§

DEAD_CLASS
DEFAULT_MAX_PROJECTED_BYTES
DEFAULT_MAX_PROJECTED_ROWS: Defaults: 4096 rows / 1 MiB encoded payload per project call.
ID_BLOCK
LIVE_CLASS
UNIQUE_OWNER_KEY_CAP: Owner-key capacity. A format constant: the widest key in the measured consumer is 48 bytes, this leaves one 8-byte component of headroom.

Traits§

BulkScan: Sealed strict scan and mutation seam used by bulk Scope operations. Implemented only for the opaque tree and map scan wrappers.
CollectionMeta: Trait for types that carry enough metadata to describe an armdb collection.
CounterCollection: A collection that can hold a counter field. Implemented for the typed managed families in Task 3; sealed through IndexKeyed’s own seal.
IndexKeyed: Associated key/value types for typed row/key helpers.
IntoUpsert: Converts a closure result into an Upsert decision plus an optional caller-facing value.
Key: Key metadata trait — describes key encoding for armdb collections.
Location: Marker trait for disk location types stored in SkipList nodes. DiskLoc (12 bytes) for Bitcask, u32 (4 bytes) for FixedStore slot_id.
OrderedScan: Ordered, direction-aware scan seam. Implemented only on TreeScan / MapScan — never on collection types directly — so a non-iterable Map cannot obtain a value of this trait.
OwnedRows
ProjectableIndex: Crate-public seam every index family implements (Bitcask + Fixed Zero*, Typed*, VarTyped*). Lives in core so Projected does not depend on feature = "schema".
QueueMode: Selects the storage representation for a QueueSpec.
QueueSpec: Compile-time declaration of a durable queue.
StrictRows: Sealed strict row seam used by bulk retention operations.
TypedWriteHook: Typed write hook for TypedTree.
UniqueNamespace: Implemented only by unique_index!. The bound that keeps crate::armour::Db::open_unique_index from being aimed at an ordinary collection.
WatchDecoder: Decode a raw watch payload on the receiving side.
WatchSpec: The collection identity and decoder used by a watch receiver.
WriteHook: Trait for receiving write notifications from tree/map operations.

Functions§

boxed: Erase an iterator type for use as a BoxedRows.
collection_tag: FNV-1a over the collection name. const so a declaration can compute the tag of T::NAME at compile time.
merge_sorted: Lazily merge sources that are already ordered for dir.
page_chunks: Collect a bounded page while preparing rows in chunks before projection.

Type Aliases§

BatchWriteDeprecated: Renamed to Upsert in 0.8.0, so one decision type covers both upsert and update_many.
BoxedRows: Iterator-erased rows for callers with heterogeneous source types.
DbResult
FormatStepFn: Byte-to-byte callback used by a format migration step.
IndexedDeprecated: Deprecated alias — kept one release for downstream. Internal crate code uses Projected directly (see projection::Indexed). Renamed from Indexed (T9): the carrier now holds a counter projection alongside the index one. Kept one release for downstream — internal code must use Projected directly, since a hit here fails the crate’s -D warnings clippy gate.

Crate armdb

Crate armdb Copy item path

§Durability backends

§Collection types

§Usage

§Durability

§Bitcask

§FixedStore

§Thread safety

§Encryption at rest (feature encryption)

§Write hooks (secondary indexes)

§Compaction

§Iteration

§Complexity

§Weakly-consistent semantics

§Ordering: Config::reversed

§Prefix sharding

§Caveats

§Shutdown

§Layers above the core

§Features

Re-exports§

Modules§

Macros§

Structs§

Enums§

Constants§

Traits§

Functions§

Type Aliases§

Crate armdb

§Encryption at rest (feature `encryption`)

§Ordering: `Config::reversed`