single extent, biasing the planner against dedupes that move a large
reference cluster for little physical gain — a brake on the reference-cluster
growth that low reference limits can otherwise cause.
+ * A non-zero value also makes the planner consolidate duplicates onto a
+ canonical extent. When several source extents match a destination equally
+ well, it prefers the source that already has the most references, and it
+ re-centers a set of whole-extent duplicates on the most-referenced one, so
+ references gather in a star topology instead of spreading across arbitrary
+ sources. `0` spreads them (the historical behavior). Consolidation is
+ tied to this option because only a non-zero `ref-op-cost` bounds the
+ reference movement it drives: unpriced, references pile onto canonical
+ extents up to `refs-max` and re-canonicalize along a chain.
* Default: `53`, the same as `ref-cost` (config version 1 and `v0.11`: `0`,
which disables the term).
* Accepts a [size value](config-format.md#size-values).
* Default: `1.0`.
* Accepts a [ratio value](config-format.md#ratio-values) (e.g. `1.0`, `50%`).
-* **`prefer-canonical-src`**
- When several source extents match a destination equally well — they cover the
- same span, so the choice between them does not change the plan's cost — prefer
- the source that already has the most references. This consolidates duplicates
- onto a single canonical extent (a star topology) rather than spreading them
- across arbitrary sources; when off, the first equally-good source is used and
- references spread out (the historical behavior).
- * Only safe with a non-zero [`ref-op-cost`](#rewrite-section). Consolidation
- concentrates references onto a few extents, and `ref-op-cost` is what prices
- — and therefore bounds — the reference movement that concentration drives.
- With `ref-op-cost = 0` there is no such bound: references pile onto canonical
- extents up to `refs-max` and re-canonicalize along a chain, doing far more
- reference-rewriting work than spreading them would. Enable this only
- together with a non-zero `ref-op-cost`.
- * Default: `yes`.
- * Accepts a [boolean value](config-format.md#boolean-values).
-
* **`plan-max-vertices`**
Boundary-vertex budget for the shortest-path coverage search. The exact
search is O(V²) in the boundary count V (the distinct match endpoints of a
prices). `0` when the term is disabled or no destination reference
shares metadata pages.
* `pivot` — present when this destination belongs to a re-centered plan: with
- `rewrite.prefer-canonical-src`, the dedupe star was pivoted onto a
+ a non-zero `rewrite.ref-op-cost`, the dedupe star was pivoted onto a
higher-reference whole-extent duplicate, so this destination (possibly the
scanned extent itself) is being deduped onto that canonical rather than the
scanned extent surviving as the source.
# Space-debt weight per reference a plan rewrites (every dedupe/copy
# FILE_EXTENT_SAME, including whole-extent dedupes ref-cost ignores).
- # Size value in bytes; 0 disables. See docs/config-file.md.
+ # Size value in bytes; 0 disables. Non-zero also prefers the
+ # most-referenced source on equal-length matches.
+ # See docs/config-file.md.
ref-op-cost = 0
# Expected ratio of subvol metadata sharing between snapshots.
# 0 disables. See docs/config-file.md.
snapshot-sharing = 1.0
- # Prefer the most-referenced source on equal-length dedupe matches, to
- # consolidate duplicates onto a canonical extent. Boolean; only safe
- # with a non-zero ref-op-cost. See docs/config-file.md.
- prefer-canonical-src = yes
-
# Boundary-vertex budget for the coverage search. Above this V the
# planner uses a linear greedy cover instead of the O(V^2) exact
# search. Integer count, or unlimited to disable the fallback.
# Percentage with %, or a size value (e.g. 128K, 1M - 4K).
free-min = 128K
- # Space-debt weight per reference a plan rewrites. Prices the
- # reference movement that prefer-canonical-src drives.
+ # Space-debt weight per reference a plan rewrites. Non-zero also
+ # consolidates duplicates onto the most-referenced source.
ref-op-cost = 53
# The [resolve] section controls how bees maps physical addresses back to
rv.m_inode_locking = load("rewrite.inode-locking", bees_parse_bool);
rv.m_keep_older = load("rewrite.keep-older", bees_parse_bool);
rv.m_keep_newer = load("rewrite.keep-newer", bees_parse_bool);
- rv.m_prefer_canonical_src = load("rewrite.prefer-canonical-src", bees_parse_bool);
+ // Consolidating onto the most-referenced source is only safe when
+ // ref-op-cost prices the reference movement it drives.
+ rv.m_prefer_canonical_src = rv.m_ref_op_cost > 0;
{
BEESTRACE("loading rewrite.read-size");
rv.m_read_size = get("rewrite.read-size", bees_parse_size);
std::ostream &print(std::ostream &os) const override;
/// Re-center the dedupe star on the highest-reference whole-extent
- /// duplicate when prefer-canonical-src is set (see the definition); a no-op
+ /// duplicate when ref-op-cost > 0 (see the definition); a no-op
/// otherwise. Runs once after the candidate loop, before selection.
void finalize() override;
for (const auto &match : group.m_matches) {
if (match.size() == 0) continue;
// Carry the src ref count as the search's equal-reach tie-break
- // (rewrite.prefer-canonical-src): prefer consolidating onto the
+ // (rewrite.ref-op-cost > 0): prefer consolidating onto the
// higher-ref, canonical src. When disabled leave it 0, which the
// search reads as "no preference" (ties resolve as before) and
// also skips the refs() lookup. The lookup is layer-cached; the
/// paying the snapshot term are greppable; 0 when the term is off or
/// no dst ref shares metadata pages.
uint64_t m_sel_snap_extra = 0;
- /// True when this dst belongs to a re-centered Plan B (prefer-canonical-src
+ /// True when this dst belongs to a re-centered Plan B (ref-op-cost > 0
/// pivoted the star onto a higher-ref whole-extent duplicate, so this dst —
/// possibly the former start — is deduped onto that canonical). Logged as a
/// "pivot" tag on the "plan:" line so re-centered plans are greppable.
bool m_whole_extent = false;
};
std::deque<Entry> m_entries;
- /// Set by finalize() (prefer-canonical-src) when a whole-extent candidate
+ /// Set by finalize() (ref-op-cost > 0) when a whole-extent candidate
/// outranks the start on reference count: the plan re-centers the dedupe
/// star on that candidate, the start joins the destinations, and every
/// destination dedupes onto this center instead of the start. Empty means
void
BeesStartAsSrcPlan::finalize()
{
- // prefer-canonical-src: if a whole-extent-duplicate candidate holds more
+ // ref-op-cost > 0: if a whole-extent-duplicate candidate holds more
// references than the start, re-center the dedupe star on it. Centering on
// the highest-reference member minimizes the references the plan moves
// (every other member's references move onto the center), and for a set of
{
// Return the src only when the plan has accepted at least one dst. The src
// is the start, unless finalize() re-centered the star on a higher-ref
- // whole-extent candidate (prefer-canonical-src), in which case the start is
+ // whole-extent candidate (ref-op-cost > 0), in which case the start is
// a dst and that candidate is the sole src.
if (m_impl->m_entries.empty()) {
return {};
}
const auto &start = pb->start();
- // prefer-canonical-src re-centered the star on a higher-ref whole-extent
+ // ref-op-cost > 0 re-centered the star on a higher-ref whole-extent
// duplicate (finalize()): the center is the sole src; the start and the
// remaining candidates are the dsts. The center is byte-identical to
// the start over the whole extent, so a dst's match against the start
/// arbitrary one; off spreads references across sources (the historical
/// behavior). Consolidating is only safe when reference moves are priced:
/// with rewrite.ref-op-cost = 0 it concentrates references onto a few
- /// extents with nothing to bound the resulting re-canonicalization, so pair
- /// it with a non-zero ref-op-cost. Authoritative default in
- /// bees-config-v2.cc; the C++ initializer (false) is only the pre-load
- /// value (a bool has no invalid sentinel — see code that sets it).
+ /// extents with nothing to bound the resulting re-canonicalization. Not
+ /// a config key: derived from ref-op-cost > 0 when the policy is loaded.
bool m_prefer_canonical_src = false;
/// Boundary-vertex budget for the shortest-path coverage search.
/// The exact search is O(V^2) in the boundary count V and holds the