std/io/
copy.rs

1use super::{BorrowedBuf, BufReader, BufWriter, DEFAULT_BUF_SIZE, Read, Result, Write};
2use crate::alloc::Allocator;
3use crate::cmp;
4use crate::collections::VecDeque;
5use crate::io::IoSlice;
6use crate::mem::MaybeUninit;
7
8#[cfg(test)]
9mod tests;
10
11/// Copies the entire contents of a reader into a writer.
12///
13/// This function will continuously read data from `reader` and then
14/// write it into `writer` in a streaming fashion until `reader`
15/// returns EOF.
16///
17/// On success, the total number of bytes that were copied from
18/// `reader` to `writer` is returned.
19///
20/// If you want to copy the contents of one file to another and you’re
21/// working with filesystem paths, see the [`fs::copy`] function.
22///
23/// [`fs::copy`]: crate::fs::copy
24///
25/// # Errors
26///
27/// This function will return an error immediately if any call to [`read`] or
28/// [`write`] returns an error. All instances of [`ErrorKind::Interrupted`] are
29/// handled by this function and the underlying operation is retried.
30///
31/// [`read`]: Read::read
32/// [`write`]: Write::write
33/// [`ErrorKind::Interrupted`]: crate::io::ErrorKind::Interrupted
34///
35/// # Examples
36///
37/// ```
38/// use std::io;
39///
40/// fn main() -> io::Result<()> {
41///     let mut reader: &[u8] = b"hello";
42///     let mut writer: Vec<u8> = vec![];
43///
44///     io::copy(&mut reader, &mut writer)?;
45///
46///     assert_eq!(&b"hello"[..], &writer[..]);
47///     Ok(())
48/// }
49/// ```
50///
51/// # Platform-specific behavior
52///
53/// On Linux (including Android), this function uses `copy_file_range(2)`,
54/// `sendfile(2)` or `splice(2)` syscalls to move data directly between file
55/// descriptors if possible.
56///
57/// Note that platform-specific behavior [may change in the future][changes].
58///
59/// [changes]: crate::io#platform-specific-behavior
60#[stable(feature = "rust1", since = "1.0.0")]
61pub fn copy<R: ?Sized, W: ?Sized>(reader: &mut R, writer: &mut W) -> Result<u64>
62where
63    R: Read,
64    W: Write,
65{
66    cfg_select! {
67        any(target_os = "linux", target_os = "android") => {
68            crate::sys::kernel_copy::copy_spec(reader, writer)
69        }
70        _ => {
71            generic_copy(reader, writer)
72        }
73    }
74}
75
76/// The userspace read-write-loop implementation of `io::copy` that is used when
77/// OS-specific specializations for copy offloading are not available or not applicable.
78pub(crate) fn generic_copy<R: ?Sized, W: ?Sized>(reader: &mut R, writer: &mut W) -> Result<u64>
79where
80    R: Read,
81    W: Write,
82{
83    let read_buf = BufferedReaderSpec::buffer_size(reader);
84    let write_buf = BufferedWriterSpec::buffer_size(writer);
85
86    if read_buf >= DEFAULT_BUF_SIZE && read_buf >= write_buf {
87        return BufferedReaderSpec::copy_to(reader, writer);
88    }
89
90    BufferedWriterSpec::copy_from(writer, reader)
91}
92
93/// Specialization of the read-write loop that reuses the internal
94/// buffer of a BufReader. If there's no buffer then the writer side
95/// should be used instead.
96trait BufferedReaderSpec {
97    fn buffer_size(&self) -> usize;
98
99    fn copy_to(&mut self, to: &mut (impl Write + ?Sized)) -> Result<u64>;
100}
101
102impl<T> BufferedReaderSpec for T
103where
104    Self: Read,
105    T: ?Sized,
106{
107    #[inline]
108    default fn buffer_size(&self) -> usize {
109        0
110    }
111
112    default fn copy_to(&mut self, _to: &mut (impl Write + ?Sized)) -> Result<u64> {
113        unreachable!("only called from specializations")
114    }
115}
116
117impl BufferedReaderSpec for &[u8] {
118    fn buffer_size(&self) -> usize {
119        // prefer this specialization since the source "buffer" is all we'll ever need,
120        // even if it's small
121        usize::MAX
122    }
123
124    fn copy_to(&mut self, to: &mut (impl Write + ?Sized)) -> Result<u64> {
125        let len = self.len();
126        to.write_all(self)?;
127        *self = &self[len..];
128        Ok(len as u64)
129    }
130}
131
132impl<A: Allocator> BufferedReaderSpec for VecDeque<u8, A> {
133    fn buffer_size(&self) -> usize {
134        // prefer this specialization since the source "buffer" is all we'll ever need,
135        // even if it's small
136        usize::MAX
137    }
138
139    fn copy_to(&mut self, to: &mut (impl Write + ?Sized)) -> Result<u64> {
140        let len = self.len();
141        let (front, back) = self.as_slices();
142        let bufs = &mut [IoSlice::new(front), IoSlice::new(back)];
143        to.write_all_vectored(bufs)?;
144        self.clear();
145        Ok(len as u64)
146    }
147}
148
149impl<I> BufferedReaderSpec for BufReader<I>
150where
151    Self: Read,
152    I: ?Sized,
153{
154    fn buffer_size(&self) -> usize {
155        self.capacity()
156    }
157
158    fn copy_to(&mut self, to: &mut (impl Write + ?Sized)) -> Result<u64> {
159        let mut len = 0;
160
161        loop {
162            // Hack: this relies on `impl Read for BufReader` always calling fill_buf
163            // if the buffer is empty, even for empty slices.
164            // It can't be called directly here since specialization prevents us
165            // from adding I: Read
166            match self.read(&mut []) {
167                Ok(_) => {}
168                Err(e) if e.is_interrupted() => continue,
169                Err(e) => return Err(e),
170            }
171            let buf = self.buffer();
172            if self.buffer().len() == 0 {
173                return Ok(len);
174            }
175
176            // In case the writer side is a BufWriter then its write_all
177            // implements an optimization that passes through large
178            // buffers to the underlying writer. That code path is #[cold]
179            // but we're still avoiding redundant memcopies when doing
180            // a copy between buffered inputs and outputs.
181            to.write_all(buf)?;
182            len += buf.len() as u64;
183            self.discard_buffer();
184        }
185    }
186}
187
188/// Specialization of the read-write loop that either uses a stack buffer
189/// or reuses the internal buffer of a BufWriter
190trait BufferedWriterSpec: Write {
191    fn buffer_size(&self) -> usize;
192
193    fn copy_from<R: Read + ?Sized>(&mut self, reader: &mut R) -> Result<u64>;
194}
195
196impl<W: Write + ?Sized> BufferedWriterSpec for W {
197    #[inline]
198    default fn buffer_size(&self) -> usize {
199        0
200    }
201
202    default fn copy_from<R: Read + ?Sized>(&mut self, reader: &mut R) -> Result<u64> {
203        stack_buffer_copy(reader, self)
204    }
205}
206
207impl<I: Write + ?Sized> BufferedWriterSpec for BufWriter<I> {
208    fn buffer_size(&self) -> usize {
209        self.capacity()
210    }
211
212    fn copy_from<R: Read + ?Sized>(&mut self, reader: &mut R) -> Result<u64> {
213        if self.capacity() < DEFAULT_BUF_SIZE {
214            return stack_buffer_copy(reader, self);
215        }
216
217        let mut len = 0;
218        let mut init = 0;
219
220        loop {
221            let buf = self.buffer_mut();
222            let mut read_buf: BorrowedBuf<'_> = buf.spare_capacity_mut().into();
223
224            unsafe {
225                // SAFETY: init is either 0 or the init_len from the previous iteration.
226                read_buf.set_init(init);
227            }
228
229            if read_buf.capacity() >= DEFAULT_BUF_SIZE {
230                let mut cursor = read_buf.unfilled();
231                match reader.read_buf(cursor.reborrow()) {
232                    Ok(()) => {
233                        let bytes_read = cursor.written();
234
235                        if bytes_read == 0 {
236                            return Ok(len);
237                        }
238
239                        init = read_buf.init_len() - bytes_read;
240                        len += bytes_read as u64;
241
242                        // SAFETY: BorrowedBuf guarantees all of its filled bytes are init
243                        unsafe { buf.set_len(buf.len() + bytes_read) };
244
245                        // Read again if the buffer still has enough capacity, as BufWriter itself would do
246                        // This will occur if the reader returns short reads
247                    }
248                    Err(ref e) if e.is_interrupted() => {}
249                    Err(e) => return Err(e),
250                }
251            } else {
252                // All the bytes that were already in the buffer are initialized,
253                // treat them as such when the buffer is flushed.
254                init += buf.len();
255
256                self.flush_buf()?;
257            }
258        }
259    }
260}
261
262impl BufferedWriterSpec for Vec<u8> {
263    fn buffer_size(&self) -> usize {
264        cmp::max(DEFAULT_BUF_SIZE, self.capacity() - self.len())
265    }
266
267    fn copy_from<R: Read + ?Sized>(&mut self, reader: &mut R) -> Result<u64> {
268        reader.read_to_end(self).map(|bytes| u64::try_from(bytes).expect("usize overflowed u64"))
269    }
270}
271
272pub fn stack_buffer_copy<R: Read + ?Sized, W: Write + ?Sized>(
273    reader: &mut R,
274    writer: &mut W,
275) -> Result<u64> {
276    let buf: &mut [_] = &mut [MaybeUninit::uninit(); DEFAULT_BUF_SIZE];
277    let mut buf: BorrowedBuf<'_> = buf.into();
278
279    let mut len = 0;
280
281    loop {
282        match reader.read_buf(buf.unfilled()) {
283            Ok(()) => {}
284            Err(e) if e.is_interrupted() => continue,
285            Err(e) => return Err(e),
286        };
287
288        if buf.filled().is_empty() {
289            break;
290        }
291
292        len += buf.filled().len() as u64;
293        writer.write_all(buf.filled())?;
294        buf.clear();
295    }
296
297    Ok(len)
298}
std/io/copy.rs

std/io/
copy.rs
