them with a `vrange` filter, leaving the remaining filter parameters
unmodified. Before the balance item is written, the vrange filter of
each chunk type is limited to the addresses below the next chunk to be
-allocated (a 0..end range when the request had no vrange, or a lower end
-on the vrange supplied by userspace). Every block group that existed
-when the balance started stays selected until the balance relocates it.
+allocated (a 0..end range when the request had no vrange, or the end of
+the vrange supplied by userspace, lowered to that address if it is
+higher). Every block group that existed when the balance started stays
+selected until the balance relocates it.
New chunks are normally allocated after the last chunk, but relocating the
highest chunk into free space lower down deletes it without allocating
anything, and the next chunk would then reuse its address below the
bound, where a resumed balance would select it again. To prevent this,
-while a balance item exists, find_next_chunk() never allocates below
-the vrange upper bound.
+while a balance item exists, find_next_chunk() never returns an address
+below the vrange upper bound.
The upper bound never moves, so there is no progress to track or persist.
There's no new on-disk state and no balance item updates during the
On resume, the balance loop revisits only the chunks it left in place
above the point where it stopped (filtered out, ENOSPC, active swapfile)
-and checks them against the filters again. Nothing is skipped, and
-nothing is repeated except the lightweight filter check.
+and checks them against the filters again. Nothing is skipped, and no
+completed block group is repeated.
The vrange filter has been present in btrfs since balance filters were
introduced in 2012, so there is no compatibility issue arising from
A balance item written by an older kernel has no vrange, so with patch
2, a balance that starts on an old kernel and resumes on a new kernel
restarts from the beginning, redoing much of the work already done.
-That behavior may be an unpleasant surprise for some users, so when there
-is no `vrange` filter, patch 3 resumes exactly those items with the old
+That behavior may be an unpleasant surprise for some users, so for each
+chunk type without a `vrange` filter, patch 3 resumes with the old
usage=90 and convert-soft heuristics. The cost is keeping a layer of
surprising behavior and code in the kernel to avoid a one-time issue
that affects few users, is relatively easy to recover from, and will