The `[resolve]` section controls how bees maps a physical btrfs address back to the files that reference it, using the `LOGICAL_INO_V2` ioctl.
* **`commit-root`**
- Resolve references against the filesystem's commit roots instead of the live tree. Default: `no`.
+ Resolve references against the filesystem's commit roots instead of the live tree. Default: `yes`.
With `no`, the kernel walks the running transaction's trees, so the reference list reflects the filesystem as it is at the moment of the call. To keep that view consistent, the kernel holds a tree mod log sequence for the whole duration of the walk. While any sequence is live, every node-level change anywhere on the filesystem is journalled into unreclaimable slab, and the journal is only trimmed below the oldest live sequence. Walks of heavily-shared extents take the longest and therefore hold a sequence the longest, which is also when other work — balance, snapshot deletion — is most likely to be generating tree changes to journal.
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 created since the last commit are invisible. bees is built to survive a stale answer — 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 — but surviving a stale answer is not the same as being unaffected by one. 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.
- On a mixed real-data corpus, `yes` recovered less space and took longer to converge than `no`, despite each individual resolve being substantially cheaper. The option exists mainly so the two can be compared on a single kernel, on a specific workload, without rebuilding.
+ The option exists so the two can be compared on a single kernel, on a specific workload, without rebuilding.
- Kernels that do not implement commit-root resolution reject the request once with `EINVAL`; bees logs a warning and falls back to live-root walks for the rest of the run, so setting `yes` on such a kernel is harmless.
+ Kernels that do not implement commit-root resolution reject the request once with `EINVAL`; bees logs a warning and falls back to live-root walks for the rest of the run, so the default is harmless on such a kernel.
- Example — resolve against the commit roots:
+ Example — resolve against the live tree instead:
```ini
[resolve]
- commit-root = yes
+ commit-root = no
```
## [scan.subvol] section
[resolve]
# Resolve references against the commit roots instead of the live
- # tree. yes: answers come from the last committed transaction and
- # may be up to one transaction stale, and the kernel holds no tree
- # mod log sequence for the walk. no (default): answers reflect the
- # running transaction. Ignored by kernels without the flag.
- # See docs/config-file.md for the tradeoff.
- commit-root = no
+ # tree. yes (default): answers come from the last committed
+ # transaction and may be up to one transaction stale, and the
+ # kernel holds no tree mod log sequence for the walk. no: answers
+ # reflect the running transaction. Ignored by kernels without the
+ # flag. See docs/config-file.md for the tradeoff.
+ commit-root = yes
)--v2-config--";
// Inherits from the schema that reproduces v0.11 behaviour; see the file
// rather than errors -- but tolerating it is not the same as being
// unaffected by it.
//
- // Measured on a mixed real-data corpus, asking for the commit root
- // recovered less space and took longer to converge, so it is off by
- // default. The knob exists so the two can be compared on one kernel.
+ // On by default; the knob exists so the two can be compared on one
+ // kernel.
//
// Kernels that do not implement the flag reject it once with EINVAL,
// after which libcrucible stops setting it.