]> git.hungrycats.org Git - bees/commitdiff
thread: add workaround-clone-logical-ino config option
authorZygo Blaxell <bees@furryterror.org>
Wed, 24 Jun 2026 15:16:56 +0000 (11:16 -0400)
committerZygo Blaxell <bees@furryterror.org>
Tue, 6 Oct 2026 05:51:40 +0000 (01:51 -0400)
The dedupe (clone) ioctl and LOGICAL_INO must not run concurrently on
some kernels, so bees serializes them through MultiLocker.  This was
hardcoded on via MultiLocker::enable_locking(true) in bees_main.

Expose the behaviour as a boolean [thread] option,
workaround-clone-logical-ino, defaulting to yes (the prior hardcoded
behaviour).  When set to no, locking is disabled and any thread may run
either operation at any time, which is faster but unsafe on affected
kernels.  bees_main now passes the configured value straight to
enable_locking().

The option is consumed once at startup and handed to a static method, so
it needs no member in BeesContext or BeesRoots.  Document it in the
built-in config and docs/config-file.md.

Assisted-by: Claude-Code:claude-opus-4-8
docs/config-file.md
src/bees-config-v2.cc
src/bees.cc

index 20f4a6ff4a12223a5ba5272c2b64e278cdd00616..2e6de87f93e40ce5c1fbf4636afc9abe983208f0 100644 (file)
@@ -718,6 +718,16 @@ The `[thread]` section sets how many worker threads bees runs and how aggressive
 
   Default: `9999`.
 
+* **`workaround-clone-logical-ino`**
+  Whether to serialize the dedupe (clone) ioctl against the `LOGICAL_INO` ioctl to avoid a btrfs kernel bug that can be triggered when both run concurrently.
+
+  * `yes` (the default) prevents any thread from running dedupe while another thread is running `LOGICAL_INO`, and vice versa.  The two ioctls never overlap.
+  * `no` removes the restriction: any thread may run either operation at any time.  This is faster under high concurrency but unsafe on kernels affected by the bug.
+
+  Leave this enabled unless you have confirmed your kernel is not affected.
+
+  Default: `yes`.
+
 ## [throttle] section
 
 The [throttle] section helps manage btrfs commit latency by injecting intentional delays between system calls that queue delayed references (refs).  Instead of submitting as many commands as possible and waiting for the queue to drain, this option queues commands at the **average rate** at which they are processed.  This can improve system responsiveness and stabilize IO latency, particularly for write operations.
index 63c52f091e6044f4b71c9807903914b5c40970b1..889a327ebac3c8832afeadc2be555d18cba37f18 100644 (file)
@@ -34,6 +34,15 @@ static const char bees_config_v2[] = R"--v2-config--(
         # Config version (number) or alias (STABLE, CURRENT, v0.11).
         version = 2
 
+[thread]
+
+        # Serialize the dedupe ioctl against LOGICAL_INO to avoid a kernel
+        # bug triggered when both run concurrently.  yes: no thread runs
+        # dedupe while another runs LOGICAL_INO (and vice versa).  no: any
+        # thread may run either operation at any time (faster, but unsafe
+        # on affected kernels).
+        workaround-clone-logical-ino = yes
+
 
 # The [resolve] section controls how bees maps physical addresses back to
 # the files that reference them.
index 86440afec0d4459bfe7fd2570a61bc14e6ff56aa..319d64fe7d876d25bbc58d863d6bbb2a67cd22bf 100644 (file)
@@ -714,8 +714,11 @@ bees_main(int argc, char *argv[])
                        bc->get_config().get("state.point.defer", bees_parse_bool));
        }
 
-       // Workaround for the logical-ino-vs-clone kernel bug
-       MultiLocker::enable_locking(true);
+       // Workaround for the logical-ino-vs-clone kernel bug: serialize the
+       // dedupe ioctl against LOGICAL_INO unless the operator opts out.
+       const bool workaround_clone_logical_ino = bc->get_config().get("thread.workaround-clone-logical-ino", bees_parse_bool);
+       BEESLOGINFO("thread.workaround-clone-logical-ino = " << (workaround_clone_logical_ino ? "yes" : "no") << " [thread.workaround-clone-logical-ino]");
+       MultiLocker::enable_locking(workaround_clone_logical_ino);
 
        // Start crawlers
        bc->start();