From babd62c5ba6d2fc364dfb9e1dc9068a44f1466a1 Mon Sep 17 00:00:00 2001 From: Quentin de Quelen Date: Mon, 9 Nov 2026 23:50:48 +0100 Subject: [PATCH] first/last descend without a cursor (#147) Database::first and Database::last built a cursor, with its 32-frame path stack and leaf cache, to read one entry and drop it. They now use Tree::first_entry / last_entry: a root-to-leaf descent along one edge that keeps no path, the shape of the cursor-free point get, with the same level bound and error. The tree tests assert the new descent agrees with the cursor on every tree they walk, including the empty one. Laptop, read_census at one codegen unit (thread CPU, p10, median of 5 interleaved rounds): first_last 61.9 -> 41.7 ns per call, LMDB 54.5 (1.14x -> 0.77x). get/access/hot and scan/full/fwd unchanged. The bench-ab run was invalid under machine load; a Graviton gate is owed. Recorded in the perf ledger. Co-Authored-By: Claude --- CHANGELOG.md | 3 ++ benches/results/perf-ledger.jsonl | 1 + crates/zerodb-core/src/btree/mod.rs | 61 +++++++++++++++++++++++++++++ crates/zerodb-core/src/rotxn.rs | 10 +---- 4 files changed, 67 insertions(+), 8 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 4fd5e4d4..2f074ef1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -166,6 +166,9 @@ Ratios are ZeroDB time ÷ LMDB time on Graviton4 unless stated; details in - Full scans read entries from the leaf in hand, and trusted mode no longer records leaves: `scan/full/fwd` 2.25× → 1.45×, and about 1.0× in trusted mode. +- `first` and `last` descend without building a cursor, as point gets do + (#147): 61.9 → 41.7 ns per call against LMDB's 54.5 (1.14× → 0.77×, + laptop). - `skip` crosses whole leaves without decoding the entries it passes. - Short read transactions reuse their memory on the same thread (#25). - The meta checksum uses the ARMv8 `crc32c` instructions on aarch64 diff --git a/benches/results/perf-ledger.jsonl b/benches/results/perf-ledger.jsonl index 674573ff..3cf7ab18 100644 --- a/benches/results/perf-ledger.jsonl +++ b/benches/results/perf-ledger.jsonl @@ -111,3 +111,4 @@ {"date": "2026-11-02T07:33:25+00:00", "rung": "^(put/gc/ovf|del/bulk)", "hypothesis": "Owed re-measure for #141 (write cursor keeps its path across splits): #141 saw put/gc/ovf_across +4.2% and del/bulk/all +3.1% and was never re-run after its last fix. Before = aa6cbe3 (the commit #141 was built on), after = main at 3c4f37f.", "outcome": "kept", "commit": "987ce3e", "verdict": "invalid", "base": "aa6cbe351f86a46befe79b82bbc3a0b70eeeb628", "host": "Darwin arm64", "rounds": 3, "rungs": [{"rung": "del/bulk/all", "state": "unreliable", "ratio_vs_lmdb_before": 0.9936896285905952, "ratio_vs_lmdb_after": 0.9259079292614257, "speedup": 0.931787856712052}, {"rung": "del/bulk/half", "state": "improved", "ratio_vs_lmdb_before": 1.2715363571835225, "ratio_vs_lmdb_after": 0.991449157233737, "speedup": 0.7797253705193424}, {"rung": "put/gc/ovf_across", "state": "unreliable", "ratio_vs_lmdb_before": 0.8452338529426783, "ratio_vs_lmdb_after": 1.1733910898597482, "speedup": 1.3882443134223643}, {"rung": "put/gc/ovf_miss", "state": "unreliable", "ratio_vs_lmdb_before": 3.204429671760977, "ratio_vs_lmdb_after": 1.9395986177080942, "speedup": 0.5698584235538426}], "notes": "macOS laptop (Apple Silicon, 16 KiB pages), 3 interleaved rounds at load average 26 with nine other build sessions running: verdict INVALID, indicative only. LMDB drifted 20-56% between halves on del/bulk/all, put/gc/ovf_across and put/gc/ovf_miss, so those rows say nothing. The one reliable row: del/bulk/half 1.27x -> 0.99x LMDB (0.78 of before, LMDB drift 0.997). No regression is visible, but the +4.2% / +3.1% question is not settled: the referee is still a Graviton run of the same filter on a quiet host. The current harness needs two shims to build against aa6cbe3 (the heed-zerodb package rename and the oracle os_page_size helper), so a re-run must apply them too."} {"date": "2026-11-02T08:11:39+00:00", "rung": "put/order/append", "hypothesis": "APPEND zero-fill: skip the fill(0) of a reused spare frame (heap) and of the map page (in-place WRITE_MAP) when insert_tree_frame creates a split half, as LMDB leaves a reused me_dpages page and a WRITEMAP page unzeroed; fresh heap allocations stay zeroed. The insert_tree_frame contract (fresh frames all-zero) forbids it, so it needs an ADR.", "outcome": "blocked-adr", "notes": "macOS laptop, 16 KiB pages, load average ~100, indicative. Scratch driver, 50k APPEND puts of 256-byte values in one txn, loop time only, min of 31 reps, 5 interleaved runs: WRITE_MAP 81.6 -> 73.6 ns/entry (0.90, every run agrees), heap 113.1 -> 109.4 (0.97, noise; only spare frames are affected, and the put/order/append rung opens a fresh env per iteration so it has none). Not kept: measured on a throwaway build only. Safety argument and recommendation: header and cells are fully written by init and the inserts, nothing reads the free gap (ADR-0030), the stale bytes are this env's own; a split MDB_RESERVE placeholder must then be zeroed explicitly. Referee: Graviton put/order/append under ZERODB_BENCH_WRITE_MAP=1."} {"date": "2026-11-02T21:16:32+00:00", "rung": "^(put/cursor|del/cursor|put/over/same_size)", "hypothesis": "Write cursor and keyed writes, per-entry cost: (1) touch_path returns after one dirty-set test when the path ends on a frame of this txn and nothing is spilled (a page is copied only below a touched parent), instead of one probe per level; (2) delete_apply reads the value shape and removes the cell through one frame access; (3) the cursor in-leaf step and current-key reads check the handle and read the leaf directly, without building a Tree.", "outcome": "kept", "verdict": "improved", "base": "779ce3772a543337d2c5ca5cf9ebd71214a9efb8", "host": "Darwin arm64", "rounds": 3, "rungs": [{"rung": "del/cursor/drain", "state": "improved", "ratio_vs_lmdb_before": 1.4473069653649546, "ratio_vs_lmdb_after": 1.3635500887773762, "speedup": 0.942696812319092}, {"rung": "del/cursor/rev", "state": "improved", "ratio_vs_lmdb_before": 1.5557379392236108, "ratio_vs_lmdb_after": 1.4181563952222385, "speedup": 0.9081392248656213}, {"rung": "put/cursor/rewrite", "state": "improved", "ratio_vs_lmdb_before": 1.4903260942357737, "ratio_vs_lmdb_after": 1.3721839822237063, "speedup": 0.9230954658696557}, {"rung": "put/cursor/rewrite_reserved", "state": "improved", "ratio_vs_lmdb_before": 1.519072261691081, "ratio_vs_lmdb_after": 1.4212508766951422, "speedup": 0.9353051010587302}, {"rung": "put/cursor/rewrite_reserved_ovf", "state": "unreliable", "ratio_vs_lmdb_before": 1.141535860898173, "ratio_vs_lmdb_after": 1.2033279149977745, "speedup": 1.0541306289326582}, {"rung": "put/order/append", "state": "flat", "ratio_vs_lmdb_before": 1.3689426360392456, "ratio_vs_lmdb_after": 1.3620864566063446, "speedup": 0.9932515325105543}, {"rung": "put/order/rand", "state": "flat", "ratio_vs_lmdb_before": 0.9062615045875345, "ratio_vs_lmdb_after": 0.8864357119964356, "speedup": 0.9781235410632141}, {"rung": "put/order/seq", "state": "flat", "ratio_vs_lmdb_before": 0.8388673563926385, "ratio_vs_lmdb_after": 0.8205656357264116, "speedup": 0.9772166920185364}, {"rung": "put/over/grow", "state": "flat", "ratio_vs_lmdb_before": 1.0856392607006042, "ratio_vs_lmdb_after": 1.0614109982943436, "speedup": 0.9758267762159284}, {"rung": "put/over/same_size", "state": "improved", "ratio_vs_lmdb_before": 1.1505396293473196, "ratio_vs_lmdb_after": 1.1076922211165607, "speedup": 0.962614914206971}], "notes": "macOS laptop (Apple Silicon, 16 KiB pages), load 4.4, 3 interleaved rounds, before = origin/main 779ce37: improved 5, regressed 0, flat 7, drift 1 (rewrite_reserved_ovf). put/cursor/rewrite 1.49x -> 1.37x LMDB, del/cursor/drain 1.45x -> 1.36x, del/cursor/rev 1.56x -> 1.42x, put/over/same_size 1.15x -> 1.11x. Profile of the rewrite loop before: the second page lookup per entry (step leaf view + put frame) was ~3% of an entry; a slab-handle dirty index to remove it was not tried (DirtyStore restructure, small gain). Also measured and not kept: threading an owned-path flag from the keyed descent into put_apply/delete_apply (no gain over the one-test touch_path, more signature churn). Graviton referee owed."} +{"date": "2026-11-09T22:41:31+00:00", "rung": "scan/edge/first_last", "hypothesis": "Database::first/last descend without a cursor (Tree::first_entry / last_entry): no 32-frame path stack to initialise, no leaf cache, no cursor state, as the cursor-free point get; LMDB pays mdb_cursor_init plus mdb_page_search.", "outcome": "kept", "verdict": "invalid", "base": "f77726057c2ec513b7c13a04e3654dfd7c56c41e", "host": "Darwin arm64", "rounds": 3, "rungs": [{"rung": "scan/edge/first_last", "state": "unreliable", "ratio_vs_lmdb_before": 1.1296049331348756, "ratio_vs_lmdb_after": 0.8051961349910187, "speedup": 0.7113026946209665}], "notes": "macOS laptop (Apple Silicon, 16 KiB pages), load 4-10 from a sibling session: the bench-ab verdict is INVALID (LMDB drift over 3% on 4 of 5 rungs; first_last read 0.71 of before). Load-independent evidence, read_census at codegen-units=1, thread CPU ns/op, p10 over 200 batches, median of 5 interleaved rounds: first_last LMDB 54.5, before 61.9, after 41.7 (1.14x -> 0.77x LMDB, 0.675 of before; every after round below every before round and every LMDB round on min). Unchanged paths, 7 rounds of 300 batches: get/access/hot 34.5 -> 33.9 (flat), scan/full/fwd 3.94 -> 3.81. A Graviton bench-ab gate is owed."} diff --git a/crates/zerodb-core/src/btree/mod.rs b/crates/zerodb-core/src/btree/mod.rs index 0619672d..2cf8f5f6 100644 --- a/crates/zerodb-core/src/btree/mod.rs +++ b/crates/zerodb-core/src/btree/mod.rs @@ -617,6 +617,61 @@ impl<'a> Tree<'a> { Err(depth_exceeded()) } + /// The minimum entry (`MDB_FIRST` with no cursor kept), or `None` for an + /// empty tree. Same result as [`Cursor::first`] on a fresh cursor. + /// + /// # Errors + /// + /// A [`PageError`] only if the tree is structurally corrupt. + pub fn first_entry(&self) -> PosResult<'a> { + self.edge_entry(false) + } + + /// The maximum entry (`MDB_LAST` with no cursor kept), or `None` for an + /// empty tree. Same result as [`Cursor::last`] on a fresh cursor. + /// + /// # Errors + /// + /// A [`PageError`] only if the tree is structurally corrupt. + pub fn last_entry(&self) -> PosResult<'a> { + self.edge_entry(true) + } + + /// Root-to-leaf descent along the leftmost (`max == false`) or rightmost + /// edge, returning that leaf's first or last entry. No cursor: the caller + /// keeps no position, so there is no path to record, as in + /// [`Tree::find_exact`], whose level bound and error this shares. + #[inline(always)] + fn edge_entry(&self, max: bool) -> PosResult<'a> { + if self.root == PGNO_INVALID { + return Ok(None); + } + let mut pgno = self.root; + for _ in 0..(self.depth as usize + 2).min(CURSOR_STACK) { + match node_view(self.src, self.psize, pgno, self.valid)? { + NodeView::Leaf(leaf) => { + let n = leaf.num_keys(); + if n == 0 { + return Ok(None); + } + let ki = if max { n - 1 } else { 0 }; + let k = leaf.key(ki); + let v = resolve_value(self.src, self.psize, &leaf, ki, self.valid)?; + return Ok(Some((k, v))); + } + NodeView::Branch(br) => { + let ci = if max { + br.num_keys().saturating_sub(1) + } else { + 0 + }; + pgno = br.child_pgno(ci); + } + } + } + Err(depth_exceeded()) + } + /// Catalog lookup for the named-DB resolver (SPEC 02 §6): like [`Tree::get`] /// but also returns the leaf **node flags** of the matched entry, so the /// caller can tell an `F_SUBDATA` sub-DB record from a plain user key @@ -1644,6 +1699,9 @@ mod tests { let mut c = tree.cursor(); let mut out = Vec::new(); let mut e = c.first().unwrap(); + // The cursor-free edge read agrees with the cursor on every tree + // these tests walk. + assert_eq!(tree.first_entry().unwrap(), e); while let Some((k, v)) = e { out.push((k.to_vec(), v.to_vec())); e = c.next().unwrap(); @@ -1655,6 +1713,7 @@ mod tests { let mut c = tree.cursor(); let mut out = Vec::new(); let mut e = c.last().unwrap(); + assert_eq!(tree.last_entry().unwrap(), e); while let Some((k, v)) = e { out.push((k.to_vec(), v.to_vec())); e = c.prev().unwrap(); @@ -1669,6 +1728,8 @@ mod tests { assert!(t.is_empty()); assert_eq!(t.get(b"x").unwrap(), None); let mut c = t.cursor(); + assert_eq!(t.first_entry().unwrap(), None); + assert_eq!(t.last_entry().unwrap(), None); assert_eq!(c.first().unwrap(), None); assert_eq!(c.last().unwrap(), None); assert_eq!(c.next().unwrap(), None); diff --git a/crates/zerodb-core/src/rotxn.rs b/crates/zerodb-core/src/rotxn.rs index 4203bbee..aa14a8a1 100644 --- a/crates/zerodb-core/src/rotxn.rs +++ b/crates/zerodb-core/src/rotxn.rs @@ -1009,10 +1009,7 @@ impl Database { &self, txn: &'txn T, ) -> Result> { - self.checked_tree(txn)? - .cursor() - .first() - .map_err(map_page_err) + self.checked_tree(txn)?.first_entry().map_err(map_page_err) } /// `last(txn)` — the maximum entry (SPEC 00 row 42). @@ -1021,10 +1018,7 @@ impl Database { /// /// [`MdbError::Invalid`] on a corrupt tree. pub fn last<'txn, T: TxnRead>(&self, txn: &'txn T) -> Result> { - self.checked_tree(txn)? - .cursor() - .last() - .map_err(map_page_err) + self.checked_tree(txn)?.last_entry().map_err(map_page_err) } /// `get_greater_than_or_equal_to(txn, key)` — first entry `≥ key`