qcow2-rs: fallocate via F_PUNCHHOLE on macOS

[sandrewh]

qcow2-rs: fallocate via F_PUNCHHOLE on macOS

Summary

Replace the macOS fallback in Qcow2IoTokio::fallocate (which previously wrote zeros via pwrite) with a real hole-punch using fcntl(F_PUNCHHOLE, &fpunchhole_t). This makes discard semantics actually reclaim host file space on Darwin hosts, mirroring the existing Linux fallocate(FALLOC_FL_PUNCH_HOLE) behavior.

Motivation

Qcow2IoOps::fallocate is the file-level punch primitive that Qcow2Dev calls (via call_fallocate) when it wants to zero a range AND release the host extents. On Linux this works as intended. On macOS the existing implementation in tokio_io.rs falls back to writing zeros via pwrite, which preserves the reads-as-zero contract but doesn't shrink the file — wasting disk space when callers discard large regions.

F_PUNCHHOLE has been available on macOS since 10.10 (Yosemite, 2014). It's the canonical macOS analogue of Linux's FALLOC_FL_PUNCH_HOLE | FALLOC_FL_KEEP_SIZE.

Behavior

• macOS: fcntl(F_PUNCHHOLE, &fpunchhole_t). File size unchanged, punched range reads as zeros, allocated host extents released.
• macOS APFS requires fp_offset and fp_length to be multiples of the volume block size (4096). Sub-block ranges return EINVAL. The implementation catches EINVAL / EOPNOTSUPP / ENOSYS and falls back to the existing zero-write path so the reads-as-zero contract still holds — the host file just doesn't shrink for that one call.
• Linux: unchanged.
• Other non-Linux non-macOS targets (Windows, FreeBSD with tokio backend): unchanged.

Tests

Three new tests in tests/fallocate.rs, platform-gated:

Test	Platform	What it asserts
fallocate_punch_hole_shrinks_st_blocks_on_linux	Linux	fallocate(PUNCH_HOLE) shrinks st_blocks; logical file size unchanged; punched range reads as zero; bytes outside untouched
fallocate_punch_hole_shrinks_st_blocks_on_macos	macOS	Same shape with F_PUNCHHOLE on a 4-KiB-aligned range
fallocate_sub_block_range_falls_back_to_zero_write_on_macos	macOS	Sub-block-aligned range (1 KiB offset, 1 KiB length) soft-fails to zero-write cleanly: no error, range reads as zeros, surrounding bytes untouched

Reproduce

On macOS:

cargo test --release --test fallocate

On Linux:

cargo test --release --test fallocate

Out of scope (intentional)

• No change to the Linux fallocate path.
• No new Qcow2IoOps trait methods or flags.
• No change to Qcow2Dev cluster-allocator semantics.

Disclosure

Co-developed with Claude Code (Claude Opus 4.7, 1M context). I reviewed every line and can answer questions about the design or implementation.

[ming1]

Maybe something like below is needed for fixing the test failure?

diff --git a/tests/fallocate.rs b/tests/fallocate.rs
index a0cf3bb..2328fed 100644
--- a/tests/fallocate.rs
+++ b/tests/fallocate.rs
@@ -86,6 +86,12 @@ fn fallocate_punch_hole_shrinks_st_blocks_on_linux() {
                 blocks_after < blocks_before,
                 "punch_hole must shrink allocated blocks: before={blocks_before} after={blocks_after}",
             );
+        } else {
+              // Production code (Qcow2Dev::call_fallocate) falls back to
+              // write-zeros when fallocate is not supported. Replicate
+              // that here so the reads-as-zero contract holds.
+              let zero_buf = vec![0u8; 32 * 1024];
+              io.write_from(16 * 1024, &zero_buf).await.unwrap();
         }
         // Either way: logical file size unchanged, punched/zeroed range
         // reads as zero, surrounding bytes untouched.

[sandrewh]

Thanks @ming1 — good catch, and you're exactly right. Qcow2IoTokio::fallocate is the raw IO layer with no write-zeros fallback (that's in Qcow2Dev::call_fallocate), so on the EOPNOTSUPP path the range stayed the 0xAB prefill and the reads-as-zero assertion would still fail — the test was broken at a different line than before.

Applied your suggested approach in f83a390: the not-punched branch now writes zeros + fsyncs, replicating exactly what production does, so the reads-as-zero contract holds on both paths. Pushed.