fix: update scan resistance chart and improve documentation clarity (#109)

- Adjusted the maximum value for the scan resistance chart to dynamically reflect the highest score, enhancing visual accuracy.
- Revised documentation in `render_docs.rs` to clarify the performance characteristics of cache policies, specifically noting that low latency operations have near O(1) average overhead.
- Enhanced comments in `hashmap.rs` and `slab.rs` to provide clearer explanations of panic conditions and invariants, improving overall code maintainability.

These changes improve the observability of cache performance metrics and enhance the clarity of documentation for better user understanding.

Author: TKorr

bench-support/src/bin/charts_template.html

@@ -461,6 +461,7 @@ <h2>Adaptation Speed (Ops to 80%)</h2>
                     scores.push(result.metrics.scan_resistance.resistance_score);
                 }
             });
+            const scanResistanceMax = Math.max(1.0, ...scores) * 1.05;
 
             new Chart(document.getElementById('scanResistanceChart'), {
                 type: 'bar',
@@ -481,7 +482,7 @@ <h2>Adaptation Speed (Ops to 80%)</h2>
                     scales: {
                         x: {
                             beginAtZero: true,
-                            max: 1.0,
+                            max: scanResistanceMax,
                             title: {
                                 display: true,
                                 text: 'Score (1.0 = perfect)'

bench-support/src/bin/render_docs.rs

@@ -423,7 +423,9 @@ fn generate_policy_guide() -> String {
     md.push_str(
         "| **Scan-heavy workloads** | S3-FIFO, Heap-LFU | Scan-resistant, protect hot entries |\n",
     );
-    md.push_str("| **Low latency required** | LRU, Clock | Fastest operations, O(1) overhead |\n");
+    md.push_str(
+        "| **Low latency required** | LRU, Clock | Fast operations, near O(1) average overhead |\n",
+    );
     md.push_str("| **Memory constrained** | LRU, Clock | Minimal metadata overhead |\n");
     md.push_str("| **Frequency-aware** | LFU, Heap-LFU, LRU-K | Track access frequency for better decisions |\n");
     md.push_str("| **Shifting patterns** | S3-FIFO, 2Q | Adapt to changing access patterns |\n");

src/store/hashmap.rs

@@ -1208,6 +1208,9 @@ where
     }
 
     /// Computes the shard index for a key.
+    ///
+    /// Sharded operations pay one extra hash to choose the target shard before
+    /// the within-shard `HashMap` lookup.
     fn shard_index(&self, key: &K) -> usize {
         (self.hasher.hash_one(key) as usize) % self.shards.len()
     }
@@ -1330,7 +1333,12 @@ where
                     }
                     if self
                         .size
-                        .compare_exchange(current, current + 1, Ordering::AcqRel, Ordering::Relaxed)
+                        .compare_exchange_weak(
+                            current,
+                            current + 1,
+                            Ordering::AcqRel,
+                            Ordering::Relaxed,
+                        )
                         .is_ok()
                     {
                         break;
@@ -1342,6 +1350,8 @@ where
                 struct SizeGuard<'a>(&'a AtomicUsize);
                 impl Drop for SizeGuard<'_> {
                     fn drop(&mut self) {
+                        // `size` is only a capacity counter; shard locks guard
+                        // entries, so rollback does not publish data.
                         self.0.fetch_sub(1, Ordering::Relaxed);
                     }
                 }

src/store/slab.rs

@@ -759,7 +759,9 @@ where
             // `panic = "unwind"` build). Assert loudly in debug; in release,
             // heal by dropping the stale index entry so we fall into the
             // new-key path without panicking.
-            debug_assert!(false, "slab store index/entries desync at slot {}", id.0);
+            #[cfg(debug_assertions)]
+            panic!("slab store index/entries desync at slot {}", id.0);
+            #[cfg(not(debug_assertions))]
             self.index.remove(&key);
         }
 
@@ -1245,11 +1247,12 @@ where
             // or out of bounds. Assert loudly in debug; in release, heal by
             // dropping the stale index entry so the new-key path can take
             // over without blindly counting a logical-update as an insert.
-            debug_assert!(
-                false,
+            #[cfg(debug_assertions)]
+            panic!(
                 "concurrent slab store index/entries desync at slot {}",
                 id.0
             );
+            #[cfg(not(debug_assertions))]
             inner.index.remove(&key);
         }
 

src/store/weight.rs

@@ -102,7 +102,7 @@
 //!
 //! **Costs:**
 //! - Weight function called on every insert/update
-//! - Uses `Arc<V>` even for single-threaded store (needed for weight_fn)
+//! - Uses `Arc<V>` even for single-threaded store (cheap shared ownership for returned values)
 //! - Slightly more state to track than simple HashMap stores
 //!
 //! ## When to Use
@@ -299,7 +299,8 @@ impl StoreCounters {
 ///
 /// Enforces both a maximum number of entries and a maximum total weight.
 /// Weight is computed via a caller-provided function and cached per entry.
-/// Uses `Arc<V>` for values to enable weight function access.
+/// Uses `Arc<V>` for values to allow cheap shared ownership without requiring
+/// `V: Clone`.
 ///
 /// # Type Parameters
 ///
@@ -446,6 +447,8 @@ where
         capacity_weight: usize,
         weight_fn: F,
     ) -> Result<Self, std::collections::TryReserveError> {
+        // Build the map empty, then reserve fallibly so allocation errors are
+        // returned instead of panicking in an infallible capacity constructor.
         let mut map: FxHashMap<K, WeightEntry<V>> = FxHashMap::with_hasher(Default::default());
         map.try_reserve(capacity_entries)?;
         Ok(Self {
@@ -739,7 +742,7 @@ where
             let base_total = self
                 .total_weight
                 .checked_sub(entry.weight)
-                .expect("WeightStore invariant violated: checked_sub failed after invariant check");
+                .expect("WeightStore invariant violated: total_weight must be >= entry.weight");
             let next_total = base_total.checked_add(new_weight).ok_or(StoreFull)?;
             if next_total > self.capacity_weight {
                 return Err(StoreFull);
@@ -806,7 +809,7 @@ where
         self.total_weight = self
             .total_weight
             .checked_sub(entry.weight)
-            .expect("WeightStore invariant violated: checked_sub failed after invariant check");
+            .expect("WeightStore invariant violated: total_weight must be >= entry.weight");
         self.metrics.inc_remove();
         Some(entry.value)
     }