]> git.hungrycats.org Git - bees/commitdiff
scan-next: erase hash cells pointing at a ceiling extent
authorZygo Blaxell <bees@furryterror.org>
Sat, 19 Sep 2026 17:11:30 +0000 (13:11 -0400)
committerZygo Blaxell <bees@furryterror.org>
Sun, 11 Oct 2026 00:48:00 +0000 (20:48 -0400)
An extent at or above rewrite.refs-max cannot take another reference, so
it can never serve as a dedupe src again.  Its block hashes stay in the
hash table regardless, and every later scan that shares one of them pays
a lookup and an extent resolve to rediscover that the extent is
unusable.  Nothing ever clears this:  the crawler advances past the
extent and will not return, because nothing about the extent changes.

Erase the cell instead.  The candidate search already erases cells that
resolve into a gap between extents, and normalizes cells that point into
the middle of an extent; a ceiling extent belongs in the first category
rather than the second, since normalizing its address only preserves a
pointer to something that has permanently withdrawn from dedupe.

This erases only the hashes that actually surface in a lookup, which is
the complete set of hashes that cost anything -- a hash nobody looks up
is free to leave in place.  It also needs no reference list, which
matters here because a ceiling extent has none to offer.

Telling a ceiling extent apart from a freed one needs the same
disambiguation the start-extent path needed, so the candidate gate now
asks refs_at_ceiling() as well, and counts the two separately.

Document the candidate event group, which was missing entirely.

Assisted-by: Claude-Code:claude-opus-5
Assisted-by: Claude-Code:claude-opus-5-5
docs/event-counters.md
src/bees-scan-next.cc

index ec3e397e98cd6bbc9364de027e2fd00f0795ec92..b75fe54422e56689d70d3a4d804b84f24d8c1265 100644 (file)
@@ -115,6 +115,25 @@ The `bug` event group consists of known bugs in bees.
  * `bug_hash_duplicate_cell`: Two entries in the hash table were identical.  This only happens due to data corruption or a bug.
  * `bug_hash_magic_addr`: An entry in the hash table contains an address with magic.  Magic addresses cannot be deduplicated so they should not be stored in the hash table.
 
+candidate
+---------
+
+The `candidate` event group covers the search for extents that might be
+deduped against the extent currently being scanned.  Hash table cells
+matching the start extent's block hashes are resolved to the extents
+that contain them, and each extent is gated once and cached for the rest
+of the scan.
+
+ * `candidate_cache_extent`: A cell address was resolved to a live extent for the first time in this scan, gated, and cached.
+ * `candidate_cache_gap`: A cell address fell in a gap between extents.  The gap was bounded and cached, and the stale cell erased from the hash table.
+ * `candidate_cache_hit`: A cell address was resolved from the per-scan range cache, with no tree lookup.
+ * `candidate_checked`: A candidate extent was compared against the start extent to find matching ranges.
+ * `candidate_datacow_mismatch`: A candidate extent was rejected because its datacow status is incompatible with the start extent's.
+ * `candidate_matched`: The comparison found at least one matching range, in either direction.
+ * `candidate_no_refs`: A candidate extent's reference list was empty:  the extent was freed, or all of its references are stale.
+ * `candidate_refs_at_ceiling`: A candidate extent's reference list was empty because the extent sits at or above the `rewrite.refs-max` ceiling (see `refs_overflow`).  It can never take another reference, so the hash table cell that found it is erased rather than kept or normalized.
+ * `candidate_unmatched`: The comparison found no matching ranges.
+
 chase
 -----
 
index a3dfdd9f99aec71cb2742383e0f0f00e1bbc2da0..dabd84c6613dff5a80548804930a2247064751bc 100644 (file)
@@ -3382,6 +3382,7 @@ scan_next_seed_initial_candidates(
                bool       m_is_extent = false; ///< false => dead gap (negative cache)
                bool       m_is_start = false;  ///< the start extent: cached, never queued
                bool       m_accepted = false;  ///< queue-eligible (refs + datacow ok)
+               bool       m_at_ceiling = false;///< refs suppressed at rewrite.refs-max
                size_t     m_hits = 0;          ///< matching-hash count => queue priority
                BeesExtent m_extent;            ///< valid iff m_is_extent
        };
@@ -3458,7 +3459,16 @@ scan_next_seed_initial_candidates(
                                                        // Freed / all-stale: drop, but cache as
                                                        // not-accepted so its other cells skip the
                                                        // lookup and the datacow_fetch throw.
-                                                       BEESCOUNT(candidate_no_refs);
+                                                       //
+                                                       // An extent at the reference ceiling reports
+                                                       // the same empty list without being freed at
+                                                       // all, and is handled differently below.
+                                                       if (prev.refs_at_ceiling().value_or(false)) {
+                                                               k.m_at_ceiling = true;
+                                                               BEESCOUNT(candidate_refs_at_ceiling);
+                                                       } else {
+                                                               BEESCOUNT(candidate_no_refs);
+                                                       }
                                                } else if (!scan_next_datacow_compatible(prev, start, layer)) {
                                                        BEESCOUNT(candidate_datacow_mismatch);
                                                } else {
@@ -3474,6 +3484,26 @@ scan_next_seed_initial_candidates(
                                                continue;
                                        }
 
+                                       // An extent at the reference ceiling can never take
+                                       // another reference, so it can never be a src again.
+                                       // Leaving its cells in the table costs a lookup and a
+                                       // resolve on every future scan that shares one of its
+                                       // hashes, forever:  the crawler will not revisit the
+                                       // extent to change anything, because nothing about it
+                                       // changes.  Erase the cell instead of normalizing it,
+                                       // so the table stops pointing at an extent that has
+                                       // permanently withdrawn from dedupe.
+                                       //
+                                       // This erases only the hashes that actually surface,
+                                       // which is the complete set of hashes that cost
+                                       // anything -- a hash nobody looks up is free to leave
+                                       // in place.  It needs no reference list, which matters
+                                       // because a ceiling extent has none to offer.
+                                       if (kp->m_at_ceiling) {
+                                               hash_table->erase_hash_addr(hash, cell.e_addr);
+                                               continue;
+                                       }
+
                                        // Normalize old-format cells to the extent begin.
                                        const auto extent_begin = kp->m_extent.bytenr();
                                        if (cell.e_addr != extent_begin) {