BufWriter: Note non-obvious safety assumption in BorrowedBuf::set_init usage.

Author: briansmith

library/std/src/io/buffered/bufwriter.rs

@@ -193,6 +193,12 @@ impl<W: ?Sized + Write> BufWriter<W> {
     /// `write`), any 0-length writes from `inner` must be reported as i/o
     /// errors from this method.
     pub(in crate::io) fn flush_buf(&mut self) -> io::Result<()> {
+        // SAFETY: `<BufWriter as BufferedWriterSpec>::copy_from` requires that `self.buf`'s spare
+        // capacity is preserved. This function does not grow `self.buf` or explicitly shrink its
+        // capacity; `Vec` guarantees that this is sufficient to avoid it re-allocating. We never
+        // de-initialize the spare capacity of `self.buf` and we assume none of the `Vec` methods
+        // used here will do so either.
+
         /// Helper struct to ensure the buffer is updated after all the writes
         /// are complete. It tracks the number of written bytes and drains them
         /// all from the front of the buffer when dropped.

library/std/src/io/copy.rs

@@ -219,9 +219,11 @@ impl<I: Write + ?Sized> BufferedWriterSpec for BufWriter<I> {
         loop {
             let buf = self.buffer_mut();
             let mut read_buf: BorrowedBuf<'_> = buf.spare_capacity_mut().into();
-
             if init {
-                // SAFETY: init is either 0 or the init_len from the previous iteration.
+                // SAFETY: `init` is only true after `reader` initializes `read_buf`. `flush_buf`
+                // guarantees that it won't cause any part of the spare capacity to become
+                // uninitialized or cause `self.buf` to reallocate, so it is OK to persist this
+                // across `flush_buf` calls.
                 unsafe { read_buf.set_init() };
             }