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

   1 use crate::error;
   2 use crate::fmt;
   3 use crate::io::{
   4     self, ErrorKind, IntoInnerError, IoSlice, Seek, SeekFrom, Write, DEFAULT_BUF_SIZE,
   5 };
   6 use crate::mem;
   7 use crate::ptr;
   8
   9 /// Wraps a writer and buffers its output.
  10 ///
  11 /// It can be excessively inefficient to work directly with something that
  12 /// implements [`Write`]. For example, every call to
  13 /// [`write`][`TcpStream::write`] on [`TcpStream`] results in a system call. A
  14 /// `BufWriter<W>` keeps an in-memory buffer of data and writes it to an underlying
  15 /// writer in large, infrequent batches.
  16 ///
  17 /// `BufWriter<W>` can improve the speed of programs that make *small* and
  18 /// *repeated* write calls to the same file or network socket. It does not
  19 /// help when writing very large amounts at once, or writing just one or a few
  20 /// times. It also provides no advantage when writing to a destination that is
  21 /// in memory, like a <code>[Vec]\<u8></code>.
  22 ///
  23 /// It is critical to call [`flush`] before `BufWriter<W>` is dropped. Though
  24 /// dropping will attempt to flush the contents of the buffer, any errors
  25 /// that happen in the process of dropping will be ignored. Calling [`flush`]
  26 /// ensures that the buffer is empty and thus dropping will not even attempt
  27 /// file operations.
  28 ///
  29 /// # Examples
  30 ///
  31 /// Let's write the numbers one through ten to a [`TcpStream`]:
  32 ///
  33 /// ```no_run
  34 /// use std::io::prelude::*;
  35 /// use std::net::TcpStream;
  36 ///
  37 /// let mut stream = TcpStream::connect("127.0.0.1:34254").unwrap();
  38 ///
  39 /// for i in 0..10 {
  40 ///     stream.write(&[i+1]).unwrap();
  41 /// }
  42 /// ```
  43 ///
  44 /// Because we're not buffering, we write each one in turn, incurring the
  45 /// overhead of a system call per byte written. We can fix this with a
  46 /// `BufWriter<W>`:
  47 ///
  48 /// ```no_run
  49 /// use std::io::prelude::*;
  50 /// use std::io::BufWriter;
  51 /// use std::net::TcpStream;
  52 ///
  53 /// let mut stream = BufWriter::new(TcpStream::connect("127.0.0.1:34254").unwrap());
  54 ///
  55 /// for i in 0..10 {
  56 ///     stream.write(&[i+1]).unwrap();
  57 /// }
  58 /// stream.flush().unwrap();
  59 /// ```
  60 ///
  61 /// By wrapping the stream with a `BufWriter<W>`, these ten writes are all grouped
  62 /// together by the buffer and will all be written out in one system call when
  63 /// the `stream` is flushed.
  64 ///
  65 // HACK(#78696): can't use `crate` for associated items
  66 /// [`TcpStream::write`]: super::super::super::net::TcpStream::write
  67 /// [`TcpStream`]: crate::net::TcpStream
  68 /// [`flush`]: BufWriter::flush
  69 #[stable(feature = "rust1", since = "1.0.0")]
  70 pub struct BufWriter<W: Write> {
  71     inner: W,
  72     // The buffer. Avoid using this like a normal `Vec` in common code paths.
  73     // That is, don't use `buf.push`, `buf.extend_from_slice`, or any other
  74     // methods that require bounds checking or the like. This makes an enormous
  75     // difference to performance (we may want to stop using a `Vec` entirely).
  76     buf: Vec<u8>,
  77     // #30888: If the inner writer panics in a call to write, we don't want to
  78     // write the buffered data a second time in BufWriter's destructor. This
  79     // flag tells the Drop impl if it should skip the flush.
  80     panicked: bool,
  81 }
  82
  83 impl<W: Write> BufWriter<W> {
  84     /// Creates a new `BufWriter<W>` with a default buffer capacity. The default is currently 8 KB,
  85     /// but may change in the future.
  86     ///
  87     /// # Examples
  88     ///
  89     /// ```no_run
  90     /// use std::io::BufWriter;
  91     /// use std::net::TcpStream;
  92     ///
  93     /// let mut buffer = BufWriter::new(TcpStream::connect("127.0.0.1:34254").unwrap());
  94     /// ```
  95     #[stable(feature = "rust1", since = "1.0.0")]
  96     pub fn new(inner: W) -> BufWriter<W> {
  97         BufWriter::with_capacity(DEFAULT_BUF_SIZE, inner)
  98     }
  99
 100     /// Creates a new `BufWriter<W>` with at least the specified buffer capacity.
 101     ///
 102     /// # Examples
 103     ///
 104     /// Creating a buffer with a buffer of at least a hundred bytes.
 105     ///
 106     /// ```no_run
 107     /// use std::io::BufWriter;
 108     /// use std::net::TcpStream;
 109     ///
 110     /// let stream = TcpStream::connect("127.0.0.1:34254").unwrap();
 111     /// let mut buffer = BufWriter::with_capacity(100, stream);
 112     /// ```
 113     #[stable(feature = "rust1", since = "1.0.0")]
 114     pub fn with_capacity(capacity: usize, inner: W) -> BufWriter<W> {
 115         BufWriter { inner, buf: Vec::with_capacity(capacity), panicked: false }
 116     }
 117
 118     /// Send data in our local buffer into the inner writer, looping as
 119     /// necessary until either it's all been sent or an error occurs.
 120     ///
 121     /// Because all the data in the buffer has been reported to our owner as
 122     /// "successfully written" (by returning nonzero success values from
 123     /// `write`), any 0-length writes from `inner` must be reported as i/o
 124     /// errors from this method.
 125     pub(in crate::io) fn flush_buf(&mut self) -> io::Result<()> {
 126         /// Helper struct to ensure the buffer is updated after all the writes
 127         /// are complete. It tracks the number of written bytes and drains them
 128         /// all from the front of the buffer when dropped.
 129         struct BufGuard<'a> {
 130             buffer: &'a mut Vec<u8>,
 131             written: usize,
 132         }
 133
 134         impl<'a> BufGuard<'a> {
 135             fn new(buffer: &'a mut Vec<u8>) -> Self {
 136                 Self { buffer, written: 0 }
 137             }
 138
 139             /// The unwritten part of the buffer
 140             fn remaining(&self) -> &[u8] {
 141                 &self.buffer[self.written..]
 142             }
 143
 144             /// Flag some bytes as removed from the front of the buffer
 145             fn consume(&mut self, amt: usize) {
 146                 self.written += amt;
 147             }
 148
 149             /// true if all of the bytes have been written
 150             fn done(&self) -> bool {
 151                 self.written >= self.buffer.len()
 152             }
 153         }
 154
 155         impl Drop for BufGuard<'_> {
 156             fn drop(&mut self) {
 157                 if self.written > 0 {
 158                     self.buffer.drain(..self.written);
 159                 }
 160             }
 161         }
 162
 163         let mut guard = BufGuard::new(&mut self.buf);
 164         while !guard.done() {
 165             self.panicked = true;
 166             let r = self.inner.write(guard.remaining());
 167             self.panicked = false;
 168
 169             match r {
 170                 Ok(0) => {
 171                     return Err(io::const_io_error!(
 172                         ErrorKind::WriteZero,
 173                         "failed to write the buffered data",
 174                     ));
 175                 }
 176                 Ok(n) => guard.consume(n),
 177                 Err(ref e) if e.kind() == io::ErrorKind::Interrupted => {}
 178                 Err(e) => return Err(e),
 179             }
 180         }
 181         Ok(())
 182     }
 183
 184     /// Buffer some data without flushing it, regardless of the size of the
 185     /// data. Writes as much as possible without exceeding capacity. Returns
 186     /// the number of bytes written.
 187     pub(super) fn write_to_buf(&mut self, buf: &[u8]) -> usize {
 188         let available = self.spare_capacity();
 189         let amt_to_buffer = available.min(buf.len());
 190
 191         // SAFETY: `amt_to_buffer` is <= buffer's spare capacity by construction.
 192         unsafe {
 193             self.write_to_buffer_unchecked(&buf[..amt_to_buffer]);
 194         }
 195
 196         amt_to_buffer
 197     }
 198
 199     /// Gets a reference to the underlying writer.
 200     ///
 201     /// # Examples
 202     ///
 203     /// ```no_run
 204     /// use std::io::BufWriter;
 205     /// use std::net::TcpStream;
 206     ///
 207     /// let mut buffer = BufWriter::new(TcpStream::connect("127.0.0.1:34254").unwrap());
 208     ///
 209     /// // we can use reference just like buffer
 210     /// let reference = buffer.get_ref();
 211     /// ```
 212     #[stable(feature = "rust1", since = "1.0.0")]
 213     pub fn get_ref(&self) -> &W {
 214         &self.inner
 215     }
 216
 217     /// Gets a mutable reference to the underlying writer.
 218     ///
 219     /// It is inadvisable to directly write to the underlying writer.
 220     ///
 221     /// # Examples
 222     ///
 223     /// ```no_run
 224     /// use std::io::BufWriter;
 225     /// use std::net::TcpStream;
 226     ///
 227     /// let mut buffer = BufWriter::new(TcpStream::connect("127.0.0.1:34254").unwrap());
 228     ///
 229     /// // we can use reference just like buffer
 230     /// let reference = buffer.get_mut();
 231     /// ```
 232     #[stable(feature = "rust1", since = "1.0.0")]
 233     pub fn get_mut(&mut self) -> &mut W {
 234         &mut self.inner
 235     }
 236
 237     /// Returns a reference to the internally buffered data.
 238     ///
 239     /// # Examples
 240     ///
 241     /// ```no_run
 242     /// use std::io::BufWriter;
 243     /// use std::net::TcpStream;
 244     ///
 245     /// let buf_writer = BufWriter::new(TcpStream::connect("127.0.0.1:34254").unwrap());
 246     ///
 247     /// // See how many bytes are currently buffered
 248     /// let bytes_buffered = buf_writer.buffer().len();
 249     /// ```
 250     #[stable(feature = "bufreader_buffer", since = "1.37.0")]
 251     pub fn buffer(&self) -> &[u8] {
 252         &self.buf
 253     }
 254
 255     /// Returns a mutable reference to the internal buffer.
 256     ///
 257     /// This can be used to write data directly into the buffer without triggering writers
 258     /// to the underlying writer.
 259     ///
 260     /// That the buffer is a `Vec` is an implementation detail.
 261     /// Callers should not modify the capacity as there currently is no public API to do so
 262     /// and thus any capacity changes would be unexpected by the user.
 263     pub(in crate::io) fn buffer_mut(&mut self) -> &mut Vec<u8> {
 264         &mut self.buf
 265     }
 266
 267     /// Returns the number of bytes the internal buffer can hold without flushing.
 268     ///
 269     /// # Examples
 270     ///
 271     /// ```no_run
 272     /// use std::io::BufWriter;
 273     /// use std::net::TcpStream;
 274     ///
 275     /// let buf_writer = BufWriter::new(TcpStream::connect("127.0.0.1:34254").unwrap());
 276     ///
 277     /// // Check the capacity of the inner buffer
 278     /// let capacity = buf_writer.capacity();
 279     /// // Calculate how many bytes can be written without flushing
 280     /// let without_flush = capacity - buf_writer.buffer().len();
 281     /// ```
 282     #[stable(feature = "buffered_io_capacity", since = "1.46.0")]
 283     pub fn capacity(&self) -> usize {
 284         self.buf.capacity()
 285     }
 286
 287     /// Unwraps this `BufWriter<W>`, returning the underlying writer.
 288     ///
 289     /// The buffer is written out before returning the writer.
 290     ///
 291     /// # Errors
 292     ///
 293     /// An [`Err`] will be returned if an error occurs while flushing the buffer.
 294     ///
 295     /// # Examples
 296     ///
 297     /// ```no_run
 298     /// use std::io::BufWriter;
 299     /// use std::net::TcpStream;
 300     ///
 301     /// let mut buffer = BufWriter::new(TcpStream::connect("127.0.0.1:34254").unwrap());
 302     ///
 303     /// // unwrap the TcpStream and flush the buffer
 304     /// let stream = buffer.into_inner().unwrap();
 305     /// ```
 306     #[stable(feature = "rust1", since = "1.0.0")]
 307     pub fn into_inner(mut self) -> Result<W, IntoInnerError<BufWriter<W>>> {
 308         match self.flush_buf() {
 309             Err(e) => Err(IntoInnerError::new(self, e)),
 310             Ok(()) => Ok(self.into_parts().0),
 311         }
 312     }
 313
 314     /// Disassembles this `BufWriter<W>`, returning the underlying writer, and any buffered but
 315     /// unwritten data.
 316     ///
 317     /// If the underlying writer panicked, it is not known what portion of the data was written.
 318     /// In this case, we return `WriterPanicked` for the buffered data (from which the buffer
 319     /// contents can still be recovered).
 320     ///
 321     /// `into_parts` makes no attempt to flush data and cannot fail.
 322     ///
 323     /// # Examples
 324     ///
 325     /// ```
 326     /// use std::io::{BufWriter, Write};
 327     ///
 328     /// let mut buffer = [0u8; 10];
 329     /// let mut stream = BufWriter::new(buffer.as_mut());
 330     /// write!(stream, "too much data").unwrap();
 331     /// stream.flush().expect_err("it doesn't fit");
 332     /// let (recovered_writer, buffered_data) = stream.into_parts();
 333     /// assert_eq!(recovered_writer.len(), 0);
 334     /// assert_eq!(&buffered_data.unwrap(), b"ata");
 335     /// ```
 336     #[stable(feature = "bufwriter_into_parts", since = "1.56.0")]
 337     pub fn into_parts(mut self) -> (W, Result<Vec<u8>, WriterPanicked>) {
 338         let buf = mem::take(&mut self.buf);
 339         let buf = if !self.panicked { Ok(buf) } else { Err(WriterPanicked { buf }) };
 340
 341         // SAFETY: forget(self) prevents double dropping inner
 342         let inner = unsafe { ptr::read(&mut self.inner) };
 343         mem::forget(self);
 344
 345         (inner, buf)
 346     }
 347
 348     // Ensure this function does not get inlined into `write`, so that it
 349     // remains inlineable and its common path remains as short as possible.
 350     // If this function ends up being called frequently relative to `write`,
 351     // it's likely a sign that the client is using an improperly sized buffer
 352     // or their write patterns are somewhat pathological.
 353     #[cold]
 354     #[inline(never)]
 355     fn write_cold(&mut self, buf: &[u8]) -> io::Result<usize> {
 356         if buf.len() > self.spare_capacity() {
 357             self.flush_buf()?;
 358         }
 359
 360         // Why not len > capacity? To avoid a needless trip through the buffer when the input
 361         // exactly fills it. We'd just need to flush it to the underlying writer anyway.
 362         if buf.len() >= self.buf.capacity() {
 363             self.panicked = true;
 364             let r = self.get_mut().write(buf);
 365             self.panicked = false;
 366             r
 367         } else {
 368             // Write to the buffer. In this case, we write to the buffer even if it fills it
 369             // exactly. Doing otherwise would mean flushing the buffer, then writing this
 370             // input to the inner writer, which in many cases would be a worse strategy.
 371
 372             // SAFETY: There was either enough spare capacity already, or there wasn't and we
 373             // flushed the buffer to ensure that there is. In the latter case, we know that there
 374             // is because flushing ensured that our entire buffer is spare capacity, and we entered
 375             // this block because the input buffer length is less than that capacity. In either
 376             // case, it's safe to write the input buffer to our buffer.
 377             unsafe {
 378                 self.write_to_buffer_unchecked(buf);
 379             }
 380
 381             Ok(buf.len())
 382         }
 383     }
 384
 385     // Ensure this function does not get inlined into `write_all`, so that it
 386     // remains inlineable and its common path remains as short as possible.
 387     // If this function ends up being called frequently relative to `write_all`,
 388     // it's likely a sign that the client is using an improperly sized buffer
 389     // or their write patterns are somewhat pathological.
 390     #[cold]
 391     #[inline(never)]
 392     fn write_all_cold(&mut self, buf: &[u8]) -> io::Result<()> {
 393         // Normally, `write_all` just calls `write` in a loop. We can do better
 394         // by calling `self.get_mut().write_all()` directly, which avoids
 395         // round trips through the buffer in the event of a series of partial
 396         // writes in some circumstances.
 397
 398         if buf.len() > self.spare_capacity() {
 399             self.flush_buf()?;
 400         }
 401
 402         // Why not len > capacity? To avoid a needless trip through the buffer when the input
 403         // exactly fills it. We'd just need to flush it to the underlying writer anyway.
 404         if buf.len() >= self.buf.capacity() {
 405             self.panicked = true;
 406             let r = self.get_mut().write_all(buf);
 407             self.panicked = false;
 408             r
 409         } else {
 410             // Write to the buffer. In this case, we write to the buffer even if it fills it
 411             // exactly. Doing otherwise would mean flushing the buffer, then writing this
 412             // input to the inner writer, which in many cases would be a worse strategy.
 413
 414             // SAFETY: There was either enough spare capacity already, or there wasn't and we
 415             // flushed the buffer to ensure that there is. In the latter case, we know that there
 416             // is because flushing ensured that our entire buffer is spare capacity, and we entered
 417             // this block because the input buffer length is less than that capacity. In either
 418             // case, it's safe to write the input buffer to our buffer.
 419             unsafe {
 420                 self.write_to_buffer_unchecked(buf);
 421             }
 422
 423             Ok(())
 424         }
 425     }
 426
 427     // SAFETY: Requires `buf.len() <= self.buf.capacity() - self.buf.len()`,
 428     // i.e., that input buffer length is less than or equal to spare capacity.
 429     #[inline]
 430     unsafe fn write_to_buffer_unchecked(&mut self, buf: &[u8]) {
 431         debug_assert!(buf.len() <= self.spare_capacity());
 432         let old_len = self.buf.len();
 433         let buf_len = buf.len();
 434         let src = buf.as_ptr();
 435         let dst = self.buf.as_mut_ptr().add(old_len);
 436         ptr::copy_nonoverlapping(src, dst, buf_len);
 437         self.buf.set_len(old_len + buf_len);
 438     }
 439
 440     #[inline]
 441     fn spare_capacity(&self) -> usize {
 442         self.buf.capacity() - self.buf.len()
 443     }
 444 }
 445
 446 #[stable(feature = "bufwriter_into_parts", since = "1.56.0")]
 447 /// Error returned for the buffered data from `BufWriter::into_parts`, when the underlying
 448 /// writer has previously panicked.  Contains the (possibly partly written) buffered data.
 449 ///
 450 /// # Example
 451 ///
 452 /// ```
 453 /// use std::io::{self, BufWriter, Write};
 454 /// use std::panic::{catch_unwind, AssertUnwindSafe};
 455 ///
 456 /// struct PanickingWriter;
 457 /// impl Write for PanickingWriter {
 458 ///   fn write(&mut self, buf: &[u8]) -> io::Result<usize> { panic!() }
 459 ///   fn flush(&mut self) -> io::Result<()> { panic!() }
 460 /// }
 461 ///
 462 /// let mut stream = BufWriter::new(PanickingWriter);
 463 /// write!(stream, "some data").unwrap();
 464 /// let result = catch_unwind(AssertUnwindSafe(|| {
 465 ///     stream.flush().unwrap()
 466 /// }));
 467 /// assert!(result.is_err());
 468 /// let (recovered_writer, buffered_data) = stream.into_parts();
 469 /// assert!(matches!(recovered_writer, PanickingWriter));
 470 /// assert_eq!(buffered_data.unwrap_err().into_inner(), b"some data");
 471 /// ```
 472 pub struct WriterPanicked {
 473     buf: Vec<u8>,
 474 }
 475
 476 impl WriterPanicked {
 477     /// Returns the perhaps-unwritten data.  Some of this data may have been written by the
 478     /// panicking call(s) to the underlying writer, so simply writing it again is not a good idea.
 479     #[must_use = "`self` will be dropped if the result is not used"]
 480     #[stable(feature = "bufwriter_into_parts", since = "1.56.0")]
 481     pub fn into_inner(self) -> Vec<u8> {
 482         self.buf
 483     }
 484
 485     const DESCRIPTION: &'static str =
 486         "BufWriter inner writer panicked, what data remains unwritten is not known";
 487 }
 488
 489 #[stable(feature = "bufwriter_into_parts", since = "1.56.0")]
 490 impl error::Error for WriterPanicked {
 491     #[allow(deprecated, deprecated_in_future)]
 492     fn description(&self) -> &str {
 493         Self::DESCRIPTION
 494     }
 495 }
 496
 497 #[stable(feature = "bufwriter_into_parts", since = "1.56.0")]
 498 impl fmt::Display for WriterPanicked {
 499     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
 500         write!(f, "{}", Self::DESCRIPTION)
 501     }
 502 }
 503
 504 #[stable(feature = "bufwriter_into_parts", since = "1.56.0")]
 505 impl fmt::Debug for WriterPanicked {
 506     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
 507         f.debug_struct("WriterPanicked")
 508             .field("buffer", &format_args!("{}/{}", self.buf.len(), self.buf.capacity()))
 509             .finish()
 510     }
 511 }
 512
 513 #[stable(feature = "rust1", since = "1.0.0")]
 514 impl<W: Write> Write for BufWriter<W> {
 515     #[inline]
 516     fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
 517         // Use < instead of <= to avoid a needless trip through the buffer in some cases.
 518         // See `write_cold` for details.
 519         if buf.len() < self.spare_capacity() {
 520             // SAFETY: safe by above conditional.
 521             unsafe {
 522                 self.write_to_buffer_unchecked(buf);
 523             }
 524
 525             Ok(buf.len())
 526         } else {
 527             self.write_cold(buf)
 528         }
 529     }
 530
 531     #[inline]
 532     fn write_all(&mut self, buf: &[u8]) -> io::Result<()> {
 533         // Use < instead of <= to avoid a needless trip through the buffer in some cases.
 534         // See `write_all_cold` for details.
 535         if buf.len() < self.spare_capacity() {
 536             // SAFETY: safe by above conditional.
 537             unsafe {
 538                 self.write_to_buffer_unchecked(buf);
 539             }
 540
 541             Ok(())
 542         } else {
 543             self.write_all_cold(buf)
 544         }
 545     }
 546
 547     fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> io::Result<usize> {
 548         // FIXME: Consider applying `#[inline]` / `#[inline(never)]` optimizations already applied
 549         // to `write` and `write_all`. The performance benefits can be significant. See #79930.
 550         if self.get_ref().is_write_vectored() {
 551             // We have to handle the possibility that the total length of the buffers overflows
 552             // `usize` (even though this can only happen if multiple `IoSlice`s reference the
 553             // same underlying buffer, as otherwise the buffers wouldn't fit in memory). If the
 554             // computation overflows, then surely the input cannot fit in our buffer, so we forward
 555             // to the inner writer's `write_vectored` method to let it handle it appropriately.
 556             let saturated_total_len =
 557                 bufs.iter().fold(0usize, |acc, b| acc.saturating_add(b.len()));
 558
 559             if saturated_total_len > self.spare_capacity() {
 560                 // Flush if the total length of the input exceeds our buffer's spare capacity.
 561                 // If we would have overflowed, this condition also holds, and we need to flush.
 562                 self.flush_buf()?;
 563             }
 564
 565             if saturated_total_len >= self.buf.capacity() {
 566                 // Forward to our inner writer if the total length of the input is greater than or
 567                 // equal to our buffer capacity. If we would have overflowed, this condition also
 568                 // holds, and we punt to the inner writer.
 569                 self.panicked = true;
 570                 let r = self.get_mut().write_vectored(bufs);
 571                 self.panicked = false;
 572                 r
 573             } else {
 574                 // `saturated_total_len < self.buf.capacity()` implies that we did not saturate.
 575
 576                 // SAFETY: We checked whether or not the spare capacity was large enough above. If
 577                 // it was, then we're safe already. If it wasn't, we flushed, making sufficient
 578                 // room for any input <= the buffer size, which includes this input.
 579                 unsafe {
 580                     bufs.iter().for_each(|b| self.write_to_buffer_unchecked(b));
 581                 };
 582
 583                 Ok(saturated_total_len)
 584             }
 585         } else {
 586             let mut iter = bufs.iter();
 587             let mut total_written = if let Some(buf) = iter.by_ref().find(|&buf| !buf.is_empty()) {
 588                 // This is the first non-empty slice to write, so if it does
 589                 // not fit in the buffer, we still get to flush and proceed.
 590                 if buf.len() > self.spare_capacity() {
 591                     self.flush_buf()?;
 592                 }
 593                 if buf.len() >= self.buf.capacity() {
 594                     // The slice is at least as large as the buffering capacity,
 595                     // so it's better to write it directly, bypassing the buffer.
 596                     self.panicked = true;
 597                     let r = self.get_mut().write(buf);
 598                     self.panicked = false;
 599                     return r;
 600                 } else {
 601                     // SAFETY: We checked whether or not the spare capacity was large enough above.
 602                     // If it was, then we're safe already. If it wasn't, we flushed, making
 603                     // sufficient room for any input <= the buffer size, which includes this input.
 604                     unsafe {
 605                         self.write_to_buffer_unchecked(buf);
 606                     }
 607
 608                     buf.len()
 609                 }
 610             } else {
 611                 return Ok(0);
 612             };
 613             debug_assert!(total_written != 0);
 614             for buf in iter {
 615                 if buf.len() <= self.spare_capacity() {
 616                     // SAFETY: safe by above conditional.
 617                     unsafe {
 618                         self.write_to_buffer_unchecked(buf);
 619                     }
 620
 621                     // This cannot overflow `usize`. If we are here, we've written all of the bytes
 622                     // so far to our buffer, and we've ensured that we never exceed the buffer's
 623                     // capacity. Therefore, `total_written` <= `self.buf.capacity()` <= `usize::MAX`.
 624                     total_written += buf.len();
 625                 } else {
 626                     break;
 627                 }
 628             }
 629             Ok(total_written)
 630         }
 631     }
 632
 633     fn is_write_vectored(&self) -> bool {
 634         true
 635     }
 636
 637     fn flush(&mut self) -> io::Result<()> {
 638         self.flush_buf().and_then(|()| self.get_mut().flush())
 639     }
 640 }
 641
 642 #[stable(feature = "rust1", since = "1.0.0")]
 643 impl<W: Write> fmt::Debug for BufWriter<W>
 644 where
 645     W: fmt::Debug,
 646 {
 647     fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
 648         fmt.debug_struct("BufWriter")
 649             .field("writer", &self.inner)
 650             .field("buffer", &format_args!("{}/{}", self.buf.len(), self.buf.capacity()))
 651             .finish()
 652     }
 653 }
 654
 655 #[stable(feature = "rust1", since = "1.0.0")]
 656 impl<W: Write + Seek> Seek for BufWriter<W> {
 657     /// Seek to the offset, in bytes, in the underlying writer.
 658     ///
 659     /// Seeking always writes out the internal buffer before seeking.
 660     fn seek(&mut self, pos: SeekFrom) -> io::Result<u64> {
 661         self.flush_buf()?;
 662         self.get_mut().seek(pos)
 663     }
 664 }
 665
 666 #[stable(feature = "rust1", since = "1.0.0")]
 667 impl<W: Write> Drop for BufWriter<W> {
 668     fn drop(&mut self) {
 669         if !self.panicked {
 670             // dtors should not panic, so we ignore a failed flush
 671             let _r = self.flush_buf();
 672         }
 673     }
 674 }