docs: audit macOS fast_io fallback vs Linux io_uring (#1652)#4008
Merged
Conversation
Static, source-grounded audit of the macOS fallback chain in crates/fast_io/. Maps each Linux io_uring path to its macOS equivalent, identifies that MacosWriter (F_NOCACHE + writev) is implemented but unwired from the disk-commit dispatcher, and recommends a one-screen fix in disk_commit/process.rs to deliver the win.
github-actions
Bot
added
the
documentation
This was referenced May 14, 2026
oferchen
added a commit
that referenced
this pull request
May 14, 2026
Darwin ships a BSD-style sendfile(2) syscall, but the dispatch in crates/fast_io/src/sendfile.rs only branched on Linux and fell through to a read/write loop on every other unix target. The macOS fast_io audit at docs/audits/macos-fastio-fallback.md flagged this as one of two unshipped wins identified during the post-merge review of PR #4008. This change adds a target_os = "macos" arm in send_file_to_fd and send_file_to_fd_with_policy that calls libc::sendfile with the Darwin signature: int sendfile(int fd, int s, off_t offset, off_t *len, struct sf_hdtr *hdtr, int flags); The implementation handles the in/out `len` parameter (bytes to send -> bytes actually sent), treats a return of 0 as success, and preserves the "transfer from the current file position" contract by querying the source offset with lseek(SEEK_CUR) and advancing the position with lseek(SEEK_SET) after the transfer. Partial sends on EAGAIN/EINTR are reported as forward progress so the socket peer always sees a consistent prefix. Non-socket destinations (pipes, regular files) fail with ENOTSOCK; the dispatch transparently falls back to the buffered read/write loop in that case, matching the behaviour Linux already had for non-sendfile-capable targets. Tests gated to target_os = "macos" exercise the new path through a SOCK_STREAM socketpair (native sendfile fast path), the public dispatch entry point, and a pipe destination that must fall back to read/write. Refs #2152.
oferchen
added a commit
that referenced
this pull request
May 18, 2026
Static, source-grounded audit of the macOS fallback chain in crates/fast_io/. Maps each Linux io_uring path to its macOS equivalent, identifies that MacosWriter (F_NOCACHE + writev) is implemented but unwired from the disk-commit dispatcher, and recommends a one-screen fix in disk_commit/process.rs to deliver the win.
oferchen
added a commit
that referenced
this pull request
May 18, 2026
Darwin ships a BSD-style sendfile(2) syscall, but the dispatch in crates/fast_io/src/sendfile.rs only branched on Linux and fell through to a read/write loop on every other unix target. The macOS fast_io audit at docs/audits/macos-fastio-fallback.md flagged this as one of two unshipped wins identified during the post-merge review of PR #4008. This change adds a target_os = "macos" arm in send_file_to_fd and send_file_to_fd_with_policy that calls libc::sendfile with the Darwin signature: int sendfile(int fd, int s, off_t offset, off_t *len, struct sf_hdtr *hdtr, int flags); The implementation handles the in/out `len` parameter (bytes to send -> bytes actually sent), treats a return of 0 as success, and preserves the "transfer from the current file position" contract by querying the source offset with lseek(SEEK_CUR) and advancing the position with lseek(SEEK_SET) after the transfer. Partial sends on EAGAIN/EINTR are reported as forward progress so the socket peer always sees a consistent prefix. Non-socket destinations (pipes, regular files) fail with ENOTSOCK; the dispatch transparently falls back to the buffered read/write loop in that case, matching the behaviour Linux already had for non-sendfile-capable targets. Tests gated to target_os = "macos" exercise the new path through a SOCK_STREAM socketpair (native sendfile fast path), the public dispatch entry point, and a pipe destination that must fall back to read/write. Refs #2152.
oferchen
added a commit
that referenced
this pull request
May 18, 2026
Darwin ships a BSD-style sendfile(2) syscall, but the dispatch in crates/fast_io/src/sendfile.rs only branched on Linux and fell through to a read/write loop on every other unix target. The macOS fast_io audit at docs/audits/macos-fastio-fallback.md flagged this as one of two unshipped wins identified during the post-merge review of PR #4008. This change adds a target_os = "macos" arm in send_file_to_fd and send_file_to_fd_with_policy that calls libc::sendfile with the Darwin signature: int sendfile(int fd, int s, off_t offset, off_t *len, struct sf_hdtr *hdtr, int flags); The implementation handles the in/out `len` parameter (bytes to send -> bytes actually sent), treats a return of 0 as success, and preserves the "transfer from the current file position" contract by querying the source offset with lseek(SEEK_CUR) and advancing the position with lseek(SEEK_SET) after the transfer. Partial sends on EAGAIN/EINTR are reported as forward progress so the socket peer always sees a consistent prefix. Non-socket destinations (pipes, regular files) fail with ENOTSOCK; the dispatch transparently falls back to the buffered read/write loop in that case, matching the behaviour Linux already had for non-sendfile-capable targets. Tests gated to target_os = "macos" exercise the new path through a SOCK_STREAM socketpair (native sendfile fast path), the public dispatch entry point, and a pipe destination that must fall back to read/write. Refs #2152.
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
1 participant
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
docs/audits/macos-fastio-fallback.md, a static source-grounded audit of the macOS fallback path incrates/fast_io/(closes Enforce coverage thresholds in CI #1652).StdFileReader/StdFileWriterfromcrates/fast_io/src/traits.rsvia the stub atcrates/fast_io/src/io_uring_stub.rs, plus thePlatformCopyclonefile / fcopyfile chain atcrates/fast_io/src/platform_copy/dispatch.rs).MacosWritertype atcrates/fast_io/src/macos_io.rs:58(F_NOCACHE >= 1 MiB plus writev withMAX_IOV_COUNT = 64) is implemented, exported fromcrates/fast_io/src/lib.rs:155, and has zero callers outside its own tests. Wiring it intomake_writeratcrates/transfer/src/disk_commit/process.rs:269is a one-screen change.Test plan
cargo fmt --all -- --check(no Rust changes).docs/audits/macos-fastio-fallback.mdon GitHub and verify all in-repo paths and line refs resolve.