From b96b989111163decc565cd2f16e55e8bd11e9640 Mon Sep 17 00:00:00 2001 From: Maksym Arutyunyan Date: Fri, 3 Apr 2026 14:02:41 +0200 Subject: [PATCH 1/4] refactor: improve node cache public API naming and docs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Rename ambiguous methods for clarity: - node_cache_size → node_cache_num_slots - node_cache_clear_metrics → node_cache_reset_metrics - node_cache_size_bytes_approx → node_cache_heap_usage Consolidate sizing guidance on the DEFAULT_NODE_CACHE_NUM_SLOTS constant and remove hardcoded values from method docs. --- src/btreemap.rs | 29 +++++++++++++++-------------- 1 file changed, 15 insertions(+), 14 deletions(-) diff --git a/src/btreemap.rs b/src/btreemap.rs index 80b42906..32c52826 100644 --- a/src/btreemap.rs +++ b/src/btreemap.rs @@ -87,11 +87,18 @@ const PAGE_SIZE_VALUE_MARKER: u32 = u32::MAX; /// Default number of slots in the direct-mapped node cache. /// -/// 16 slots cover the top two tree levels (1 root + up to 12 children = -/// 13 nodes) while keeping heap usage modest. +/// Sizing options (prefer powers of two for efficient slot indexing): +/// +/// - **0** — cache disabled, every access reads from stable memory. +/// - **1** — only the root node is cached; saves one read per operation. +/// - **16** — covers the top two tree levels (1 root + up to 12 +/// children = 13 nodes). Good balance of hit rate and heap usage. +/// - **32** — extra headroom over 16 that reduces collision evictions +/// in the direct-mapped scheme and typically yields ≥2 cache hits +/// per operation regardless of tree size. /// /// Users can adjust via [`BTreeMap::with_node_cache`] or -/// [`BTreeMap::node_cache_resize`], including setting to 0 to disable. +/// [`BTreeMap::node_cache_resize`]. const DEFAULT_NODE_CACHE_NUM_SLOTS: usize = 16; /// A B-Tree map implementation that stores its data into a designated memory. @@ -312,14 +319,8 @@ where /// Each slot can hold one deserialized node; on collision, shallower /// nodes (closer to the root) are kept over deeper ones. /// - /// Pass `0` to disable the cache (the default). - /// - /// The top 2 levels of the tree contain 13 nodes (1 root + up to - /// 12 children). **16** slots is the smallest power of two that - /// covers them, but a direct-mapped cache is sensitive to address - /// collisions, so **32** is a safer default that leaves headroom - /// and typically gives 2 cache hits per operation regardless of - /// tree size. Prefer powers of two for efficient slot indexing. + /// The cache is enabled by default. Pass `0` to disable. + /// Prefer powers of two for efficient slot indexing. /// /// # Examples /// @@ -365,7 +366,7 @@ where /// Returns the current number of slots in the node cache. /// /// Returns `0` when the cache is disabled. - pub fn node_cache_size(&self) -> usize { + pub fn node_cache_num_slots(&self) -> usize { self.cache.borrow().num_slots() } @@ -377,7 +378,7 @@ where /// Resets cache metrics (hit/miss counters) without evicting /// cached nodes. - pub fn node_cache_clear_metrics(&mut self) { + pub fn node_cache_reset_metrics(&mut self) { self.cache.get_mut().clear_metrics(); } @@ -406,7 +407,7 @@ where /// Actual usage depends on key size and how many slots are /// occupied. Treat this as an order-of-magnitude guide, not a /// precise budget. - pub fn node_cache_size_bytes_approx(&self) -> usize { + pub fn node_cache_heap_usage(&self) -> usize { self.cache.borrow().num_slots() * (self.version.page_size().get() as usize + NodeCache::::slot_size()) } From 7f7ac8bab43f3438565ac57d88beba928a96cd83 Mon Sep 17 00:00:00 2001 From: Maksym Arutyunyan Date: Sat, 4 Apr 2026 10:04:48 +0200 Subject: [PATCH 2/4] doc comments --- src/btreemap.rs | 25 +++++++++++++++++++++++-- 1 file changed, 23 insertions(+), 2 deletions(-) diff --git a/src/btreemap.rs b/src/btreemap.rs index 32c52826..c67fcf00 100644 --- a/src/btreemap.rs +++ b/src/btreemap.rs @@ -378,12 +378,22 @@ where /// Resets cache metrics (hit/miss counters) without evicting /// cached nodes. + /// + /// Call this before the workload you want to measure so that + /// counters reflect only that workload, not the entire lifetime + /// of the map. pub fn node_cache_reset_metrics(&mut self) { self.cache.get_mut().clear_metrics(); } /// Returns node-cache performance metrics. /// + /// Counters accumulate from map creation (or the last call to + /// [`node_cache_reset_metrics`](Self::node_cache_reset_metrics)) + /// and are never cleared automatically. To measure a specific + /// workload, call `node_cache_reset_metrics` first, run the + /// workload, then read the metrics. + /// /// # Examples /// /// ```rust @@ -392,8 +402,19 @@ where /// let mut map: BTreeMap = /// BTreeMap::init(DefaultMemoryImpl::default()) /// .with_node_cache(32); - /// map.insert(1, 100); - /// let _ = map.get(&1); + /// + /// // Populate the map (metrics accumulate during inserts). + /// for i in 0..100u64 { + /// map.insert(i, i); + /// } + /// + /// // Clear counters before the workload we care about. + /// map.node_cache_reset_metrics(); + /// + /// // Workload: read every key. + /// for i in 0..100u64 { + /// let _ = map.get(&i); + /// } /// /// let metrics = map.node_cache_metrics(); /// println!("hit ratio: {:.1}%", metrics.hit_ratio() * 100.0); From 314d0ee7b6aee0ebc693ccec6be92bd77bf26aaa Mon Sep 17 00:00:00 2001 From: Maksym Arutyunyan Date: Sat, 4 Apr 2026 10:38:43 +0200 Subject: [PATCH 3/4] doc comment --- src/btreemap/node_cache.rs | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/src/btreemap/node_cache.rs b/src/btreemap/node_cache.rs index 4777bebd..9897894c 100644 --- a/src/btreemap/node_cache.rs +++ b/src/btreemap/node_cache.rs @@ -4,6 +4,11 @@ use crate::Storable; use super::node::Node; /// Node-cache performance metrics. +/// +/// Counters accumulate over the lifetime of the cache and are **never +/// cleared automatically**. To measure a specific workload, call +/// [`BTreeMap::node_cache_clear_metrics`](super::BTreeMap::node_cache_clear_metrics) +/// before the workload, then read the metrics afterward. #[derive(Debug, Default, Clone, Copy, PartialEq, Eq)] pub struct NodeCacheMetrics { /// Successful cache lookups. From 54ac3ae65c0ebcbfcf231f8b094d57021b2a652a Mon Sep 17 00:00:00 2001 From: Maksym Arutyunyan Date: Sat, 4 Apr 2026 10:41:19 +0200 Subject: [PATCH 4/4] fix doc comment --- src/btreemap/node_cache.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/btreemap/node_cache.rs b/src/btreemap/node_cache.rs index 9897894c..c4eb1d2c 100644 --- a/src/btreemap/node_cache.rs +++ b/src/btreemap/node_cache.rs @@ -7,7 +7,7 @@ use super::node::Node; /// /// Counters accumulate over the lifetime of the cache and are **never /// cleared automatically**. To measure a specific workload, call -/// [`BTreeMap::node_cache_clear_metrics`](super::BTreeMap::node_cache_clear_metrics) +/// [`BTreeMap::node_cache_reset_metrics`](super::BTreeMap::node_cache_reset_metrics) /// before the workload, then read the metrics afterward. #[derive(Debug, Default, Clone, Copy, PartialEq, Eq)] pub struct NodeCacheMetrics {