From 31641b753458de948c4848c7ed518c3a95cc769a Mon Sep 17 00:00:00 2001 From: Matthew Mattox Date: Fri, 13 Nov 2026 23:02:17 -0600 Subject: [PATCH 1/3] perf(alloc): free uncounted blocks under the bitmap lock alone, once per operation Deletes took the global refcount lock for every file, even for blocks no snapshot or clone ever shared, and the bitmap lock once per block. With four nodes deleting, two thirds of their time went to the refcount lock. A block whose refcount reads 0 under the bitmap lock now goes straight back to the bitmap. Share is the only runtime code that raises a count, and it now does so under the bitmap lock too, skipping blocks already freed, so a zero count cannot change under a free. Counted blocks still go through Release under the refcount lock, after the bitmap lock is dropped, since Share takes refcount before bitmap. Co-Authored-By: Claude Opus 5.5 --- CHANGELOG.md | 1 + internal/bitmap/bitmap.go | 105 ++++++++++++++++++++++ internal/bitmap/bitmap_test.go | 47 ++++++++++ internal/extent/extent.go | 3 + internal/extent/extent_test.go | 4 +- internal/extent/tree_edit.go | 52 +++++++---- internal/fsck/check_fuzz_test.go | 3 +- internal/goclusterfs/fs.go | 34 +++---- internal/goclusterfs/fsck_reclaim_test.go | 14 +-- internal/goclusterfs/snapshot_test.go | 95 +++++++++++++++++++- internal/refcount/refcount.go | 91 +++++++++++++++++-- internal/refcount/refcount_test.go | 91 ++++++++++++++++++- internal/snapshot/worker_test.go | 2 +- tests/integration/helpers.go | 50 +++-------- tests/test-manifest.yaml | 35 ++++++++ 15 files changed, 538 insertions(+), 89 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index e3e67ed1..b2f474ae 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -57,6 +57,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), ### Changed +- Freeing blocks that no snapshot or clone shares takes only the block bitmap lock, once per operation, not the refcount lock and one bitmap lock per block. Snapshots and clones take the bitmap lock while they count a file's blocks. - Each node keeps the directories it reads in an in-memory index, so a lookup no longer reads and decodes the whole directory. A lookup checks the directory inode's generation on disk before it uses the index, so other nodes' changes show on the next lookup without broadcast. Removing an entry now writes the directory inode before the child is freed. `-dir-index-entries` caps the names held (default 1,048,576, about 100 MB), and `/metrics` counts hits, misses and rebuilds. In one test with two nodes, `ls -l` of 4,000 files went from 65 s to 1 s, a `stat` from 3.8 ms to 0.25 ms, and a create from 14 ms to 6 ms. - `-format` now writes a superblock with the volume layout and zeroes all metadata regions, even on a device that already holds a filesystem. Mount reads every region offset from the superblock. - At most 64 nodes mount a volume at once, one per node registry slot. diff --git a/internal/bitmap/bitmap.go b/internal/bitmap/bitmap.go index 7f8eb8bc..f845ff1d 100644 --- a/internal/bitmap/bitmap.go +++ b/internal/bitmap/bitmap.go @@ -334,6 +334,111 @@ func (r *Region) releaseReserved(ctx context.Context, blocks []uint64) { // flipBits marks each block allocated (or free) whose bit says otherwise, under // the bitmap lock, and returns the blocks it changed, even on error. +// HoldAllocated takes the bitmap lock and returns the blocks of blocks that are +// allocated. The lock stays held, so none of them can be freed, until release. +func (r *Region) HoldAllocated(ctx context.Context, blocks []uint64) ([]uint64, func(), error) { + if r.lockMgr != nil { + if err := r.lockMgr.Acquire(ctx, lock.LockTypeBlockBitmap, 0, lock.LockModeExclusive); err != nil { + return nil, nil, fmt.Errorf("failed to acquire bitmap lock: %w", err) + } + } + r.mu.Lock() + release := func() { + r.mu.Unlock() + if r.lockMgr != nil { + r.unlock() + } + } + sectors := make(map[uint64][]byte) + var allocated []uint64 + for _, b := range blocks { + if b >= r.totalBlocks { + continue + } + sectorIdx := b / BitsPerSector + data, ok := sectors[sectorIdx] + if !ok { + var err error + if data, err = r.readSector(sectorIdx); err != nil { + release() + return nil, nil, fmt.Errorf("failed to read bitmap sector %d: %w", sectorIdx, err) + } + sectors[sectorIdx] = data + } + bit := b % BitsPerSector + if data[bit/8]&(1<<(bit%8)) != 0 { + allocated = append(allocated, b) + } + } + return allocated, release, nil +} + +// FreeIf takes the bitmap lock, asks which of blocks to free, and frees those +// in one hold. It returns the blocks it left allocated. Freed blocks are +// queued for TRIM. +func (r *Region) FreeIf(ctx context.Context, blocks []uint64, which func([]uint64) func(uint64) bool) ([]uint64, error) { + if len(blocks) == 0 { + return nil, nil + } + if r.lockMgr != nil { + if err := r.lockMgr.Acquire(ctx, lock.LockTypeBlockBitmap, 0, lock.LockModeExclusive); err != nil { + return nil, fmt.Errorf("failed to acquire bitmap lock: %w", err) + } + defer r.unlock() + } + r.mu.Lock() + defer r.mu.Unlock() + + free := which(blocks) + var kept []uint64 + bySector := make(map[uint64][]uint64) + for _, b := range blocks { + switch { + case !free(b): + kept = append(kept, b) + case b >= r.totalBlocks: + logging.Debugf("bitmap.FreeIf: block %d out of range", b) + default: + bySector[b/BitsPerSector] = append(bySector[b/BitsPerSector], b) + } + } + for sectorIdx, sectorBlocks := range bySector { + data, err := r.readSector(sectorIdx) + if err != nil { + return kept, fmt.Errorf("failed to read bitmap sector %d: %w", sectorIdx, err) + } + var freed []uint64 + for _, b := range sectorBlocks { + bit := b % BitsPerSector + mask := byte(1) << (bit % 8) + if data[bit/8]&mask == 0 { + logging.Debugf("bitmap.FreeIf: block %d already free", b) + continue + } + data[bit/8] &^= mask + freed = append(freed, b) + } + if len(freed) == 0 { + continue + } + if err := r.writeSector(sectorIdx, data); err != nil { + return kept, fmt.Errorf("failed to write bitmap sector %d: %w", sectorIdx, err) + } + if r.trimMgr != nil { + for _, b := range freed { + r.trimMgr.Queue(b) + } + } + } + return kept, nil +} + +// FreeBatch frees blocks in one bitmap lock hold. +func (r *Region) FreeBatch(ctx context.Context, blocks []uint64) error { + _, err := r.FreeIf(ctx, blocks, func([]uint64) func(uint64) bool { return func(uint64) bool { return true } }) + return err +} + func (r *Region) flipBits(ctx context.Context, blocks []uint64, allocated bool) ([]uint64, error) { if r.lockMgr != nil { if err := r.lockMgr.Acquire(ctx, lock.LockTypeBlockBitmap, 0, lock.LockModeExclusive); err != nil { diff --git a/internal/bitmap/bitmap_test.go b/internal/bitmap/bitmap_test.go index dd04d8f6..46a3ef69 100644 --- a/internal/bitmap/bitmap_test.go +++ b/internal/bitmap/bitmap_test.go @@ -5,6 +5,7 @@ import ( "errors" "os" "path/filepath" + "slices" "testing" "github.com/supporttools/GoClusterFS/internal/storage" @@ -682,3 +683,49 @@ func BenchmarkIsFree(b *testing.B) { } } } + +// FreeIf frees the blocks the caller picks, keeps the rest, and skips blocks +// already free; HoldAllocated reports only allocated blocks. +func TestFreeIfAndHoldAllocated(t *testing.T) { + dev, cleanup := createTestDevice(t, 10<<20) + defer cleanup() + var uuid [16]byte + region := NewRegion(dev, 0, 1000, nil, uuid) + ctx := context.Background() + blocks, err := region.Alloc(ctx, 4) + if err != nil { + t.Fatal(err) + } + if err := region.Free(ctx, blocks[3]); err != nil { + t.Fatal(err) + } + + allocated, release, err := region.HoldAllocated(ctx, blocks) + if err != nil { + t.Fatal(err) + } + release() + if want := blocks[:3]; !slices.Equal(allocated, want) { + t.Errorf("HoldAllocated = %v, want %v", allocated, want) + } + + pick := map[uint64]bool{blocks[0]: true, blocks[2]: true, blocks[3]: true} + kept, err := region.FreeIf(ctx, blocks, func([]uint64) func(uint64) bool { + return func(b uint64) bool { return pick[b] } + }) + if err != nil { + t.Fatal(err) + } + if want := []uint64{blocks[1]}; !slices.Equal(kept, want) { + t.Errorf("FreeIf kept %v, want %v", kept, want) + } + for i, b := range blocks { + free, err := region.IsFree(b) + if err != nil { + t.Fatal(err) + } + if want := i != 1; free != want { + t.Errorf("block %d free = %v, want %v", b, free, want) + } + } +} diff --git a/internal/extent/extent.go b/internal/extent/extent.go index e7f85694..132f32e0 100644 --- a/internal/extent/extent.go +++ b/internal/extent/extent.go @@ -103,6 +103,9 @@ type Manager struct { // snapshot or clone goes back to the bitmap only after its last owner frees it. func (m *Manager) SetRefcounts(refs *refcount.Region) { m.refs = refs + if refs != nil { + refs.SetAllocationGuard(m.bitmap) + } } // NewManager creates a new extent manager. dataOffset is the device offset of diff --git a/internal/extent/extent_test.go b/internal/extent/extent_test.go index 5b731a3b..73cf1337 100644 --- a/internal/extent/extent_test.go +++ b/internal/extent/extent_test.go @@ -1566,7 +1566,7 @@ func TestFreeKeepsSharedBlocks(t *testing.T) { if err != nil { t.Fatal(err) } - if err := refs.Share(env.ctx, blocks); err != nil { + if _, err := refs.Share(env.ctx, blocks); err != nil { t.Fatal(err) } @@ -1663,7 +1663,7 @@ func TestConcurrentInlineCopyOnWrite(t *testing.T) { t.Fatal(err) } env.write(src) - if err := refs.Share(env.ctx, []uint64{old}); err != nil { + if _, err := refs.Share(env.ctx, []uint64{old}); err != nil { t.Fatal(err) } snap := env.newInode() diff --git a/internal/extent/tree_edit.go b/internal/extent/tree_edit.go index 432cddd9..32e8ec45 100644 --- a/internal/extent/tree_edit.go +++ b/internal/extent/tree_edit.go @@ -742,27 +742,41 @@ func (m *Manager) freeBlocks(ctx context.Context, blocks []uint64) { m.deferred = nil m.deferredMu.Unlock() - if m.refs != nil && len(blocks) > 0 { - free, err := m.refs.Release(ctx, blocks) - switch { - case errors.Is(err, lock.ErrDeadlockRisk): - m.deferFree(blocks...) - return - case err != nil: - log.Printf("[extent] release %d blocks: %v; leaving them allocated", len(blocks), err) - return - } - blocks = free + if len(blocks) == 0 { + return + } + uncounted := func([]uint64) func(uint64) bool { return func(uint64) bool { return true } } + if m.refs != nil { + uncounted = m.refs.Uncounted + } + // Only Share raises a count, and only under the bitmap lock, so a block with + // no count under that lock has this one owner and needs no refcount lock. + counted, err := m.bitmap.FreeIf(ctx, blocks, uncounted) + switch { + case errors.Is(err, lock.ErrDeadlockRisk): + m.deferFree(blocks...) + return + case err != nil: + log.Printf("[extent] free %d blocks: %v; leaving the rest allocated", len(blocks), err) + return + case len(counted) == 0: + return } - for _, b := range blocks { - err := m.bitmap.Free(ctx, b) - switch { - case errors.Is(err, lock.ErrDeadlockRisk): - m.deferFree(b) - case err != nil: - log.Printf("[extent] free block %d: %v", b, err) - } + free, err := m.refs.Release(ctx, counted) + switch { + case errors.Is(err, lock.ErrDeadlockRisk): + m.deferFree(counted...) + return + case err != nil: + log.Printf("[extent] release %d blocks: %v; leaving them allocated", len(counted), err) + return + } + switch err := m.bitmap.FreeBatch(ctx, free); { + case errors.Is(err, lock.ErrDeadlockRisk): + m.deferFree(free...) + case err != nil: + log.Printf("[extent] free %d released blocks: %v", len(free), err) } } diff --git a/internal/fsck/check_fuzz_test.go b/internal/fsck/check_fuzz_test.go index 7bcac80d..9a150452 100644 --- a/internal/fsck/check_fuzz_test.go +++ b/internal/fsck/check_fuzz_test.go @@ -123,7 +123,8 @@ func fuzzImage(tb testing.TB) (*storage.Device, []fuzzTarget) { blocks, err := mgr.DataBlocks(plain) must(err) - must(refs.Share(ctx, blocks)) + _, err = refs.Share(ctx, blocks) + must(err) clone := newFile("clone") must(mgr.CopyExtentsForClone(ctx, plain, clone)) clone.Size = plain.Size diff --git a/internal/goclusterfs/fs.go b/internal/goclusterfs/fs.go index 10f95557..e6853448 100644 --- a/internal/goclusterfs/fs.go +++ b/internal/goclusterfs/fs.go @@ -3213,31 +3213,33 @@ func (f *FS) shareSource(ctx context.Context, srcNum uint32) (*inode.Inode, []ui if err := f.refcountReg.CheckCovered(blocks); err != nil { return nil, nil, err } - if err := f.refcountReg.Share(ctx, blocks); err != nil { + counted, err := f.refcountReg.Share(ctx, blocks) + if err != nil { return nil, nil, err } + marked, err := src, error(nil) // A snapshot's data inode is marked shared when it is created and never written again. - if src.Flags&inode.FlagSnapshotData != 0 { - return src, blocks, nil - } - if beforeShareMark != nil { - beforeShareMark() - } - // Setxattr holds lockInode(srcNum). - marked, err := f.updateUnderInodeLock(ctx, srcNum, func(ino *inode.Inode) error { - if duringShareMark != nil { - duringShareMark() + if src.Flags&inode.FlagSnapshotData == 0 { + if beforeShareMark != nil { + beforeShareMark() } - return f.markShared(ino) - }) + // Setxattr holds lockInode(srcNum). + marked, err = f.updateUnderInodeLock(ctx, srcNum, func(ino *inode.Inode) error { + if duringShareMark != nil { + duringShareMark() + } + return f.markShared(ino) + }) + } var now []uint64 if err == nil { now, err = f.extentMgr.DataBlocks(marked) } - if err == nil && slices.Equal(now, blocks) { - return marked, blocks, nil + // Share skips blocks already freed, so a file that lost blocks is shared again. + if err == nil && slices.Equal(now, blocks) && len(counted) == len(blocks) { + return marked, counted, nil } - f.extentMgr.ReleaseBlocks(ctx, blocks) + f.extentMgr.ReleaseBlocks(ctx, counted) if err != nil { return nil, nil, err } diff --git a/internal/goclusterfs/fsck_reclaim_test.go b/internal/goclusterfs/fsck_reclaim_test.go index 1fb43f89..e66b2be9 100644 --- a/internal/goclusterfs/fsck_reclaim_test.go +++ b/internal/goclusterfs/fsck_reclaim_test.go @@ -33,7 +33,7 @@ func leakBlock(t *testing.T, fsys *FS) { } // deleteWithTimedOutFree removes name as Unlink does, but its block free gives -// up on a refcount lock another node holds, as it does after the 30s lock-wait +// up on the bitmap and refcount locks another node holds, as it does after the 30s lock-wait // limit. Unlink detaches from its caller's context, so it would wait the full 30s. func deleteWithTimedOutFree(t *testing.T, fsys *FS, name string) { t.Helper() @@ -63,16 +63,20 @@ func deleteWithTimedOutFree(t *testing.T, fsys *FS, name string) { copy(otherUUID[:], "othernode1234567") otherUUID[15] = byte(slot) other := lock.NewManager(fsys.dev, sb.LockBitmapOffset, sb.LockBitmapSize, otherUUID, slot) - if err := other.Acquire(ctx, lock.LockTypeRefCount, 0, lock.LockModeExclusive); err != nil { - t.Fatal(err) + for _, typ := range []lock.LockType{lock.LockTypeRefCount, lock.LockTypeBlockBitmap} { + if err := other.Acquire(ctx, typ, 0, lock.LockModeExclusive); err != nil { + t.Fatal(err) + } } expired, cancel := context.WithCancel(ctx) cancel() if err := fsys.extentMgr.Delete(expired, ino); err != nil { t.Fatalf("delete %s: %v", name, err) } - if err := other.Release(lock.LockTypeRefCount, 0); err != nil { - t.Fatal(err) + for _, typ := range []lock.LockType{lock.LockTypeBlockBitmap, lock.LockTypeRefCount} { + if err := other.Release(typ, 0); err != nil { + t.Fatal(err) + } } if err := fsys.inodeTbl.Free(ctx, ino.InodeNum); err != nil { t.Fatal(err) diff --git a/internal/goclusterfs/snapshot_test.go b/internal/goclusterfs/snapshot_test.go index e3d0dfd8..6e513ca8 100644 --- a/internal/goclusterfs/snapshot_test.go +++ b/internal/goclusterfs/snapshot_test.go @@ -604,7 +604,7 @@ func TestCopyOnWriteKeepsConcurrentInPlaceWrite(t *testing.T) { } inPlace = true // Node B's snapshot counts the block before it marks the file shared. - if err := nodeB.refcountReg.Share(ctx, []uint64{shared}); err != nil { + if _, err := nodeB.refcountReg.Share(ctx, []uint64{shared}); err != nil { t.Error(err) } go func() { @@ -740,6 +740,9 @@ func TestSnapshotRetriesWhenFileChangesWhileSharing(t *testing.T) { if free, err := nodeA.bitmapMgr.IsFree(b); err != nil || !free { t.Errorf("block %d is unmapped but still allocated (refcount %d, err=%v)", b, refcountOf(t, nodeA, b), err) } + if got := refcountOf(t, nodeA, b); got != 0 { + t.Errorf("block %d is free but counts %d owners", b, got) + } } }) } @@ -997,3 +1000,93 @@ func TestStaleCopyCannotUndoCopyOnWrite(t *testing.T) { setxattr(t, f, "user.snapshot.clone", "before:/before-clone") checkFile(t, lookupFile(t, fsys, "before-clone"), original) } + +// Deleting files no snapshot or clone ever shared frees their blocks under the +// bitmap lock alone, one hold per file, without the refcount lock. +func TestDeletingUnsharedFilesTakesNoRefcountLock(t *testing.T) { + fsys := openFormattedFS(t, newFormattedImage(t)) + ctx := context.Background() + for i := range 3 { + writeAt(t, createFile(t, fsys, fmt.Sprintf("f%d", i)), pattern(byte(i), 3*BlockSize), 0) + } + free := fsys.bitmapMgr.FreeCount() + before := lockAcquires(fsys) + for i := range 3 { + if errno := fsys.Unlink(ctx, fmt.Sprintf("f%d", i)); errno != 0 { + t.Fatalf("unlink f%d: %v", i, errno) + } + } + after := lockAcquires(fsys) + if got := after["refcount"] - before["refcount"]; got != 0 { + t.Errorf("deleting 3 unshared files took the refcount lock %d times, want 0", got) + } + if got := after["bitmap"] - before["bitmap"]; got != 3 { + t.Errorf("deleting 3 files of 3 blocks took the bitmap lock %d times, want 3", got) + } + if got := fsys.bitmapMgr.FreeCount(); got != free+9 { + t.Errorf("%d free blocks after the deletes, want %d", got, free+9) + } +} + +func lockAcquires(fsys *FS) map[string]uint64 { + out := map[string]uint64{} + for _, ts := range fsys.lockMgr.Stats().Types { + out[ts.Name] = ts.Acquires + } + return out +} + +// Node B clones a file while node A deletes the clone before it. Deleting a +// clone releases counted blocks under the refcount lock and then frees them +// under the bitmap lock, while cloning holds the refcount lock and then the +// bitmap lock. Neither may wait on the other, and every count must come out +// exact. +func TestCountedFreesAndSharesAcrossNodes(t *testing.T) { + path := newFormattedImageOfSize(t, superblock.MinDeviceSize+128<<20) + nodeA, nodeB := openFormattedFS(t, path), openFormattedFS(t, path) + ctx := context.Background() + content := pattern(1, 2*BlockSize) + src := createFile(t, nodeA, "src") + writeAt(t, src, content, 0) + free := nodeA.bitmapMgr.FreeCount() + + const rounds = 20 + done := make(chan struct{}) + go func() { + defer close(done) + var wg sync.WaitGroup + for i := range rounds { + wg.Go(func() { + if errno := (&File{fs: nodeB, inodeNum: src.inodeNum}).Setxattr(ctx, "user.clone", []byte(fmt.Sprintf("/c%d", i)), 0); errno != 0 { + t.Errorf("clone %d: %v", i, errno) + } + }) + if i > 0 { + wg.Go(func() { + if errno := nodeA.Unlink(ctx, fmt.Sprintf("c%d", i-1)); errno != 0 && errno != syscall.ENOENT { + t.Errorf("unlink c%d: %v", i-1, errno) + } + }) + } + wg.Wait() + } + }() + select { + case <-done: + case <-time.After(2 * time.Minute): + t.Fatalf("cloning and deleting clones did not finish: lock stats A %+v, B %+v", nodeA.lockMgr.Stats(), nodeB.lockMgr.Stats()) + } + for i := range rounds { + _ = nodeA.Unlink(ctx, fmt.Sprintf("c%d", i)) + } + + checkFile(t, src, content) + for logical := uint64(0); logical < 2; logical++ { + if got := refcountOf(t, nodeA, physicalBlock(t, nodeA, src.inodeNum, logical)); got > 1 { + t.Errorf("block %d of src counts %d owners after every clone is gone, want 1", logical, got) + } + } + if got := nodeA.bitmapMgr.FreeCount(); got != free { + t.Errorf("%d free blocks after deleting every clone, want %d", got, free) + } +} diff --git a/internal/refcount/refcount.go b/internal/refcount/refcount.go index 422013bd..caedf72d 100644 --- a/internal/refcount/refcount.go +++ b/internal/refcount/refcount.go @@ -111,6 +111,19 @@ type Region struct { capacity uint64 // Blocks the region has entries for totalBlocks uint64 // Total number of data blocks tracked lockMgr *lock.Manager // For distributed locking (optional) + guard AllocationGuard +} + +// AllocationGuard is the block bitmap as Share needs it. A block with no count +// is freed under the bitmap lock alone, so Share counts blocks only while +// holding that lock, and only blocks that are still allocated. +type AllocationGuard interface { + HoldAllocated(ctx context.Context, blocks []uint64) (allocated []uint64, release func(), err error) +} + +// SetAllocationGuard makes Share count only blocks the guard reports allocated. +func (r *Region) SetAllocationGuard(g AllocationGuard) { + r.guard = g } // NewRegion creates a new reference count region manager. @@ -333,17 +346,76 @@ func (r *Region) DecrementBatch(ctx context.Context, blockNums []uint64) ([]uint return results, nil } -// Share adds one owner, such as a snapshot or a clone, to each block. Blocks -// are allocated with a count of 0, which like 1 means a single owner, so the -// first share of a block sets its count to 2. -func (r *Region) Share(ctx context.Context, blockNums []uint64) error { - return r.updateBatch(ctx, blockNums, func(_ int, e *Entry) (bool, error) { +// Share adds one owner, such as a snapshot or a clone, to each block that is +// still allocated, and returns the blocks it counted. Blocks are allocated +// with a count of 0, which like 1 means a single owner, so the first share of +// a block sets its count to 2. +func (r *Region) Share(ctx context.Context, blockNums []uint64) ([]uint64, error) { + if len(blockNums) == 0 { + return nil, nil + } + if r.lockMgr != nil { + if err := r.lockMgr.Acquire(ctx, lock.LockTypeRefCount, 0, lock.LockModeExclusive); err != nil { + return nil, fmt.Errorf("failed to acquire refcount lock: %w", err) + } + defer r.unlock() + } + counted := blockNums + if r.guard != nil { + allocated, release, err := r.guard.HoldAllocated(ctx, blockNums) + if err != nil { + return nil, err + } + defer release() + counted = allocated + } + err := r.updateLocked(counted, func(_ int, e *Entry) (bool, error) { if e.RefCount == 0xFFFFFFFF { return false, ErrRefCountOverflow } e.RefCount = max(e.RefCount, 1) + 1 return true, nil }) + if err != nil { + return nil, err + } + return counted, nil +} + +// Uncounted reports which of blocks have no count, reading each sector once. +// A block whose sector cannot be read counts as counted. +func (r *Region) Uncounted(blockNums []uint64) func(uint64) bool { + r.mu.RLock() + defer r.mu.RUnlock() + sectors := make(map[uint64][]byte) + unreadable := make(map[uint64]bool) + none := make(map[uint64]bool) + for _, b := range blockNums { + switch { + case b >= r.totalBlocks: + continue + case b >= r.capacity: + none[b] = true + continue + } + sectorIdx := b / EntriesPerSector + if unreadable[sectorIdx] { + continue + } + data, ok := sectors[sectorIdx] + if !ok { + var err error + if data, err = r.readSector(sectorIdx); err != nil { + unreadable[sectorIdx] = true + continue + } + sectors[sectorIdx] = data + } + if decodeEntry(data, b%EntriesPerSector) == (Entry{}) { + none[b] = true + } + } + return func(b uint64) bool { return none[b] } } // Release drops one owner from each block and returns the blocks that no @@ -387,7 +459,16 @@ func (r *Region) updateBatch(ctx context.Context, blockNums []uint64, fn func(i } defer r.unlock() } + return r.updateLocked(blockNums, fn) +} +// updateLocked is updateBatch for a caller that holds the refcount lock. +func (r *Region) updateLocked(blockNums []uint64, fn func(i int, e *Entry) (bool, error)) error { + for _, blockNum := range blockNums { + if blockNum >= r.totalBlocks { + return ErrBlockOutOfRange + } + } r.mu.Lock() defer r.mu.Unlock() diff --git a/internal/refcount/refcount_test.go b/internal/refcount/refcount_test.go index c80b71e3..d5c25e77 100644 --- a/internal/refcount/refcount_test.go +++ b/internal/refcount/refcount_test.go @@ -8,7 +8,10 @@ import ( "os" "path/filepath" "testing" + "time" + "github.com/supporttools/GoClusterFS/internal/bitmap" + "github.com/supporttools/GoClusterFS/internal/lock" "github.com/supporttools/GoClusterFS/internal/storage" ) @@ -587,13 +590,13 @@ func TestShareAndRelease(t *testing.T) { return e.RefCount } - if err := region.Share(ctx, blocks); err != nil { + if _, err := region.Share(ctx, blocks); err != nil { t.Fatal(err) } if got := count(3); got != 2 { t.Fatalf("first share of a new block: count %d, want 2", got) } - if err := region.Share(ctx, blocks[:1]); err != nil { + if _, err := region.Share(ctx, blocks[:1]); err != nil { t.Fatal(err) } if got := count(3); got != 3 { @@ -979,7 +982,7 @@ func TestBlocksPastRegionLeaveTheNextRegionAlone(t *testing.T) { if _, err := region.Increment(ctx, first); !errors.Is(err, ErrBlockPastRegion) { t.Errorf("Increment(%d) = %v, want ErrBlockPastRegion", first, err) } - if err := region.Share(ctx, []uint64{first - 1, last}); !errors.Is(err, ErrBlockPastRegion) { + if _, err := region.Share(ctx, []uint64{first - 1, last}); !errors.Is(err, ErrBlockPastRegion) { t.Errorf("Share(%d, %d) = %v, want ErrBlockPastRegion", first-1, last, err) } if err := region.Set(ctx, last, 2, 0); !errors.Is(err, ErrBlockPastRegion) { @@ -1106,3 +1109,85 @@ func BenchmarkScan(b *testing.B) { } } } + +// Node A frees a block with no count under the bitmap lock while node B shares +// it. B's Share waits for the bitmap lock and then skips the freed block, so no +// free block keeps a count. +func TestShareWaitsForUncountedFree(t *testing.T) { + dev, cleanup := createTestDevice(t, 32<<20) + defer cleanup() + const blocks = 1000 + node := func(slot int) (*lock.Manager, *bitmap.Region, *Region) { + var uuid [16]byte + copy(uuid[:], "test-node-uuid0") + uuid[15] = byte('0' + slot) + mgr := lock.NewManager(dev, 16<<20, 10<<20, uuid, slot) + bm := bitmap.NewRegion(dev, 1<<20, blocks, mgr, uuid) + refs := NewRegion(dev, 0, SizeForBlocks(blocks), blocks, mgr) + refs.SetAllocationGuard(bm) + return mgr, bm, refs + } + _, bmA, refsA := node(0) + mgrB, _, refsB := node(1) + ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second) + defer cancel() + + got, err := bmA.Alloc(ctx, 1) + if err != nil { + t.Fatal(err) + } + b := got[0] + type result struct { + counted []uint64 + err error + } + shared := make(chan result, 1) + kept, err := bmA.FreeIf(ctx, []uint64{b}, func(bs []uint64) func(uint64) bool { + uncounted := refsA.Uncounted(bs) + go func() { + counted, err := refsB.Share(ctx, []uint64{b}) + shared <- result{counted, err} + }() + for mgrB.Stats().Waiting == 0 { + select { + case r := <-shared: + shared <- r + return uncounted + case <-time.After(time.Millisecond): + } + } + return uncounted + }) + if err != nil || len(kept) != 0 { + t.Fatalf("FreeIf kept %v, err %v; want the uncounted block freed", kept, err) + } + r := <-shared + if r.err != nil { + t.Fatal(r.err) + } + if len(r.counted) != 0 { + t.Errorf("Share counted %v, a block freed while it waited", r.counted) + } + if e, err := refsA.GetUnlocked(b); err != nil || e != (Entry{}) { + t.Errorf("freed block %d: entry %+v (err=%v), want no count", b, e, err) + } +} + +// Share takes the refcount lock and then the bitmap lock, so taking them the +// other way round must be refused, or a free and a share could deadlock. +func TestReleaseRefusedUnderBitmapLock(t *testing.T) { + dev, cleanup := createTestDevice(t, 32<<20) + defer cleanup() + var uuid [16]byte + copy(uuid[:], "test-node-uuid00") + mgr := lock.NewManager(dev, 16<<20, 10<<20, uuid, 0) + refs := NewRegion(dev, 0, SizeForBlocks(1000), 1000, mgr) + ctx := context.Background() + if err := mgr.Acquire(ctx, lock.LockTypeBlockBitmap, 0, lock.LockModeExclusive); err != nil { + t.Fatal(err) + } + defer func() { _ = mgr.Release(lock.LockTypeBlockBitmap, 0) }() + if _, err := refs.Release(ctx, []uint64{1}); !errors.Is(err, lock.ErrDeadlockRisk) { + t.Fatalf("Release under the bitmap lock: %v, want ErrDeadlockRisk", err) + } +} diff --git a/internal/snapshot/worker_test.go b/internal/snapshot/worker_test.go index 06870a86..5cba80c4 100644 --- a/internal/snapshot/worker_test.go +++ b/internal/snapshot/worker_test.go @@ -163,7 +163,7 @@ func (env *workerEnv) snapshot(file *inode.Inode, name string, state State) *Des if err != nil { env.t.Fatal(err) } - if err := env.refs.Share(env.ctx, blocks); err != nil { + if _, err := env.refs.Share(env.ctx, blocks); err != nil { env.t.Fatal(err) } if err := env.ext.CopyExtentsForClone(env.ctx, file, data); err != nil { diff --git a/tests/integration/helpers.go b/tests/integration/helpers.go index 61e1c063..984d90dd 100644 --- a/tests/integration/helpers.go +++ b/tests/integration/helpers.go @@ -332,38 +332,23 @@ func (m *MountedFS) WaitForMount(timeout time.Duration) error { return fmt.Errorf("timeout waiting for mount after %v", timeout) } -// unmountBusyTimeout is how long Unmount retries fusermount while the mount is -// busy: a FUSE release still in flight after close, or a desktop indexer -// crawling the mount, keeps it busy for a moment. -const unmountBusyTimeout = 10 * time.Second - -// Unmount unmounts the filesystem and waits for the mount process to run its -// clean shutdown. If the mount stays busy, it kills the process and detaches -// the dead mount, so a later Mount at the same path can work, and returns an -// error. +// Unmount unmounts the filesystem using fusermount. func (m *MountedFS) Unmount() error { - var unmountErr error - start := time.Now() - for busy := 0; ; busy++ { - output, err := exec.Command("fusermount", "-u", m.MountPoint).CombinedOutput() - if err == nil || !m.IsMounted() { - unmountErr = nil - if busy > 0 { - m.t.Logf("fusermount -u succeeded after the mount was busy for %v", time.Since(start).Round(time.Millisecond)) - } - break - } - unmountErr = fmt.Errorf("fusermount -u %s: %v: %s", m.MountPoint, err, strings.TrimSpace(string(output))) - if !strings.Contains(string(output), "busy") || time.Since(start) > unmountBusyTimeout { - m.t.Log(unmountErr) - break - } - time.Sleep(100 * time.Millisecond) + // Use fusermount to unmount FIRST. + // This triggers the go-fuse server to exit cleanly, allowing + // the mount command to run its shutdown code (journal checkpoint, etc.) + // Do NOT cancel the context first - that would SIGKILL the process + // and skip the clean shutdown path where journal checkpointing happens. + cmd := exec.Command("fusermount", "-u", m.MountPoint) + output, err := cmd.CombinedOutput() + if err != nil { + // May fail if already unmounted + m.t.Logf("fusermount output: %s", output) } - // Do not cancel the context first: that kills the process before its - // clean shutdown checkpoints the journal. + // Wait for mount process to exit cleanly if m.MountCmd != nil && m.MountCmd.Process != nil { + // Give it time to run clean shutdown (journal checkpoint, etc.) done := make(chan error, 1) go func() { done <- m.MountCmd.Wait() @@ -375,6 +360,7 @@ func (m *MountedFS) Unmount() error { m.t.Logf("mount process exited: %v", err) } case <-time.After(10 * time.Second): + // Force kill only as last resort after generous timeout m.t.Log("Warning: mount process did not exit in time, force killing") if m.cancel != nil { m.cancel() @@ -383,14 +369,6 @@ func (m *MountedFS) Unmount() error { } } - if m.IsMounted() { - if output, err := exec.Command("fusermount", "-uz", m.MountPoint).CombinedOutput(); err != nil { - m.t.Logf("fusermount -uz %s: %v: %s", m.MountPoint, err, output) - } - } - if unmountErr != nil { - return unmountErr - } m.t.Log("Unmounted successfully") return nil } diff --git a/tests/test-manifest.yaml b/tests/test-manifest.yaml index d8ca7586..c468b68d 100644 --- a/tests/test-manifest.yaml +++ b/tests/test-manifest.yaml @@ -2240,6 +2240,41 @@ scenarios: environments: go: internal/lock/lock_test.go::TestStatsCountBlockedAcquires + - id: share-waits-for-uncounted-free + name: Share waits for a free of an uncounted block + description: Node A frees a block with no count under the bitmap lock while node B shares it; B's Share waits for the bitmap lock, skips the freed block, and no free block keeps a count + priority: go_only + environments: + go: internal/refcount/refcount_test.go::TestShareWaitsForUncountedFree + + - id: bitmap-free-if + name: Bitmap frees chosen blocks in one hold + description: FreeIf frees the blocks the caller picks, keeps the rest and skips blocks already free; HoldAllocated reports only allocated blocks + priority: go_only + environments: + go: internal/bitmap/bitmap_test.go::TestFreeIfAndHoldAllocated + + - id: unshared-delete-no-refcount-lock + name: Deleting unshared files skips the refcount lock + description: Deleting files no snapshot or clone shared frees their blocks with one bitmap lock hold per file and no refcount lock + priority: go_only + environments: + go: internal/goclusterfs/snapshot_test.go::TestDeletingUnsharedFilesTakesNoRefcountLock + + - id: release-refused-under-bitmap-lock + name: Refcount lock refused under the bitmap lock + description: Share takes the refcount lock and then the bitmap lock, so the lock-order checker refuses the refcount lock to a goroutine holding the bitmap lock + priority: go_only + environments: + go: internal/refcount/refcount_test.go::TestReleaseRefusedUnderBitmapLock + + - id: counted-frees-and-shares-across-nodes + name: Clone deletes and clones on two nodes + description: Node B clones a file while node A deletes the previous clone, 20 rounds; neither waits on the other, every block of the deleted clones is freed, and the source's counts come back to 1 + priority: go_only + environments: + go: internal/goclusterfs/snapshot_test.go::TestCountedFreesAndSharesAcrossNodes + - id: locks-no-wait-other-types name: Locks never wait on records of another type description: With one node holding a lock in every inode record, another node takes locks of every other type without waiting From 335a06dd942395654bdefa7e4ed7fe89104045c1 Mon Sep 17 00:00:00 2001 From: Matthew Mattox Date: Fri, 13 Nov 2026 23:02:34 -0600 Subject: [PATCH 2/3] test: keep main's integration helpers (#131) Co-Authored-By: Claude Opus 5.5 --- tests/integration/helpers.go | 50 ++++++++++++++++++++++++++---------- 1 file changed, 36 insertions(+), 14 deletions(-) diff --git a/tests/integration/helpers.go b/tests/integration/helpers.go index 984d90dd..61e1c063 100644 --- a/tests/integration/helpers.go +++ b/tests/integration/helpers.go @@ -332,23 +332,38 @@ func (m *MountedFS) WaitForMount(timeout time.Duration) error { return fmt.Errorf("timeout waiting for mount after %v", timeout) } -// Unmount unmounts the filesystem using fusermount. +// unmountBusyTimeout is how long Unmount retries fusermount while the mount is +// busy: a FUSE release still in flight after close, or a desktop indexer +// crawling the mount, keeps it busy for a moment. +const unmountBusyTimeout = 10 * time.Second + +// Unmount unmounts the filesystem and waits for the mount process to run its +// clean shutdown. If the mount stays busy, it kills the process and detaches +// the dead mount, so a later Mount at the same path can work, and returns an +// error. func (m *MountedFS) Unmount() error { - // Use fusermount to unmount FIRST. - // This triggers the go-fuse server to exit cleanly, allowing - // the mount command to run its shutdown code (journal checkpoint, etc.) - // Do NOT cancel the context first - that would SIGKILL the process - // and skip the clean shutdown path where journal checkpointing happens. - cmd := exec.Command("fusermount", "-u", m.MountPoint) - output, err := cmd.CombinedOutput() - if err != nil { - // May fail if already unmounted - m.t.Logf("fusermount output: %s", output) + var unmountErr error + start := time.Now() + for busy := 0; ; busy++ { + output, err := exec.Command("fusermount", "-u", m.MountPoint).CombinedOutput() + if err == nil || !m.IsMounted() { + unmountErr = nil + if busy > 0 { + m.t.Logf("fusermount -u succeeded after the mount was busy for %v", time.Since(start).Round(time.Millisecond)) + } + break + } + unmountErr = fmt.Errorf("fusermount -u %s: %v: %s", m.MountPoint, err, strings.TrimSpace(string(output))) + if !strings.Contains(string(output), "busy") || time.Since(start) > unmountBusyTimeout { + m.t.Log(unmountErr) + break + } + time.Sleep(100 * time.Millisecond) } - // Wait for mount process to exit cleanly + // Do not cancel the context first: that kills the process before its + // clean shutdown checkpoints the journal. if m.MountCmd != nil && m.MountCmd.Process != nil { - // Give it time to run clean shutdown (journal checkpoint, etc.) done := make(chan error, 1) go func() { done <- m.MountCmd.Wait() @@ -360,7 +375,6 @@ func (m *MountedFS) Unmount() error { m.t.Logf("mount process exited: %v", err) } case <-time.After(10 * time.Second): - // Force kill only as last resort after generous timeout m.t.Log("Warning: mount process did not exit in time, force killing") if m.cancel != nil { m.cancel() @@ -369,6 +383,14 @@ func (m *MountedFS) Unmount() error { } } + if m.IsMounted() { + if output, err := exec.Command("fusermount", "-uz", m.MountPoint).CombinedOutput(); err != nil { + m.t.Logf("fusermount -uz %s: %v: %s", m.MountPoint, err, output) + } + } + if unmountErr != nil { + return unmountErr + } m.t.Log("Unmounted successfully") return nil } From 96dab87f6645db71fbfa0fa876e6fee89bd58a49 Mon Sep 17 00:00:00 2001 From: Matthew Mattox Date: Fri, 13 Nov 2026 23:57:12 -0600 Subject: [PATCH 3/3] fix(alloc): address review notes on the free path Say what the guard really proves: a zero count read under the bitmap lock stays zero while the block is freed, not that an allocated block is owned. Document that Increment, IncrementBatch, Set and SetFlags skip the guard. HoldAllocated now rejects a block past the end of the volume, so a corrupt extent fails with EIO instead of retrying, and freeing an already free block warns again. Co-Authored-By: Claude Opus 5.5 --- internal/bitmap/bitmap.go | 10 ++++++---- internal/extent/tree_edit.go | 4 ++-- internal/refcount/refcount.go | 9 ++++++++- 3 files changed, 16 insertions(+), 7 deletions(-) diff --git a/internal/bitmap/bitmap.go b/internal/bitmap/bitmap.go index f845ff1d..ade90421 100644 --- a/internal/bitmap/bitmap.go +++ b/internal/bitmap/bitmap.go @@ -332,10 +332,9 @@ func (r *Region) releaseReserved(ctx context.Context, blocks []uint64) { } } -// flipBits marks each block allocated (or free) whose bit says otherwise, under -// the bitmap lock, and returns the blocks it changed, even on error. // HoldAllocated takes the bitmap lock and returns the blocks of blocks that are // allocated. The lock stays held, so none of them can be freed, until release. +// A block past the end of the volume is an error. func (r *Region) HoldAllocated(ctx context.Context, blocks []uint64) ([]uint64, func(), error) { if r.lockMgr != nil { if err := r.lockMgr.Acquire(ctx, lock.LockTypeBlockBitmap, 0, lock.LockModeExclusive); err != nil { @@ -353,7 +352,8 @@ func (r *Region) HoldAllocated(ctx context.Context, blocks []uint64) ([]uint64, var allocated []uint64 for _, b := range blocks { if b >= r.totalBlocks { - continue + release() + return nil, nil, fmt.Errorf("block %d: %w", b, ErrBlockOutOfRange) } sectorIdx := b / BitsPerSector data, ok := sectors[sectorIdx] @@ -412,7 +412,7 @@ func (r *Region) FreeIf(ctx context.Context, blocks []uint64, which func([]uint6 bit := b % BitsPerSector mask := byte(1) << (bit % 8) if data[bit/8]&mask == 0 { - logging.Debugf("bitmap.FreeIf: block %d already free", b) + log.Printf("[WARN] bitmap: freeing block %d, which is already free", b) continue } data[bit/8] &^= mask @@ -439,6 +439,8 @@ func (r *Region) FreeBatch(ctx context.Context, blocks []uint64) error { return err } +// flipBits marks each block allocated (or free) whose bit says otherwise, under +// the bitmap lock, and returns the blocks it changed, even on error. func (r *Region) flipBits(ctx context.Context, blocks []uint64, allocated bool) ([]uint64, error) { if r.lockMgr != nil { if err := r.lockMgr.Acquire(ctx, lock.LockTypeBlockBitmap, 0, lock.LockModeExclusive); err != nil { diff --git a/internal/extent/tree_edit.go b/internal/extent/tree_edit.go index 32e8ec45..f2cea438 100644 --- a/internal/extent/tree_edit.go +++ b/internal/extent/tree_edit.go @@ -749,8 +749,8 @@ func (m *Manager) freeBlocks(ctx context.Context, blocks []uint64) { if m.refs != nil { uncounted = m.refs.Uncounted } - // Only Share raises a count, and only under the bitmap lock, so a block with - // no count under that lock has this one owner and needs no refcount lock. + // Only Share raises a count, and only under the bitmap lock, so a count of 0 + // read under that lock stays 0 while the block is freed. counted, err := m.bitmap.FreeIf(ctx, blocks, uncounted) switch { case errors.Is(err, lock.ErrDeadlockRisk): diff --git a/internal/refcount/refcount.go b/internal/refcount/refcount.go index caedf72d..3f6532e5 100644 --- a/internal/refcount/refcount.go +++ b/internal/refcount/refcount.go @@ -116,7 +116,10 @@ type Region struct { // AllocationGuard is the block bitmap as Share needs it. A block with no count // is freed under the bitmap lock alone, so Share counts blocks only while -// holding that lock, and only blocks that are still allocated. +// holding that lock, and only blocks that are still allocated. An allocated +// block may still be on its way out, between Release and the bitmap free or +// while TRIM holds it, so Share's caller checks afterwards that the file still +// maps every block it counted. type AllocationGuard interface { HoldAllocated(ctx context.Context, blocks []uint64) (allocated []uint64, release func(), err error) } @@ -186,6 +189,7 @@ func (r *Region) Get(ctx context.Context, blockNum uint64) (Entry, error) { // Increment increases the reference count for a block. // Returns the new count after incrementing. +// It skips the bitmap guard that Share takes, so only offline repair and tests may call it. func (r *Region) Increment(ctx context.Context, blockNum uint64) (uint32, error) { if blockNum >= r.totalBlocks { return 0, ErrBlockOutOfRange @@ -259,6 +263,7 @@ func (r *Region) Decrement(ctx context.Context, blockNum uint64) (uint32, error) // Set directly sets the reference count for a block. // Used during initialization or recovery. For normal operations, use Increment/Decrement. +// It skips the bitmap guard that Share takes, so only offline repair and tests may call it. func (r *Region) Set(ctx context.Context, blockNum uint64, count uint32, flags EntryFlags) error { if blockNum >= r.totalBlocks { return ErrBlockOutOfRange @@ -283,6 +288,7 @@ func (r *Region) Set(ctx context.Context, blockNum uint64, count uint32, flags E } // SetFlags updates the flags for a block without changing the reference count. +// It skips the bitmap guard that Share takes, so only offline repair and tests may call it. func (r *Region) SetFlags(ctx context.Context, blockNum uint64, flags EntryFlags) error { if blockNum >= r.totalBlocks { return ErrBlockOutOfRange @@ -311,6 +317,7 @@ func (r *Region) SetFlags(ctx context.Context, blockNum uint64, flags EntryFlags // IncrementBatch increments reference counts for multiple blocks atomically. // This is more efficient than calling Increment individually for each block. // Returns the new counts after incrementing. +// It skips the bitmap guard that Share takes, so only offline repair and tests may call it. func (r *Region) IncrementBatch(ctx context.Context, blockNums []uint64) ([]uint32, error) { results := make([]uint32, len(blockNums)) err := r.updateBatch(ctx, blockNums, func(i int, e *Entry) (bool, error) {