forkvm: clone fork files via FICLONE reflink with sparse-copy fallback#212
Merged
Conversation
CopyGuestDirectory now attempts an FICLONE per regular file before falling back to the existing SEEK_DATA/SEEK_HOLE sparse copy. On btrfs/xfs+reflink the per-fork file copy collapses to a metadata operation, leaving the existing sparse-copy path intact for filesystems that don't support copy-on-write. The reflink path short-circuits after the first observed "unsupported"-class error from FICLONE so we don't repay the kernel rejection on every file. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
The reflink fast path now succeeds before sparse seeking is invoked, so the test must disable reflink to exercise the sparse fallback.
sjmiller609
commented
May 13, 2026
Walks the snapshot guest dir after ForkSnapshot, FIEMAPs each regular file against its counterpart under the fork instance dir, and fails if no pair shares a physical extent. A successful FICLONE leaves both files pointing at the same extents, so disjoint physical offsets across every inspected file means the fast path silently fell back to a full byte copy. Requires a reflink-capable scratch filesystem (XFS reflink=1, btrfs, ZFS). Linux-only; non-Linux platforms get a no-op stub since they only exercise the sparse-copy fallback today.
|
Firetiger deploy monitoring skipped This PR didn't match the auto-monitor filter configured on your GitHub connection:
Reason: PR modifies forkvm package (packages/api/lib/forkvm) which is not an API endpoint or Temporal workflow as specified in the filter. To monitor this PR anyway, reply with |
sjmiller609
commented
May 13, 2026
hiroTamada
approved these changes
May 13, 2026
hiroTamada
approved these changes
May 13, 2026
Contributor
hiroTamada
left a comment
hiroTamada
left a comment
There was a problem hiding this comment.
looks good to me. Excited for the optimization.
I learned FICONE for the first time today. Thank you for letting me review this.
hiroTamada
approved these changes
May 13, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
forkvm.CopyGuestDirectoryso fork data dirs share extents with their source on supporting filesystems (XFS reflinks, btrfs, ZFS).Why
Snapshot fan-out forks bottleneck on the rootfs copy. FICLONE makes the per-fork copy O(metadata) instead of O(bytes), which is a ~10x speedup on warm caches and removes write amplification on cold ones. Falling back keeps macOS/non-XFS dev environments working.
Test plan
go test ./lib/forkvm/...(unit tests cover both reflink and sparse fallback paths via fault injection)🤖 Generated with Claude Code
Note
Medium Risk
Changes the core fork copy path to prefer Linux
FICLONEreflinks, which can affect snapshot/fork correctness and error handling if ioctl behavior differs across filesystems. Fallbacks and tests reduce risk, but it still touches performance-critical file-copy logic.Overview
forkvm.CopyGuestDirectorynow prefers a Linux-onlyFICLONEreflink clone for regular files, and falls back to the existing sparse extent copy when the filesystem/platform rejects reflinks (with a per-copy “reflink unsupported” sticky state to avoid repeated ioctl attempts).Tests were updated/added to force and validate the fallback path, smoke-test the default reflink attempt, and in
instancesintegration tests (Linux) assert that forks actually share physical extents viaFIEMAPwhen running on a reflink-capable filesystem.Reviewed by Cursor Bugbot for commit 9bfce24. Bugbot is set up for automated code reviews on this repo. Configure here.