]> git.hungrycats.org Git - bees/commitdiff
hash: add state.hash.randomize-lru config option
authorZygo Blaxell <bees@furryterror.org>
Mon, 25 May 2026 22:45:20 +0000 (18:45 -0400)
committerZygo Blaxell <bees@furryterror.org>
Tue, 6 Oct 2026 05:51:40 +0000 (01:51 -0400)
The push_random_hash_addr* methods insert new (not-yet-duplicate)
hashes at a random position in the per-bucket LRU list.  This spreads
evictions so that new hashes don't uniformly evict every old hash, but
it also makes the hash table's contents depend on a per-thread PRNG,
so two runs over identical input diverge.

Hash lifetime is better solved at hash insertion time, when the entropy
of the hashes themselves can act as a deterministic PRNG, and we get more
direct control of how many hashes survive from each extent.  That change
is not included here, but the benefit for deterministic testing is enough
to bring this change forward.

Add state.hash.randomize-lru (default yes, preserving current behavior).
When set to no, the random-insert methods force the insertion position to
0, i.e. insert at the LRU front and evict from the back.  Combined with
thread.thread-max = 1 this removes the last source of nondeterminism in
hash-table eviction, so repeated runs over the same filesystem produce
the same dedupe result -- useful for reproducible performance analysis
where randomized-eviction variance would otherwise mask the effect being
measured.

Document it in bees-config-v1.cc and docs/config-file.md.

Assisted-by: Claude-Code:claude-opus-4-7
Signed-off-by: Zygo Blaxell <bees@furryterror.org>
docs/config-file.md
src/bees-config-v1.cc
src/bees-hash.cc
src/bees.cc
src/bees.h

index ce58ee9e6a52826cb121b17c919e40aeb056480d..1fcaa859b2cc8cad551b4d9e046ba208cea348d4 100644 (file)
@@ -531,6 +531,23 @@ may create or resize it, and how aggressively it is written back to disk.
     manager that may immediately power down or unmount the filesystem
     after bees exits.
 
+### Eviction
+
+* **`randomize-lru`**
+  Insert new (not-yet-duplicate) hashes at a random position in the
+  per-bucket LRU list rather than always at the front.
+  * `yes` (default) — each insert picks a random slot in the bucket.
+    Randomizing the insertion point spreads evictions out so that new
+    reads do not systematically evict older inserts, which keeps hit
+    rates higher when all hashes are inserted from each extent.
+  * `no` — insert at the LRU front only (most-recently-used position),
+    evicting from the back.  This removes the per-insert randomness, so
+    that — combined with `thread.thread-max = 1` — hash-table eviction
+    is deterministic from one run to the next.  Useful for reproducible
+    performance analysis, where run-to-run variance from randomized
+    eviction would otherwise mask the effect being measured.  Also
+    useful when combined with controls on insert-time block counts.
+
 ## [state.point] section
 
 The `[state.point]` section configures `beespoint.ini`: how often the crawl
index a06d65fdb11569ef4e2ef290377fec82abf74108..15a55020e65f790b3a59a493da361c22f9aad768 100644 (file)
@@ -351,6 +351,10 @@ static const char bees_config_v1[] = R"--v1-config--(
         # fsync the hash table file when bees exits.
         close-fsync = no
 
+        # Insert new hashes at a random position in the per-bucket
+        # LRU list.  Set to no to insert at the LRU front only.
+        randomize-lru = yes
+
 # The [state.point] section controls crawl checkpoint options.
 
 [state.point]
index 3dd4f0b18e8951c58075df182e5d9c5dbdf92463..46123ceb525acd4775d3e74679328f34e4902d23 100644 (file)
@@ -651,7 +651,7 @@ BeesHashTable::push_random_hash_addr(HashType hash, AddrType addr)
        Cell *ip = find(er.first, er.second, mv);
        bool found = (ip < er.second);
 
-       const auto pos = tl_distribution(bees_generator);
+       const size_t pos = m_randomize_lru ? tl_distribution(bees_generator) : 0;
 
        int case_cond = 0;
 #if 0
@@ -1029,6 +1029,13 @@ BeesHashTable::set_close_fsync(bool v)
        BEESLOGINFO("state.hash.close-fsync = " << (v ? "yes" : "no") << " [state.hash.close-fsync]");
 }
 
+void
+BeesHashTable::set_randomize_lru(bool v)
+{
+       m_randomize_lru = v;
+       BEESLOGINFO("state.hash.randomize-lru = " << (v ? "yes" : "no") << " [state.hash.randomize-lru]");
+}
+
 void
 BeesHashTable::resize_file(off_t new_size_signed)
 {
index a3352d2cbd94f10a55b846ac290117e15935cd35..9fc7e745e8545a0e3b2ee60b335d45106ee8c3ad 100644 (file)
@@ -593,6 +593,9 @@ bees_main(int argc, char *argv[])
                        BEESLOGINFO("state.hash: effective writeback rate = " << pretty(static_cast<uint64_t>(effective_rate)) << "/s");
                        ht->set_flush_rate(effective_rate);
                }
+               // LRU randomization applies to both file-backed and in-memory
+               // tables (it governs insert position, not file I/O).
+               bc->hash_table()->set_randomize_lru(bc->get_config().get("state.hash.randomize-lru", bees_parse_bool));
                bc->start_hash_writeback();
 
                // Crawl checkpoint options
index b54ce468264d8557a6bbb557f65f39d03bc8e8e2..04cac36953545d7a6549875c04bbb51ce932d9f3 100644 (file)
@@ -804,6 +804,10 @@ public:
        void set_writeback_unreadahead(bool v);
        /// fsync the hash table on close (at bees termination only).
        void set_close_fsync(bool v);
+       /// If false, push_random_hash_addr* insert at the LRU front instead of
+       /// a random position.  Combined with thread.thread-max = 1 this makes
+       /// hash-table eviction deterministic for performance analysis.
+       void set_randomize_lru(bool v);
 
 private:
        string          m_filename;
@@ -852,6 +856,7 @@ private:
        bool                    m_writeback_fsync = false;
        bool                    m_writeback_unreadahead = false;
        bool                    m_close_fsync = false;
+       bool                    m_randomize_lru = true;
 
        /// Configured state.hash.size, captured in init() before set_resize()
        /// has been called.  prepare_in_memory() compares this against the