]> git.hungrycats.org Git - bees/commitdiff
verification: carry pending references in the verification ring
authorZygo Blaxell <bees@furryterror.org>
Wed, 23 Sep 2026 04:15:14 +0000 (00:15 -0400)
committerZygo Blaxell <bees@furryterror.org>
Sun, 11 Oct 2026 00:48:00 +0000 (20:48 -0400)
The record of references bees created that a resolve cannot yet report
had its own expiry:  a counter of observed transid changes and a fixed
four-change lifetime.  The verification tracker already answers the
same question -- how many transid changes must pass before the effects
of a dedupe are in the commit root -- with a ring sized by
loop.verify-delay, and it rotates on the same observation from the same
thread.  Two mechanisms for one wait is one too many, and the fixed
lifetime was not operator-tunable where verify-delay is.

Record each created reference into the ring slot currently being
filled, and drop the slot's record when it retires, at the same moment
the dsts recorded into it are checked for deletion.  A resolve unions
the record from every slot.  BeesPendingRefs goes away; the ring's own
mutex covers the map alongside the extents and locks it already holds.

Assisted-by: Claude-Code:claude-fable-5-1
docs/config-file.md
src/Makefile
src/bees-context.cc
src/bees-extent-layer.cc
src/bees-pending-refs.cc [deleted file]
src/bees-pending-refs.h [deleted file]
src/bees-roots.cc
src/bees-verification.h
src/bees.h
test/Makefile

index 64fb073d920a604a58fd6189fbdfcadea512ef57..6824b2d572d81fc00f27d4b1988634b6236d910b 100644 (file)
@@ -1295,6 +1295,8 @@ The `[loop]` section controls the crawl loop lifecycle.  By default bees runs as
 
   Note that this parameter is the number of times the filesystem's current transid is observed to change during the transid polling loop, not the difference between one observed value and another.  e.g. if the bees loop observes the filesystem transid is 10000, and in the following iteration of the loop observes 10050, that is counted as one increment, not 50.
 
+  The same wait also bounds how long bees carries the record of references its own dedupes created, which a resolve cannot report until the dedupe's transaction commits (see `resolve.commit-root`).
+
   Minimum `2`.  Default: `2`.
 
   Example — wait five transid increments on a busy filesystem:
@@ -1314,7 +1316,7 @@ The `[resolve]` section controls how bees maps a physical btrfs address back to
 
   With `yes`, the answer comes from the last committed transaction, so no tree mod log sequence is held.  The cost is that the answer can be up to one transaction (roughly 30 seconds) stale: references other writers created since the last commit are invisible.  bees is built to survive that — the kernel already falls back to the commit roots on its own whenever it cannot attach to a running transaction, the crawler only hands out extents from committed transactions, and references that vanish between the walk and the dedupe are treated as churn rather than errors.  A reference bees cannot see is a reference it does not dedupe, so the extent survives a dedupe that was supposed to free it, and the work is repeated on a later pass.
 
-  References bees creates itself are handled separately, because those it cannot afford to miss: an extent that has just served as a dedupe source has gained references no commit-root walk can report yet, and if it is then chosen as a destination, a plan built from the short list would leave it in place.  bees records every reference its own dedupes create and unions them into every resolve of that extent until they have reached the commit root, with either setting.
+  References bees creates itself are handled separately, because those it cannot afford to miss: an extent that has just served as a dedupe source has gained references no commit-root walk can report yet, and if it is then chosen as a destination, a plan built from the short list would leave it in place.  bees records every reference its own dedupes create and unions them into every resolve of that extent until they have reached the commit root, with either setting.  The record is kept for the same `loop.verify-delay` transid changes that gate destination verification.
 
   The option exists so the two can be compared on a single kernel, on a specific workload, without rebuilding.
 
index 6cd949f3d7f2ba52aa5457cff6c23233c2b90ebc..c6fc88af7f067259613107f6fef90fa4fd65d2dc 100644 (file)
@@ -39,7 +39,6 @@ BEES_OBJS = \
        bees-heatmap.o \
        bees-lib.o \
        bees-log.o \
-       bees-pending-refs.o \
        bees-plan.o \
        bees-planner-state.o \
        bees-reporter.o \
@@ -70,7 +69,6 @@ REPL_OBJS = \
        bees-heatmap.o \
        bees-lib.o \
        bees-log.o \
-       bees-pending-refs.o \
        bees-plan.o \
        bees-planner-state.o \
        bees-reporter.o \
index 1a9cafc34d5758cff45aab7fc66cdae0830d9fe9..3832d306e0e85120777b62dd9f8f16e11df52b6a 100644 (file)
@@ -269,11 +269,11 @@ BeesContext::dedup(const BeesRangePair &brp_in)
                                // extents that no resolve can report until they
                                // commit.  Put them on record so a resolve of those
                                // extents stays complete in the meantime (see
-                               // bees-pending-refs.h).
+                               // bees-verification.h).
                                const auto dst_fid = brp.second.fid();
                                for (const auto &created : bees_dedupe_created_refs(m_root_fd, brp)) {
-                                       m_pending_refs.add(created.m_bytenr, dst_fid.root(),
-                                               dst_fid.ino(), created.m_offset);
+                                       m_verification->record_pending_ref(created.m_bytenr,
+                                               dst_fid.root(), dst_fid.ino(), created.m_offset);
                                }
                        } else {
                                BEESCOUNT(dedup_miss);
@@ -1051,7 +1051,7 @@ BeesContext::logical_ino(const uint64_t logical, const bool all_refs)
        // References bees created itself are the exception -- a src it
        // re-plans as a dst from a list missing them survives the dedupe --
        // and those it keeps on record and unions into every resolve until
-       // they commit (see bees-pending-refs.h).
+       // they commit (see bees-verification.h).
        //
        // On by default; the knob exists so the two can be compared on one
        // kernel.
@@ -1303,6 +1303,51 @@ BeesContext::refs_max() const
        return get_rewrite_policy().m_refs_max;
 }
 
+void
+BeesVerificationTracker::record_pending_ref(const uint64_t bytenr, const uint64_t root,
+       const uint64_t inum, const uint64_t offset)
+{
+       unique_lock<mutex> guard(m_mutex);
+       m_cycles[m_current].m_pending_refs[bytenr].push_back(PendingRef{root, inum, offset});
+       BEESCOUNT(pending_ref_add);
+}
+
+size_t
+BeesVerificationTracker::merge_pending_refs(const uint64_t bytenr,
+       vector<BtrfsInodeOffsetRoot> &iors) const
+{
+       unique_lock<mutex> guard(m_mutex);
+       // Both lists are short compared to a LOGICAL_INO buffer and the
+       // pending side is usually a few hundred entries at most, so a linear
+       // presence test over the kernel's answer is fine.  A pending entry the
+       // kernel already reports is one that has reached the tree it walked;
+       // it stays recorded until its slot retires because a later resolve
+       // may walk an older tree than this one did.
+       const size_t kernel_count = iors.size();
+       size_t added = 0;
+       for (const auto &cycle : m_cycles) {
+               const auto found = cycle.m_pending_refs.find(bytenr);
+               if (found == cycle.m_pending_refs.end()) {
+                       continue;
+               }
+               for (const auto &e : found->second) {
+                       const auto same = [&](const BtrfsInodeOffsetRoot &ior) {
+                               return ior.m_root == e.m_root && ior.m_inum == e.m_inum
+                                       && ior.m_offset == e.m_offset;
+                       };
+                       if (any_of(iors.begin(), iors.begin() + kernel_count, same)) {
+                               continue;
+                       }
+                       if (any_of(iors.begin() + kernel_count, iors.end(), same)) {
+                               continue;
+                       }
+                       iors.push_back(BtrfsInodeOffsetRoot{e.m_inum, e.m_offset, e.m_root});
+                       ++added;
+               }
+       }
+       return added;
+}
+
 void
 BeesVerificationTracker::on_transid_change(uint64_t transid, shared_ptr<BeesContext> ctx)
 {
@@ -1328,6 +1373,16 @@ BeesVerificationTracker::on_transid_change(uint64_t transid, shared_ptr<BeesCont
                cycle.m_extents.clear();
                cycle.m_locks.clear();
                cycle.m_owner = Task("queue_" + to_string(m_current), [](){});
+
+               // The references recorded into this slot were created by
+               // dedupes whose transactions have committed by now, so the
+               // kernel reports them itself; stop carrying them.
+               size_t expired = 0;
+               for (const auto &[bytenr, refs] : cycle.m_pending_refs) {
+                       expired += refs.size();
+               }
+               BEESCOUNTADD(pending_ref_expire, expired);
+               cycle.m_pending_refs.clear();
        }
 
        if (ready_extents.empty()) {
index d175cc186dc5ac94e140b5a9aa4ca9c8d9a0014f..e6cb9db9a669c590c6744252c294f2c8fd7f08da 100644 (file)
@@ -308,9 +308,9 @@ BeesBtrfsExtentLayer::refs_fetch(BeesBtrfsExtentNode &node) const
        // resolve.commit-root, and none when it fell back to the commit root
        // on its own.  The references this process created are on record;
        // union them in so the list is complete either way (see
-       // bees-pending-refs.h).
+       // bees-verification.h).
        vector<BtrfsInodeOffsetRoot> iors(lio->m_iors.begin(), lio->m_iors.end());
-       BEESCOUNTADD(refs_pending, m_ctx.pending_refs().merge_into(node.m_bytenr, iors));
+       BEESCOUNTADD(refs_pending, m_ctx.verification().merge_pending_refs(node.m_bytenr, iors));
        const auto count = iors.size();
        if (count == 0) {
                BEESCOUNT(refs_zero);
diff --git a/src/bees-pending-refs.cc b/src/bees-pending-refs.cc
deleted file mode 100644 (file)
index 4f49887..0000000
+++ /dev/null
@@ -1,90 +0,0 @@
-#include "bees-pending-refs.h"
-
-#include "bees.h"
-
-#include <algorithm>
-
-using namespace crucible;
-using namespace std;
-
-uint64_t
-BeesPendingRefs::add(uint64_t bytenr, uint64_t root, uint64_t inum,
-       uint64_t offset)
-{
-       unique_lock<mutex> lock(m_mutex);
-       m_by_bytenr[bytenr].push_back(Entry{root, inum, offset, m_epoch});
-       ++m_size;
-       BEESCOUNT(pending_ref_add);
-       return m_epoch;
-}
-
-size_t
-BeesPendingRefs::merge_into(uint64_t bytenr,
-       vector<BtrfsInodeOffsetRoot> &iors) const
-{
-       unique_lock<mutex> lock(m_mutex);
-       const auto found = m_by_bytenr.find(bytenr);
-       if (found == m_by_bytenr.end()) {
-               return 0;
-       }
-       // Both lists are short compared to a LOGICAL_INO buffer and the
-       // pending side is usually a few hundred entries at most, so a linear
-       // presence test over the kernel's answer is fine.  A pending entry the
-       // kernel already reports is one that has reached the tree it walked;
-       // it stays recorded until it expires because a later resolve may walk
-       // an older tree than this one did.
-       const size_t kernel_count = iors.size();
-       size_t added = 0;
-       for (const auto &e : found->second) {
-               const auto same = [&](const BtrfsInodeOffsetRoot &ior) {
-                       return ior.m_root == e.m_root && ior.m_inum == e.m_inum
-                               && ior.m_offset == e.m_offset;
-               };
-               if (any_of(iors.begin(), iors.begin() + kernel_count, same)) {
-                       continue;
-               }
-               if (any_of(iors.begin() + kernel_count, iors.end(), same)) {
-                       continue;
-               }
-               iors.push_back(BtrfsInodeOffsetRoot{e.m_inum, e.m_offset, e.m_root});
-               ++added;
-       }
-       return added;
-}
-
-void
-BeesPendingRefs::advance()
-{
-       unique_lock<mutex> lock(m_mutex);
-       ++m_epoch;
-       for (auto it = m_by_bytenr.begin(); it != m_by_bytenr.end(); ) {
-               auto &entries = it->second;
-               const auto keep_from = remove_if(entries.begin(), entries.end(),
-                       [&](const Entry &e) {
-                               return e.m_epoch + EXPIRE_EPOCHS <= m_epoch;
-                       });
-               const auto dropped = static_cast<size_t>(entries.end() - keep_from);
-               entries.erase(keep_from, entries.end());
-               m_size -= dropped;
-               BEESCOUNTADD(pending_ref_expire, dropped);
-               if (entries.empty()) {
-                       it = m_by_bytenr.erase(it);
-               } else {
-                       ++it;
-               }
-       }
-}
-
-uint64_t
-BeesPendingRefs::epoch() const
-{
-       unique_lock<mutex> lock(m_mutex);
-       return m_epoch;
-}
-
-size_t
-BeesPendingRefs::size() const
-{
-       unique_lock<mutex> lock(m_mutex);
-       return m_size;
-}
diff --git a/src/bees-pending-refs.h b/src/bees-pending-refs.h
deleted file mode 100644 (file)
index eedf1d8..0000000
+++ /dev/null
@@ -1,82 +0,0 @@
-#pragma once
-
-/// @file bees-pending-refs.h
-/// References bees created that a resolve cannot yet report.
-///
-/// A dedupe redirects a dst file range onto a src extent: the dst file gets
-/// a new EXTENT_DATA item naming the src.  Until the transaction that made
-/// it commits, that reference exists only in the running transaction.
-/// LOGICAL_INO answers from the commit root -- always with
-/// resolve.commit-root, and silently without it whenever the kernel cannot
-/// attach to a running transaction -- so a resolve of the src issued in that
-/// window omits every reference bees itself just put there.  A plan that
-/// later takes the src as a dst redirects only the references it can see,
-/// and the extent survives a dedupe that was supposed to free it.
-///
-/// This is the one class of missing reference bees cannot shrug off as
-/// churn, and the one it never needs to ask the kernel about: it made them.
-/// Each created reference is recorded against its src bytenr at dedupe time
-/// and unioned into every resolve of that bytenr until its transaction is
-/// known to have committed.
-///
-/// Expiry counts observed transid changes, not transid values.  The transid
-/// the crawl thread reads is the generation of the root-tree leaf holding
-/// one subvol's item, which moves only when an item in that leaf is
-/// rewritten: it can sit still for a dozen transactions and then jump, so
-/// arithmetic on its value would expire a fresh entry the moment the thread
-/// caught up.  Counting changes is immune to that.  An entry is stamped with
-/// the number of changes observed so far.  The first change observed after
-/// the add may be the thread catching up to a transid that was already
-/// running when the dedupe went in; every change after that is a transid
-/// the dedupe's transaction has been followed by.  A transaction is fully
-/// committed before the one after its successor can begin, so the third
-/// observed change proves the dedupe is in the commit root.  A fourth is
-/// margin.
-
-#include "crucible/fs.h"
-
-#include <cstdint>
-#include <map>
-#include <mutex>
-#include <vector>
-
-class BeesPendingRefs {
-public:
-       /// One reference bees created:  the dst file's new EXTENT_DATA item,
-       /// keyed as LOGICAL_INO reports it, and the observed-change count when
-       /// the dedupe that made it ran.
-       struct Entry {
-               uint64_t m_root;
-               uint64_t m_inum;
-               uint64_t m_offset;
-               uint64_t m_epoch;
-       };
-
-       /// Observed transid changes an entry survives.  See the file comment.
-       static constexpr uint64_t EXPIRE_EPOCHS = 4;
-
-       /// Record a reference created onto @p bytenr, stamped with the current
-       /// epoch.  Returns the stamp.
-       uint64_t add(uint64_t bytenr, uint64_t root, uint64_t inum, uint64_t offset);
-
-       /// Append to @p iors every recorded reference to @p bytenr that it does
-       /// not already contain.  Returns the number appended.
-       size_t merge_into(uint64_t bytenr,
-               std::vector<crucible::BtrfsInodeOffsetRoot> &iors) const;
-
-       /// A transid change has been observed:  advance the epoch and drop
-       /// every entry whose transaction must have committed by now.
-       void advance();
-
-       /// Observed transid changes so far.
-       uint64_t epoch() const;
-
-       /// Entries currently held, across all bytenrs.
-       size_t size() const;
-
-private:
-       mutable std::mutex m_mutex;
-       std::map<uint64_t, std::vector<Entry>> m_by_bytenr;
-       size_t m_size = 0;
-       uint64_t m_epoch = 0;
-};
index 643aa794998cc7566eb9ac587aa58e0d07abcf99..75f1a4db8d360a9f87ff10c6da39808727a3e11b 100644 (file)
@@ -2687,11 +2687,9 @@ BeesRoots::crawl_thread()
                        // Always run this even if we have no worker threads.
                        clear_caches();
 
-                       // Our own dedupes' references from far enough back are in
-                       // the commit root now; stop carrying them.
-                       m_ctx->pending_refs().advance();
-
-                       // Rotate verification pipelines and dispatch any ready batch.
+                       // Rotate verification pipelines and dispatch any ready
+                       // batch; the retiring slot's record of our own dedupes'
+                       // references goes with it.
                        m_ctx->verification().on_transid_change(new_transid, m_ctx);
 
                        // Insert new roots and restart crawl_more.
index 9050c417606bf411fe12f1988bc093e5caa5de27..ce939c6a27360d75178165aaebfb0001337bb21c 100644 (file)
 /// authoritative guard: a planner that tries to acquire an extent whose
 /// Exclusion is held by a cycle owner will be rescheduled via Borrower::Dead
 /// and will retry after verification completes.
+///
+/// The same ring carries the references bees created that a resolve cannot
+/// yet report.  A dedupe redirects a dst file range onto a src extent: the
+/// dst file gets a new EXTENT_DATA item naming the src.  Until the
+/// transaction that made it commits, that reference exists only in the
+/// running transaction, and LOGICAL_INO answers from the commit root --
+/// always with resolve.commit-root, and silently without it whenever the
+/// kernel cannot attach to a running transaction -- so a resolve of the src
+/// issued in that window omits every reference bees itself just put there.
+/// A plan that later takes the src as a dst redirects only the references
+/// it can see, and the extent survives a dedupe that was supposed to free
+/// it; a ref-count gate sees too few references and lets a plan through
+/// that the true count would have stopped.  This is the one class of
+/// missing reference bees cannot shrug off as churn, and the one it never
+/// needs to ask the kernel about: it made them.  Each created reference is
+/// recorded against its src bytenr in the current slot, keyed as
+/// LOGICAL_INO reports it, and unioned into every resolve of that bytenr.
+/// When the slot retires -- the same loop.verify-delay transid changes
+/// later that let a dst be checked for deletion -- the dedupe's transaction
+/// is in the commit root and the record is dropped.
+///
+/// Expiry counts observed transid changes, not transid values.  The transid
+/// the crawl thread reads is the generation of the root-tree leaf holding
+/// one subvol's item, which moves only when an item in that leaf is
+/// rewritten: it can sit still for a dozen transactions and then jump, so
+/// arithmetic on its value would expire a fresh entry the moment the thread
+/// caught up.  Rotating a ring on each change is immune to that.
 
 #include "bees-borrower.h"
 #include "bees-extent.h"
 
 #include "crucible/error.h"
+#include "crucible/fs.h"
 #include "crucible/task.h"
 #include "crucible/time.h"
 
 #include <list>
+#include <map>
 #include <mutex>
 #include <vector>
 #include <cmath>
@@ -66,12 +95,25 @@ using namespace std;
 /// planner threads.  on_transid_change() is called from the single crawl
 /// monitoring thread.
 class BeesVerificationTracker {
+public:
+       /// One reference bees created:  the dst file's new EXTENT_DATA item,
+       /// keyed as LOGICAL_INO reports it.
+       struct PendingRef {
+               uint64_t m_root;
+               uint64_t m_inum;
+               uint64_t m_offset;
+       };
+
+private:
        /// One transid interval's worth of recorded extents, their Exclusion
        /// locks, and the single cycle owner Task that holds those locks.
        struct Cycle {
                list<BeesExtent>    m_extents;
                list<ExclusionLock> m_locks;
                Task                m_owner;
+               /// References created by dedupes that ran during this slot,
+               /// keyed by the src bytenr they were created onto.
+               map<uint64_t, vector<PendingRef>> m_pending_refs;
        };
 
        mutable mutex       m_mutex;
@@ -140,4 +182,13 @@ public:
        /// scope.  @p ctx is captured by value (shared_ptr) so BeesContext
        /// outlives the Task.
        void on_transid_change(uint64_t transid, shared_ptr<BeesContext> ctx);
+
+       /// Record a reference a dedupe just created onto @p bytenr, in the
+       /// slot currently being filled.  Dropped when that slot retires.
+       void record_pending_ref(uint64_t bytenr, uint64_t root, uint64_t inum, uint64_t offset);
+
+       /// Append to @p iors every recorded reference to @p bytenr, in any
+       /// slot, that it does not already contain.  Returns the number
+       /// appended.
+       size_t merge_pending_refs(uint64_t bytenr, vector<BtrfsInodeOffsetRoot> &iors) const;
 };
index a9adc2932433b73f2c1a83c38369c69e577717e2..bab9f013dbbc40e2c6cf1f765cdd530b63801919 100644 (file)
@@ -11,7 +11,6 @@
 #include "bees-lib.h"
 #include "bees-log.h"
 #include "bees-reporter.h"
-#include "bees-pending-refs.h"
 #include "bees-verification.h"
 
 #include "crucible/btrfs-tree.h"
@@ -1609,7 +1608,6 @@ private:
        NamedPtr<Exclusion, uint64_t>                   m_extent_locks;  ///< Per-physical-extent mutex pool.
        NamedPtr<Exclusion, uint64_t>                   m_inode_locks;   ///< Per-inode mutex pool.
        shared_ptr<BeesVerificationTracker>             m_verification;  ///< Delayed verification for purportedly deleted extents; built from loop.verify-delay in set_config().
-       BeesPendingRefs                                 m_pending_refs;  ///< References our own dedupes created that a resolve may not yet report.
 
        /// Planner cost benchmark: counts (Σ block-map regions over the start
        /// extent and all its candidates) against the time from plan start to
@@ -1716,7 +1714,6 @@ public:
        /// has constructed it from loop.verify-delay.
        BeesVerificationTracker &verification() { return *m_verification; }
        /// References this process created that a resolve may not yet report.
-       BeesPendingRefs &pending_refs() { return m_pending_refs; }
 
        /// Return the planner cost-vs-region-count benchmark heatmap.
        BeesHeatmap &plan_regions_heatmap() { return m_plan_regions_heatmap; }
index 02058592efd9d6db97e739d0c9ca49b78dec5d99..d079be84ffb6bfafc90318e73f8eda5b5309d122 100644 (file)
@@ -52,7 +52,6 @@ REPL_OBJS = \
        ../src/bees-scan-next.o \
        ../src/bees-lib.o \
        ../src/bees-log.o \
-       ../src/bees-pending-refs.o \
        ../src/bees-fdcache.o \
        ../src/bees-filter.o \
        ../src/bees-filter-context.o \