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

Author: briansmith

library/alloc/src/raw_vec/mod.rs

@@ -71,6 +71,9 @@ const unsafe fn new_cap<T>(cap: usize) -> Cap {
 /// `Box<[T]>`, since `capacity()` won't yield the length.
 #[allow(missing_debug_implementations)]
 pub(crate) struct RawVec<T, A: Allocator = Global> {
+    // FIXME: Despite "Its uninitialized memory is scratch space that it may use however it wants"
+    // in `Vec`'s documentation, `BufWriter::flush_buf` relies on the scratch space being never
+    // de-initialized by several methods.
     inner: RawVecInner<A>,
     _marker: PhantomData<T>,
 }
@@ -83,6 +86,9 @@ pub(crate) struct RawVec<T, A: Allocator = Global> {
 /// as most operations don't need the actual type, just its layout.
 #[allow(missing_debug_implementations)]
 struct RawVecInner<A: Allocator = Global> {
+    // FIXME: Despite "Its uninitialized memory is scratch space that it may use however it wants"
+    // in `Vec`'s documentation, `BufWriter::flush_buf` relies on the scratch space being never
+    // de-initialized by several methods.
     ptr: Unique<u8>,
     /// Never used for ZSTs; it's `capacity()`'s responsibility to return usize::MAX in that case.
     ///

library/alloc/src/vec/mod.rs

@@ -436,6 +436,9 @@ mod spec_extend;
 #[doc(alias = "list")]
 #[doc(alias = "vector")]
 pub struct Vec<T, #[unstable(feature = "allocator_api", issue = "32838")] A: Allocator = Global> {
+    // FIXME: Despite "Its uninitialized memory is scratch space that it may use however it wants"
+    // mentioned above, `BufWriter::flush_buf` relies on the sctach space being never
+    // de-initialized by several methods.
     buf: RawVec<T, A>,
     len: usize,
 }

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

@@ -193,6 +193,13 @@ 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 by this function. 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, though nothing in `Vec`'s documentation
+        // guarantees this.
+
         /// 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

@@ -221,7 +221,10 @@ impl<I: Write + ?Sized> BufferedWriterSpec for BufWriter<I> {
             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() };
             }