From 259813f9e9fff5e9f86877fdedb0613e29ccddee Mon Sep 17 00:00:00 2001 From: oech3 <79379754+oech3@users.noreply.github.com> Date: Sun, 24 May 2026 01:05:22 +0900 Subject: [PATCH] Improve documents for splice modules --- src/uucore/src/lib/features/buf_copy/linux.rs | 1 + src/uucore/src/lib/features/pipes.rs | 14 ++++++-------- 2 files changed, 7 insertions(+), 8 deletions(-) diff --git a/src/uucore/src/lib/features/buf_copy/linux.rs b/src/uucore/src/lib/features/buf_copy/linux.rs index f8eaeb1d6..7de3ba609 100644 --- a/src/uucore/src/lib/features/buf_copy/linux.rs +++ b/src/uucore/src/lib/features/buf_copy/linux.rs @@ -26,6 +26,7 @@ pub fn copy_stream( if crate::pipes::splice_unbounded_auto(src, dest)? { // If the splice() call failed, fall back on writing "without buffering", or order of output would be wrong // unrelated for cp /dev/stdin since cp does not have multiple input? + // RawWriter also removes io::copy's specialization std::io::copy(src, &mut crate::io::RawWriter(dest))?; } Ok(()) diff --git a/src/uucore/src/lib/features/pipes.rs b/src/uucore/src/lib/features/pipes.rs index c4c6a99e0..fc39829a2 100644 --- a/src/uucore/src/lib/features/pipes.rs +++ b/src/uucore/src/lib/features/pipes.rs @@ -3,7 +3,7 @@ // For the full copyright and license information, please view the LICENSE // file that was distributed with this source code. -//! Thin zero-copy-related wrappers around functions. +//! Zero-copy-related functions. #![cfg(any(target_os = "linux", target_os = "android"))] @@ -41,10 +41,8 @@ pub fn pipe(s: usize) -> std::io::Result<(PipeReader, /// Up to `len` bytes are moved from `source` to `target`. Returns the number /// of successfully moved bytes. /// -/// At least one of `source` and `target` must be some sort of pipe. -/// To get around this requirement, consider splicing from your source into -/// a [`pipe`] and then from the pipe into your target (with `drain_pipe`): -/// this is still very efficient. +/// splice fails if both of `source` and `target` are not pipe. Consider using +/// splice_unbounded_broker or splice_unbounded_auto in the case. #[inline] pub fn splice(source: &impl AsFd, target: &impl AsFd, len: usize) -> rustix::io::Result { rustix::pipe::splice(source, None, target, None, len, SpliceFlags::empty()) @@ -107,8 +105,8 @@ pub fn splice_unbounded(source: &impl AsFd, dest: &mut impl AsFd) -> rustix::io: /// force-splice source to dest even both of them are not pipe via broker pipe /// returns Ok(Ok(())) if splice succeeds -/// returns Ok(Err()) if splice failed, but you can fallback to read/write -/// returns std::io::Result if splice from broker failed and read/write fallback from broker failed +/// returns Ok(Err(())) if splice failed, but you can fallback to read/write +/// returns Err(e) if splice from broker failed and read/write fallback from broker failed /// /// Thus, ?.is_err() returns serious error at early stage and checks that you can fallback /// This should not be used if one of them are pipe to save resources @@ -156,7 +154,7 @@ pub fn splice_unbounded_auto(source: &impl AsFd, dest: &mut impl AsFd) -> std::i Ok(fallback) } -/// splice `n` bytes with safe read/write fallback +/// splice `n` bytes with read/write fallback /// return actually sent bytes #[inline] pub fn send_n_bytes(input: impl AsFd, target: impl AsFd, n: u64) -> std::io::Result {