Expand description
How many bytes a claimed directory is worth, and why a normal scan does not ask.
§The default is not to measure
Prune-on-match is the whole performance thesis, and a recursive measurement would undo it:
sizing node_modules means enumerating the tens of thousands of inodes the scan just
declined to walk. So a normal scan records the claim and reports Size::Unmeasured. The
traversal happens only under SizeMode::Breakdown, which is what “the user asked for a
breakdown” compiles down to.
§Why not the directory’s own block accounting
The concept doc asked for “sizes from the directory’s own block accounting where the
platform offers it”. No platform pristine targets offers a recursive one. A directory
inode’s block count on APFS, ext4, btrfs and ZFS alike describes the directory’s own entry
table, not the tree beneath it — which is why du walks. Reporting it as the claim’s size
would call a 40 GB node_modules about 48 KB, so the honest answer is Unmeasured rather
than a number that is wrong by six orders of magnitude.
A claim that is a symlink — Bazel’s bazel-* — is different: lstat is the complete
answer for a link in constant time, so those are measured even in the default mode.
When a breakdown is asked for, the subtree goes through the tight read_dir + lstat
loop below rather than back through the scan that found it: no ignore stack, no rule
evaluation, no path bookkeeping, one pass, on the walker thread that found the claim.
Bytes are allocated blocks rather than apparent length, because allocated is what
deleting gives back.
§The one thing a default scan does have to look at
Tier two cannot claim a directory without walking it. Its size floor cannot be inferred, and
neither can “holds no git repository” — which is a negative, and a negative is only proved
by covering everything. So Measurer::survey walks in every mode, and tier-two claims
carry a real size even on a default scan while tier-one claims do not.
That is a smaller dent in the performance thesis than it sounds. For a candidate that is
claimed, the survey replaces work the walk would have done anyway — the walker would have
descended into all of it — with the same tight loop and no ignore stack or rule evaluation
per entry. The cost is in the candidates that are refused, which get surveyed and then
walked. Over ~/repos: 2.9 s with tier two off, 4.1 s with it on, for 75 tier-two claims
that arrive priced.
Structs§
- Measurement
- The result of measuring one directory.
- Measurer
- Measures directories under a fixed policy.
- Survey
- Everything one pass over a tier-two candidate found.
Enums§
Constants§
- UNPRICED
- What an unpriced row shows instead of a number.
Functions§
- human
- Bytes in the units a person reads, binary because that is what the sizes are.