]> git.hungrycats.org Git - linux/commitdiff
reclaim-fixes: new topic (candidate: cover, patches, TESTING.md)
authorZygo Blaxell <ce3g8jdj@umail.furryterror.org>
Wed, 28 Oct 2026 07:32:05 +0000 (03:32 -0400)
committerZygo Blaxell <ce3g8jdj@umail.furryterror.org>
Wed, 28 Oct 2026 07:32:05 +0000 (03:32 -0400)
The generic block group reclaim fixes split out of topics/stripe-alloc by
the sa-fold rework, exported from refs/cand/sa-fold/mn/reclaim.  Not
promoted; export.sh not run.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
topics/reclaim-fixes/0000-cover-letter.patch [new file with mode: 0644]
topics/reclaim-fixes/0001-btrfs-do-not-reclaim-block-groups-on-an-errored-file.patch [new file with mode: 0644]
topics/reclaim-fixes/0002-btrfs-log-block-group-reclaim-at-debug-level.patch [new file with mode: 0644]
topics/reclaim-fixes/0003-btrfs-back-off-block-group-reclaim-after-repeated-EN.patch [new file with mode: 0644]
topics/reclaim-fixes/0004-btrfs-let-queued-exclusive-operations-in-between-blo.patch [new file with mode: 0644]
topics/reclaim-fixes/TESTING.md [new file with mode: 0644]

diff --git a/topics/reclaim-fixes/0000-cover-letter.patch b/topics/reclaim-fixes/0000-cover-letter.patch
new file mode 100644 (file)
index 0000000..d47228e
--- /dev/null
@@ -0,0 +1,55 @@
+From 9a8bd47b0b9960efa030c57f1023211634ee9fea Mon Sep 17 00:00:00 2001
+From: Zygo Blaxell <ce3g8jdj@umail.furryterror.org>
+Date: Wed, 28 Oct 2026 03:31:36 -0400
+Subject: [PATCH 0/4] btrfs: block group reclaim fixes for a full filesystem
+To: linux-btrfs@vger.kernel.org
+
+Four small fixes to the background block group reclaim worker
+(btrfs_reclaim_bgs_work()).  None depends on a particular allocator; they
+were found while running stripe-exclusive raid56 allocation, whose trapped
+space keeps the reclaim list full at the fill edge, but each applies to
+any filesystem whose reclaim keeps failing or keeps running.
+
+Patch 1 skips reclaim on an errored filesystem: every transaction the
+worker starts there fails with -EROFS, yet it holds reclaim_bgs_lock,
+sb_writers and the balance exclusive operation while it fails.
+
+Patch 2 logs the start and end of each reclaim at debug level, so a
+kernel log can say which groups reclaim moved and when (the info message
+was removed as spam in a507904090d0).
+
+Patch 3 backs off after three -ENOSPC reclaims in a row in a space_info,
+until ten minutes pass, a chunk is added or removed, or free space grows
+by what the last failed group held.  Without it, a full filesystem
+retries forever while holding the balance exclusive operation.
+
+Patch 4 releases the balance exclusive operation between groups and
+leaves a 12 s gap while groups remain queued, so a resize, replace or
+balance queued with btrfs-progs --enqueue gets in at the next hand-off
+instead of waiting out the whole list.  The gap length follows from
+btrfs-progs' randomized re-check after the sysfs notification; the commit
+message has the numbers.
+
+Patches 3 and 4 add sysfs counters and debug lines only; nothing changes
+on a filesystem where reclaim succeeds and nobody waits for the exclusive
+operation.
+
+Zygo Blaxell (4):
+  btrfs: do not reclaim block groups on an errored filesystem
+  btrfs: log block group reclaim at debug level
+  btrfs: back off block group reclaim after repeated ENOSPC
+  btrfs: let queued exclusive operations in between block group reclaims
+
+ fs/btrfs/block-group.c | 148 +++++++++++++++++++++++++++++++++++++++--
+ fs/btrfs/block-group.h |   1 +
+ fs/btrfs/fs.c          |  29 ++++++++
+ fs/btrfs/fs.h          |  16 +++++
+ fs/btrfs/space-info.h  |  17 +++++
+ fs/btrfs/sysfs.c       |   2 +
+ 6 files changed, 208 insertions(+), 5 deletions(-)
+
+
+base-commit: 99bc6552614f6b25a4a6f07789300d65d384d6ed
+-- 
+2.47.3
+
diff --git a/topics/reclaim-fixes/0001-btrfs-do-not-reclaim-block-groups-on-an-errored-file.patch b/topics/reclaim-fixes/0001-btrfs-do-not-reclaim-block-groups-on-an-errored-file.patch
new file mode 100644 (file)
index 0000000..bfd2580
--- /dev/null
@@ -0,0 +1,42 @@
+From 94e71549404794dfdf9503ca2bab399db9e21099 Mon Sep 17 00:00:00 2001
+From: Zygo Blaxell <ce3g8jdj@umail.furryterror.org>
+Date: Thu, 24 Sep 2026 02:21:12 -0400
+Subject: [PATCH 1/4] btrfs: do not reclaim block groups on an errored
+ filesystem
+To: linux-btrfs@vger.kernel.org
+
+Block group reclaim makes each group read-only and relocates it, starting
+transactions as it goes.  Once the filesystem has gone into error (a
+transaction abort, say) every transaction it starts fails with -EROFS, so
+the work can only fail, while it holds reclaim_bgs_lock and sb_writers and
+the balance exclusive operation.  Return before taking the groups.
+
+Seen with stripe-exclusive raid56 allocation, whose read-only transition
+waits for the group's writes in flight: on a degraded raid6 whose commit
+hit ENOSPC and aborted, the reclaim worker sat in that wait for good.  The
+wait is fixed where it is; the worker has nothing to do there either way.
+
+Assisted-by: Claude:claude-fable-5-1
+Assisted-by: Claude:claude-opus-5-5
+---
+ fs/btrfs/block-group.c | 4 ++++
+ 1 file changed, 4 insertions(+)
+
+diff --git a/fs/btrfs/block-group.c b/fs/btrfs/block-group.c
+index 027830a53f7dc..ef64586c80ed3 100644
+--- a/fs/btrfs/block-group.c
++++ b/fs/btrfs/block-group.c
+@@ -2092,6 +2092,10 @@ void btrfs_reclaim_block_groups(struct btrfs_fs_info *fs_info, unsigned int limi
+       LIST_HEAD(retry_list);
+       int reclaimed = 0;
+ 
++      /* Relocation cannot proceed on an errored filesystem. */
++      if (BTRFS_FS_ERROR(fs_info))
++              return;
++
+       if (!btrfs_should_reclaim(fs_info))
+               return;
+ 
+-- 
+2.47.3
+
diff --git a/topics/reclaim-fixes/0002-btrfs-log-block-group-reclaim-at-debug-level.patch b/topics/reclaim-fixes/0002-btrfs-log-block-group-reclaim-at-debug-level.patch
new file mode 100644 (file)
index 0000000..6c9ede1
--- /dev/null
@@ -0,0 +1,59 @@
+From f01bc6126064acf2ecdd3a53207d61d1771e67b4 Mon Sep 17 00:00:00 2001
+From: Zygo Blaxell <ce3g8jdj@umail.furryterror.org>
+Date: Tue, 20 Oct 2026 13:04:19 -0400
+Subject: [PATCH 2/4] btrfs: log block group reclaim at debug level
+To: linux-btrfs@vger.kernel.org
+
+The reclaim worker relocates block groups without a word in the kernel
+log: btrfs_relocate_chunk() is called with verbose=false, and the
+"reclaiming chunk" info message was removed as log spam in a507904090d0
+("btrfs: remove redundant auto reclaim log message").  Only the
+btrfs_reclaim_block_group tracepoint and the reclaim_count/reclaim_errors
+counters in sysfs remain, so a kernel log taken from a test or a user
+report cannot show which groups reclaim moved, or when.
+
+Log the start of each reclaim (with the group's flags, length, used and
+reserved bytes) and its successful end with btrfs_debug(), so they are off
+by default and can be enabled with dynamic debug:
+
+  echo 'file fs/btrfs/block-group.c format "reclaim: " +p' \
+       > /sys/kernel/debug/dynamic_debug/control
+
+Errors are still logged with btrfs_err() as before.
+
+Assisted-by: Claude:claude-opus-5-5
+---
+ fs/btrfs/block-group.c | 9 ++++++++-
+ 1 file changed, 8 insertions(+), 1 deletion(-)
+
+diff --git a/fs/btrfs/block-group.c b/fs/btrfs/block-group.c
+index ef64586c80ed3..1f9dbd4fb06a0 100644
+--- a/fs/btrfs/block-group.c
++++ b/fs/btrfs/block-group.c
+@@ -2056,6 +2056,10 @@ static int btrfs_reclaim_block_group(struct btrfs_block_group *bg, int *reclaime
+       spin_unlock(&bg->lock);
+ 
+       trace_btrfs_reclaim_block_group(bg);
++      btrfs_debug(fs_info,
++"reclaim: relocating block group %llu flags 0x%llx length %llu used %llu reserved %llu",
++                  bg->start, bg->flags,
++                  bg->length, used, reserved);
+       ret = btrfs_relocate_chunk(fs_info, bg->start, false);
+       if (btrfs_is_zoned(fs_info) && ret == -EAGAIN) {
+               btrfs_dec_block_group_ro(bg);
+@@ -2079,8 +2083,11 @@ static int btrfs_reclaim_block_group(struct btrfs_block_group *bg, int *reclaime
+       if (space_info->total_bytes < old_total)
+               btrfs_set_periodic_reclaim_ready(space_info, true);
+       spin_unlock(&space_info->lock);
+-      if (!ret)
++      if (!ret) {
+               (*reclaimed)++;
++              btrfs_debug(fs_info, "reclaim: relocated block group %llu",
++                          bg->start);
++      }
+ 
+       return ret;
+ }
+-- 
+2.47.3
+
diff --git a/topics/reclaim-fixes/0003-btrfs-back-off-block-group-reclaim-after-repeated-EN.patch b/topics/reclaim-fixes/0003-btrfs-back-off-block-group-reclaim-after-repeated-EN.patch
new file mode 100644 (file)
index 0000000..6e4f28e
--- /dev/null
@@ -0,0 +1,221 @@
+From 47e1a71b1172c4bcbfdf7931942146a582da183d Mon Sep 17 00:00:00 2001
+From: Zygo Blaxell <ce3g8jdj@umail.furryterror.org>
+Date: Thu, 22 Oct 2026 04:02:52 -0400
+Subject: [PATCH 3/4] btrfs: back off block group reclaim after repeated ENOSPC
+To: linux-btrfs@vger.kernel.org
+
+Near a full filesystem every reclaim of a block group can fail with
+-ENOSPC, and the worker keeps retrying: a failed group goes back on the
+reclaim list at the end of each run (unless periodic reclaim is on) and is
+taken again at the next kick.  Each attempt makes the group read-only, does
+part of the relocation and fails, all while holding the balance exclusive
+operation, so a resize, replace or balance cannot start.
+
+This was seen with stripe-exclusive raid56 allocation, whose trapped space
+queues groups for reclaim at the fill edge: for over an hour of fsstress
+reclaim held the exclusive operation, "error relocating chunk ...: -28"
+repeating, with the worker in a metadata reservation (btrfs_block_rsv_refill
+under relocate_block_group) because metadata had no room either.  Nothing
+in the retry loop is specific to that allocator.
+
+After BTRFS_RECLAIM_ENOSPC_STREAK (3) reclaims in a row fail with -ENOSPC
+in a space_info, back off: the worker drops that space_info's groups until
+10 minutes pass, a chunk is added or removed, or the space_info's free
+space (free in its groups plus unallocated) grows by what the last failed
+group held.  A group that failed with -ENOSPC is not put back on the list
+for immediate retry.
+/sys/fs/btrfs/<uuid>/allocation/<type>/reclaim_backoffs counts the
+backoffs, and the start of one is logged at debug level ("reclaim: ...").
+
+Assisted-by: Claude:claude-opus-5-5
+---
+ fs/btrfs/block-group.c | 94 +++++++++++++++++++++++++++++++++++++++++-
+ fs/btrfs/block-group.h |  1 +
+ fs/btrfs/space-info.h  | 17 ++++++++
+ fs/btrfs/sysfs.c       |  2 +
+ 4 files changed, 112 insertions(+), 2 deletions(-)
+
+diff --git a/fs/btrfs/block-group.c b/fs/btrfs/block-group.c
+index 1f9dbd4fb06a0..0c8ce98021a41 100644
+--- a/fs/btrfs/block-group.c
++++ b/fs/btrfs/block-group.c
+@@ -2092,6 +2092,79 @@ static int btrfs_reclaim_block_group(struct btrfs_block_group *bg, int *reclaime
+       return ret;
+ }
+ 
++/*
++ * Reclaim gives up on a space_info for a while after this many reclaims in a
++ * row failed with -ENOSPC.  Relocating a group needs room for
++ * its live data (and metadata reservations for moving it); at the fill edge
++ * there is none, every attempt fails after doing its work, and retrying each
++ * failed group on every worker run held the balance exclusive operation for
++ * over an hour while writers starved (octopus P1, bhive 2026-10-20).
++ */
++#define BTRFS_RECLAIM_ENOSPC_STREAK   3
++#define BTRFS_RECLAIM_BACKOFF         (10 * 60 * HZ)
++
++/* Free space that a retried reclaim could use: free in groups, unallocated. */
++static u64 reclaim_free_bytes(const struct btrfs_space_info *space_info)
++{
++      return space_info->total_bytes - min(space_info->total_bytes,
++                                           space_info->bytes_used) +
++             atomic64_read(&space_info->fs_info->free_chunk_space);
++}
++
++/*
++ * Is reclaim backing off for this space_info?  The backoff ends when its
++ * time is up, when a chunk was added or removed, or when free space grew by
++ * what the last failed group needed.
++ */
++bool btrfs_reclaim_backoff_active(struct btrfs_space_info *space_info)
++{
++      bool active = false;
++
++      spin_lock(&space_info->lock);
++      if (space_info->reclaim_backoff_until) {
++              active = time_before(jiffies, space_info->reclaim_backoff_until) &&
++                       space_info->total_bytes == space_info->reclaim_backoff_total &&
++                       reclaim_free_bytes(space_info) < space_info->reclaim_backoff_free;
++              if (!active) {
++                      space_info->reclaim_backoff_until = 0;
++                      space_info->reclaim_enospc_streak = 0;
++              }
++      }
++      spin_unlock(&space_info->lock);
++      return active;
++}
++
++/*
++ * Count a reclaim of @bg that failed with -ENOSPC (@enospc) or succeeded,
++ * and start the backoff at the end of a streak of failures.  @need is what
++ * the group held: free space growing by that much ends the backoff early.
++ */
++static void reclaim_note_result(struct btrfs_block_group *bg, bool enospc, u64 need)
++{
++      struct btrfs_space_info *space_info = bg->space_info;
++      u32 streak;
++
++      spin_lock(&space_info->lock);
++      if (!enospc) {
++              space_info->reclaim_enospc_streak = 0;
++              spin_unlock(&space_info->lock);
++              return;
++      }
++      streak = ++space_info->reclaim_enospc_streak;
++      if (streak >= BTRFS_RECLAIM_ENOSPC_STREAK) {
++              space_info->reclaim_backoff_until = (jiffies + BTRFS_RECLAIM_BACKOFF) ?: 1;
++              space_info->reclaim_backoff_total = space_info->total_bytes;
++              space_info->reclaim_backoff_free = reclaim_free_bytes(space_info) +
++                                                 max_t(u64, need, SZ_16M);
++              space_info->reclaim_backoffs++;
++      }
++      spin_unlock(&space_info->lock);
++      if (streak >= BTRFS_RECLAIM_ENOSPC_STREAK)
++              btrfs_debug(bg->fs_info,
++"reclaim: %u reclaims failed with ENOSPC (last block group %llu), backing off flags 0x%llx",
++                          streak, bg->start, space_info->flags);
++}
++
+ void btrfs_reclaim_block_groups(struct btrfs_fs_info *fs_info, unsigned int limit)
+ {
+       struct btrfs_block_group *bg;
+@@ -2128,6 +2201,7 @@ void btrfs_reclaim_block_groups(struct btrfs_fs_info *fs_info, unsigned int limi
+        */
+       list_sort(NULL, &fs_info->reclaim_bgs, reclaim_bgs_cmp);
+       while (!list_empty(&fs_info->reclaim_bgs)) {
++              u64 need;
+               int ret;
+ 
+               bg = list_first_entry(&fs_info->reclaim_bgs,
+@@ -2137,10 +2211,26 @@ void btrfs_reclaim_block_groups(struct btrfs_fs_info *fs_info, unsigned int limi
+ 
+               space_info = bg->space_info;
+               spin_unlock(&fs_info->unused_bgs_lock);
+-              ret = btrfs_reclaim_block_group(bg, &reclaimed);
++              need = READ_ONCE(bg->used);
++              /*
++               * Backing off: drop the group rather than requeue it.  The
++               * rescans and usage updates queue it again once reclaim may
++               * succeed.
++               */
++              if (btrfs_reclaim_backoff_active(space_info)) {
++                      ret = 0;
++              } else {
++                      int before = reclaimed;
++
++                      ret = btrfs_reclaim_block_group(bg, &reclaimed);
++                      if (ret == -ENOSPC || reclaimed > before)
++                              reclaim_note_result(bg, ret == -ENOSPC, need);
++              }
+ 
++              /* An ENOSPC failure is not retried at once; see above. */
+               if ((btrfs_is_zoned(fs_info) && ret == -EAGAIN) ||
+-                  (ret && !READ_ONCE(space_info->periodic_reclaim)))
++                  (ret && ret != -ENOSPC &&
++                   !READ_ONCE(space_info->periodic_reclaim)))
+                       btrfs_link_bg_list(bg, &retry_list);
+               btrfs_put_block_group(bg);
+ 
+diff --git a/fs/btrfs/block-group.h b/fs/btrfs/block-group.h
+index d567ed822e55d..f0bf50033d4b1 100644
+--- a/fs/btrfs/block-group.h
++++ b/fs/btrfs/block-group.h
+@@ -345,6 +345,7 @@ void btrfs_reclaim_block_groups(struct btrfs_fs_info *fs_info, unsigned int limi
+ void btrfs_reclaim_bgs_work(struct work_struct *work);
+ void btrfs_reclaim_bgs(struct btrfs_fs_info *fs_info);
+ void btrfs_mark_bg_to_reclaim(struct btrfs_block_group *bg);
++bool btrfs_reclaim_backoff_active(struct btrfs_space_info *space_info);
+ int btrfs_read_block_groups(struct btrfs_fs_info *info);
+ struct btrfs_block_group *btrfs_make_block_group(struct btrfs_trans_handle *trans,
+                                                struct btrfs_space_info *space_info,
+diff --git a/fs/btrfs/space-info.h b/fs/btrfs/space-info.h
+index 0456b0d2d1b4a..fc4497cba313f 100644
+--- a/fs/btrfs/space-info.h
++++ b/fs/btrfs/space-info.h
+@@ -225,6 +225,23 @@ struct btrfs_space_info {
+        */
+       u64 reclaim_errors;
+ 
++      /*
++       * Reclaim backoff after -ENOSPC: once BTRFS_RECLAIM_ENOSPC_STREAK
++       * reclaims in a row failed for lack of space, the worker leaves this
++       * space_info's groups alone until reclaim_backoff_until passes, a chunk
++       * is added or removed (total_bytes leaves reclaim_backoff_total), or
++       * its free space reaches reclaim_backoff_free.  Under ->lock.
++       */
++      unsigned long reclaim_backoff_until;
++      u64 reclaim_backoff_free;
++      u64 reclaim_backoff_total;
++      u32 reclaim_enospc_streak;
++      /*
++       * Monotonically increasing counter of reclaim backoffs
++       * Exposed in /sys/fs/<uuid>/allocation/<type>/reclaim_backoffs
++       */
++      u64 reclaim_backoffs;
++
+       /*
+        * If true, use the dynamic relocation threshold, instead of the
+        * fixed bg_reclaim_threshold.
+diff --git a/fs/btrfs/sysfs.c b/fs/btrfs/sysfs.c
+index 89b0a4ef4063e..96d43e5ef19f5 100644
+--- a/fs/btrfs/sysfs.c
++++ b/fs/btrfs/sysfs.c
+@@ -793,6 +793,7 @@ SPACE_INFO_ATTR(disk_total);
+ SPACE_INFO_ATTR(reclaim_count);
+ SPACE_INFO_ATTR(reclaim_bytes);
+ SPACE_INFO_ATTR(reclaim_errors);
++SPACE_INFO_ATTR(reclaim_backoffs);
+ BTRFS_ATTR_RW(space_info, chunk_size, btrfs_chunk_size_show, btrfs_chunk_size_store);
+ BTRFS_ATTR(space_info, size_classes, btrfs_size_classes_show);
+ 
+@@ -925,6 +926,7 @@ static struct attribute *space_info_attrs[] = {
+       BTRFS_ATTR_PTR(space_info, reclaim_count),
+       BTRFS_ATTR_PTR(space_info, reclaim_bytes),
+       BTRFS_ATTR_PTR(space_info, reclaim_errors),
++      BTRFS_ATTR_PTR(space_info, reclaim_backoffs),
+       BTRFS_ATTR_PTR(space_info, periodic_reclaim),
+ #ifdef CONFIG_BTRFS_DEBUG
+       BTRFS_ATTR_PTR(space_info, force_chunk_alloc),
+-- 
+2.47.3
+
diff --git a/topics/reclaim-fixes/0004-btrfs-let-queued-exclusive-operations-in-between-blo.patch b/topics/reclaim-fixes/0004-btrfs-let-queued-exclusive-operations-in-between-blo.patch
new file mode 100644 (file)
index 0000000..3599e3a
--- /dev/null
@@ -0,0 +1,246 @@
+From 9a8bd47b0b9960efa030c57f1023211634ee9fea Mon Sep 17 00:00:00 2001
+From: Zygo Blaxell <ce3g8jdj@umail.furryterror.org>
+Date: Thu, 22 Oct 2026 04:02:53 -0400
+Subject: [PATCH 4/4] btrfs: let queued exclusive operations in between block
+ group reclaims
+To: linux-btrfs@vger.kernel.org
+
+The block group reclaim worker runs under the balance exclusive operation.
+At the fill edge, with writers active, each relocation takes tens of
+seconds (2 to 61 s measured) and the list keeps refilling, so the
+worker held the operation for most of the time writers ran: 84-90% of a
+600 s churn in reclaim-futile-test.sh, and for an hour of fsstress in the
+octopus P1 pass, where a resize and a replace could not start.
+
+btrfs-progs makes this worse than a plain refusal: before it calls the
+ioctl it reads sysfs exclusive_operation.  Without --enqueue it gives up
+there; with --enqueue it waits for the notification that
+btrfs_exclop_finish() sends and then calls the ioctl.  Either way the
+kernel never sees a refusal, and the worker retakes the operation right
+after each group, before a waiter can get in: on the lane a queued resize
+waited the whole churn (0 of 40 one-shot resizes succeeded, the longest
+refusal 601 s).
+
+Between groups, release the operation (btrfs_exclop_finish() sends the
+sysfs notification) and, if more groups are queued, leave it free for
+BTRFS_RECLAIM_GAP (12 s) before taking it back; if someone took it
+meanwhile, leave the rest of the list for a later run.  12 s comes from
+btrfs-progs: after the notification, check_running_fs_exclop() reopens
+the file and sleeps in a second select() for (remaining % 10) + 1 s "to
+randomize the order" before it re-reads the operation, so a waiter can
+take up to 10 s, plus wakeup latency under load, to get to the ioctl;
+with a 5 s gap about half the queued waiters woke after the worker had
+retaken the operation and waited another group.  A progs change that
+re-reads right after the notification (and randomizes only when it loses
+a race) would allow a much shorter gap.  With nobody waiting the gap
+costs only reclaim throughput: reclaim resumes after it.
+
+A caller that does reach btrfs_exclop_start() while the worker holds
+the operation (an ioctl user that does not pre-check sysfs) opens a
+BTRFS_RECLAIM_YIELD_WINDOW (60 s, longer than such a caller's retry
+interval and short next to the five-minute reclaim hysteresis) in which
+the worker neither starts nor takes another group.  Both are backoffs
+only: no drain or accounting wait is bounded by them.
+
+A group in progress is not interrupted, so a queued operation waits for
+the rest of the current group plus at most one gap.  Measured on a
+stripe_alloc filesystem, whose trapped space keeps the reclaim list full
+at the fill edge, with
+reclaim-futile-test.sh (6 x 1 GiB raid5 at the fill edge, 128 MiB per
+member added, "all" written to stripe_reclaim_now, 600 s of fsstress, a
+no-op `btrfs filesystem resize` every 15 s and a `--enqueue` one every
+60 s), three traced runs per kernel:
+
+  without this patch: the worker held the operation for a whole sweep
+  (184, 176 and 616 s); the first queued resize waited 184, 176 and about
+  655 s, i.e. for every queued group; one-shot resizes 27/40, 28/40, 0/40.
+
+  with it: every queued resize got in at the first hand-off after it
+  arrived (one sat through three short groups, 23 s), 0.3-9.4 s after the
+  worker's finish; longest queued waits 82, 11 and 23 s (the 82 s one sat
+  behind a single 127 s group); one-shot resizes 12/40, 31/40, 27/40.
+
+Reclaim kept its pace: 10, 10 and 14 groups per 10 minutes without the
+patch, 13, 11 and 10 with it.
+
+Assisted-by: Claude:claude-opus-5-5
+---
+ fs/btrfs/block-group.c | 41 +++++++++++++++++++++++++++++++++++++++--
+ fs/btrfs/fs.c          | 29 +++++++++++++++++++++++++++++
+ fs/btrfs/fs.h          | 16 ++++++++++++++++
+ 3 files changed, 84 insertions(+), 2 deletions(-)
+
+diff --git a/fs/btrfs/block-group.c b/fs/btrfs/block-group.c
+index 0c8ce98021a41..1885e1527e038 100644
+--- a/fs/btrfs/block-group.c
++++ b/fs/btrfs/block-group.c
+@@ -2165,6 +2165,14 @@ static void reclaim_note_result(struct btrfs_block_group *bg, bool enospc, u64 n
+                           streak, bg->start, space_info->flags);
+ }
+ 
++/* A refused operation's retry window is open: see btrfs_exclop_start(). */
++static bool reclaim_yielding(const struct btrfs_fs_info *fs_info)
++{
++      const unsigned long until = READ_ONCE(fs_info->reclaim_yield_until);
++
++      return until && time_before(jiffies, until);
++}
++
+ void btrfs_reclaim_block_groups(struct btrfs_fs_info *fs_info, unsigned int limit)
+ {
+       struct btrfs_block_group *bg;
+@@ -2179,9 +2187,12 @@ void btrfs_reclaim_block_groups(struct btrfs_fs_info *fs_info, unsigned int limi
+       if (!btrfs_should_reclaim(fs_info))
+               return;
+ 
++      if (reclaim_yielding(fs_info))
++              return;
++
+       guard(super_write)(fs_info->sb);
+ 
+-      if (!btrfs_exclop_start(fs_info, BTRFS_EXCLOP_BALANCE))
++      if (!btrfs_exclop_start_reclaim(fs_info))
+               return;
+ 
+       /*
+@@ -2235,11 +2246,36 @@ void btrfs_reclaim_block_groups(struct btrfs_fs_info *fs_info, unsigned int limi
+               btrfs_put_block_group(bg);
+ 
+               mutex_unlock(&fs_info->reclaim_bgs_lock);
++              /*
++               * Between groups, let a balance, replace or resize that is
++               * waiting for the exclusive operation have it: a long reclaim
++               * list must not lock them out for its whole run.
++               */
++              btrfs_exclop_finish(fs_info);
+               /*
+                * Reclaiming all the block groups in the list can take really
+                * long.  Prioritize cleaning up unused block groups.
+                */
+               btrfs_delete_unused_bgs(fs_info);
++              /*
++               * Leave the exclusive operation free for a moment before the
++               * next group.  btrfs-progs reads sysfs exclusive_operation
++               * before it calls the ioctl: without --enqueue it gives up
++               * there, and with it it waits for the notification that
++               * btrfs_exclop_finish() just sent.  Either way the refusal
++               * never reaches btrfs_exclop_start(), so only a gap lets a
++               * balance, replace or resize in while the list is long.
++               */
++              if (!list_empty_careful(&fs_info->reclaim_bgs))
++                      schedule_timeout_idle(BTRFS_RECLAIM_GAP);
++              /*
++               * Someone was refused the exclusive operation while we held
++               * it: leave the rest of the list to a run after their retry.
++               */
++              if (reclaim_yielding(fs_info))
++                      goto out;
++              if (!btrfs_exclop_start_reclaim(fs_info))
++                      goto out;
+               /*
+                * If we are interrupted by a balance, we can just bail out. The
+                * cleaner thread restart again if necessary.
+@@ -2253,10 +2289,11 @@ void btrfs_reclaim_block_groups(struct btrfs_fs_info *fs_info, unsigned int limi
+       spin_unlock(&fs_info->unused_bgs_lock);
+       mutex_unlock(&fs_info->reclaim_bgs_lock);
+ end:
++      btrfs_exclop_finish(fs_info);
++out:
+       spin_lock(&fs_info->unused_bgs_lock);
+       list_splice_tail(&retry_list, &fs_info->reclaim_bgs);
+       spin_unlock(&fs_info->unused_bgs_lock);
+-      btrfs_exclop_finish(fs_info);
+ }
+ 
+ void btrfs_reclaim_bgs_work(struct work_struct *work)
+diff --git a/fs/btrfs/fs.c b/fs/btrfs/fs.c
+index 75a1217727a7b..9a36fbd24e318 100644
+--- a/fs/btrfs/fs.c
++++ b/fs/btrfs/fs.c
+@@ -183,6 +183,34 @@ bool btrfs_exclop_start(struct btrfs_fs_info *fs_info,
+       if (fs_info->exclusive_operation == BTRFS_EXCLOP_NONE) {
+               fs_info->exclusive_operation = type;
+               ret = true;
++      } else if (test_bit(BTRFS_FS_RECLAIM_EXCLOP, &fs_info->flags)) {
++              /*
++               * The block group reclaim worker holds it.  It is background
++               * work: have it stand aside after its current group, long
++               * enough for the caller to retry.
++               */
++              WRITE_ONCE(fs_info->reclaim_yield_until,
++                         (jiffies + BTRFS_RECLAIM_YIELD_WINDOW) ?: 1);
++      }
++      spin_unlock(&fs_info->super_lock);
++
++      return ret;
++}
++
++/*
++ * The block group reclaim worker's balance exclusive operation: marked as
++ * the worker's, so that an operation it refuses makes it yield (see
++ * btrfs_exclop_start()).
++ */
++bool btrfs_exclop_start_reclaim(struct btrfs_fs_info *fs_info)
++{
++      bool ret = false;
++
++      spin_lock(&fs_info->super_lock);
++      if (fs_info->exclusive_operation == BTRFS_EXCLOP_NONE) {
++              fs_info->exclusive_operation = BTRFS_EXCLOP_BALANCE;
++              set_bit(BTRFS_FS_RECLAIM_EXCLOP, &fs_info->flags);
++              ret = true;
+       }
+       spin_unlock(&fs_info->super_lock);
+ 
+@@ -222,6 +250,7 @@ void btrfs_exclop_finish(struct btrfs_fs_info *fs_info)
+ {
+       spin_lock(&fs_info->super_lock);
+       WRITE_ONCE(fs_info->exclusive_operation, BTRFS_EXCLOP_NONE);
++      clear_bit(BTRFS_FS_RECLAIM_EXCLOP, &fs_info->flags);
+       spin_unlock(&fs_info->super_lock);
+       sysfs_notify(&fs_info->fs_devices->fsid_kobj, NULL, "exclusive_operation");
+ }
+diff --git a/fs/btrfs/fs.h b/fs/btrfs/fs.h
+index 2dd167c32d612..686514187327f 100644
+--- a/fs/btrfs/fs.h
++++ b/fs/btrfs/fs.h
+@@ -234,6 +234,9 @@ enum {
+        */
+       BTRFS_FS_UNALIGNED_TREE_BLOCK,
+ 
++      /* The block group reclaim worker holds the exclusive operation. */
++      BTRFS_FS_RECLAIM_EXCLOP,
++
+ #if BITS_PER_LONG == 32
+       /* Indicate if we have error/warn message printed on 32bit systems */
+       BTRFS_FS_32BIT_ERROR,
+@@ -869,6 +872,13 @@ struct btrfs_fs_info {
+ 
+       /* Reclaim partially filled block groups in the background */
+       struct work_struct reclaim_bgs_work;
++      /*
++       * A balance, replace, resize or device add/remove was refused while
++       * the reclaim worker held the exclusive operation: until this jiffies
++       * value the worker neither starts nor takes another group, so that the
++       * caller's retry gets the operation.
++       */
++      unsigned long reclaim_yield_until;
+       /* Protected by unused_bgs_lock. */
+       struct list_head reclaim_bgs;
+       int bg_reclaim_threshold;
+@@ -1084,6 +1094,12 @@ static inline unsigned int btrfs_blocks_per_folio(const struct btrfs_fs_info *fs
+ }
+ 
+ bool __attribute_const__ btrfs_supported_blocksize(u32 blocksize);
++/* How long the reclaim worker stands aside after a refused operation. */
++#define BTRFS_RECLAIM_YIELD_WINDOW    (60 * HZ)
++/* How long it leaves the exclusive operation free between two groups. */
++#define BTRFS_RECLAIM_GAP             (12 * HZ)
++
++bool btrfs_exclop_start_reclaim(struct btrfs_fs_info *fs_info);
+ bool btrfs_exclop_start(struct btrfs_fs_info *fs_info,
+                       enum btrfs_exclusive_operation type);
+ bool btrfs_exclop_start_try_lock(struct btrfs_fs_info *fs_info,
+-- 
+2.47.3
+
diff --git a/topics/reclaim-fixes/TESTING.md b/topics/reclaim-fixes/TESTING.md
new file mode 100644 (file)
index 0000000..b95c3c9
--- /dev/null
@@ -0,0 +1,35 @@
+# Testing: reclaim-fixes
+
+CANDIDATE (2026-10-28), not promoted.  Split out of topics/stripe-alloc by
+the sa-fold rework (Zygo 2026-10-27: "Split generic reclaim into a separate
+topic where reasonable"): the generic parts of four stripe-alloc commits.
+Candidate refs: refs/cand/sa-fold/{mn,618}/reclaim (the first four commits
+of refs/cand/sa-fold/{mn,618}/topic, which builds on them).  These patches
+were exported from the misc-next candidate.
+
+| patch | from (lane commit) | what stayed in stripe-alloc |
+|---|---|---|
+| 1 do not reclaim on an errored filesystem | "stripe_alloc: do not wait for stripe runs to drain on an errored filesystem" (its reclaim-worker bail) | the stripe run drain bail |
+| 2 log block group reclaim at debug level | "btrfs: log block group reclaim at debug level" | compaction and trapped bytes in the reclaim log |
+| 3 back off after repeated ENOSPC | "stripe_alloc: back off block group reclaim after repeated ENOSPC" | the stripe_reclaim_now exception, "or compacting" |
+| 4 let queued exclusive operations in between | "stripe_alloc: let queued exclusive operations in between reclaims" (whole) | nothing |
+
+To verify:
+
+- patch 1: abort a transaction (forced error) with groups queued for
+  reclaim; the worker must return without making any group read-only.
+- patch 2: with dynamic debug on for `format "reclaim: "`, each relocation
+  by reclaim logs one start and one end line.
+- patch 3: at the fill edge, after three -ENOSPC reclaims the worker stops
+  (allocation/<type>/reclaim_backoffs counts it) and resumes after a chunk
+  is added; reclaim-futile-test.sh.
+- patch 4: reclaim-futile-test.sh: queued `btrfs filesystem resize --enqueue`
+  gets in at the next hand-off; reclaim keeps its pace.
+
+Each patch was tested inside topics/stripe-alloc (the commit messages give
+the runs).  Results of the split candidates are recorded below.
+
+## Results
+
+- Standalone build of the four commits on each lane base: see the
+  topic-buildcheck runs of refs/cand/sa-fold/{618,mn}/topic (commits 1-4).