Debian Codegraph @

.cargo/vendor/core2/src/io/buffered.rs

raw
1 //! Buffering wrappers for I/O traits
2
3 use crate::io::{BufRead, Error, ErrorKind, Read, Result, Seek, SeekFrom, Write};
4 use core::{cmp, fmt};
5
6 /// The `BufReader<R, S>` struct adds buffering to any reader.
7 ///
8 /// It can be excessively inefficient to work directly with a [`Read`] instance.
9 /// For example, every call to [`read`][`TcpStream::read`] on [`TcpStream`]
10 /// results in a system call. A `BufReader<R, S>` performs large, infrequent reads on
11 /// the underlying [`Read`] and maintains an in-memory buffer of the results.
12 ///
13 /// `BufReader<R, S>` can improve the speed of programs that make *small* and
14 /// *repeated* read calls to the same file or network socket. It does not
15 /// help when reading very large amounts at once, or reading just one or a few
16 /// times. It also provides no advantage when reading from a source that is
17 /// already in memory, like a [`Vec`]`<u8>`.
18 ///
19 /// When the `BufReader<R, S>` is dropped, the contents of its buffer will be
20 /// discarded. Creating multiple instances of a `BufReader<R, S>` on the same
21 /// stream can cause data loss. Reading from the underlying reader after
22 /// unwrapping the `BufReader<R, S>` with [`BufReader::into_inner`] can also cause
23 /// data loss.
24 ///
25 /// [`TcpStream::read`]: Read::read
26 /// [`TcpStream`]: crate::net::TcpStream
27 ///
28 /// # Examples
29 ///
30 /// ```no_run
31 /// use std::prelude::*;
32 /// use core2::io::BufReader;
33 /// use std::fs::File;
34 ///
35 /// fn main() -> core::result::Result<()> {
36 /// let f = File::open("log.txt")?;
37 /// let mut reader = BufReader::new(f);
38 ///
39 /// let mut line = String::new();
40 /// let len = reader.read_line(&mut line)?;
41 /// println!("First line is {} bytes long", len);
42 /// Ok(())
43 /// }
44 /// ```
45 pub struct BufReader<R, const S: usize> {
46 inner: R,
47 buf: [u8; S],
48 pos: usize,
49 cap: usize,
50 }
51
52 impl<R: Read, const S: usize> BufReader<R, S> {
53 /// Creates a new `BufReader<R, S>` with a default buffer capacity. The default is currently 8 KB,
54 /// but may change in the future.
55 ///
56 /// # Examples
57 ///
58 /// ```no_run
59 /// use core2::io::BufReader;
60 /// use std::fs::File;
61 ///
62 /// fn main() -> core::result::Result<()> {
63 /// let f = File::open("log.txt")?;
64 /// let reader = BufReader::new(f);
65 /// Ok(())
66 /// }
67 /// ```
68 pub fn new(inner: R) -> BufReader<R, S> {
69 BufReader {
70 inner,
71 buf: [0; S],
72 pos: 0,
73 cap: 0,
74 }
75 }
76 }
77
78 impl<R, const S: usize> BufReader<R, S> {
79 /// Gets a reference to the underlying reader.
80 ///
81 /// It is inadvisable to directly read from the underlying reader.
82 ///
83 /// # Examples
84 ///
85 /// ```no_run
86 /// use core2::io::BufReader;
87 /// use std::fs::File;
88 ///
89 /// fn main() -> core::result::Result<()> {
90 /// let f1 = File::open("log.txt")?;
91 /// let reader = BufReader::new(f1);
92 ///
93 /// let f2 = reader.get_ref();
94 /// Ok(())
95 /// }
96 /// ```
97 pub fn get_ref(&self) -> &R {
98 &self.inner
99 }
100
101 /// Gets a mutable reference to the underlying reader.
102 ///
103 /// It is inadvisable to directly read from the underlying reader.
104 ///
105 /// # Examples
106 ///
107 /// ```no_run
108 /// use core2::io::BufReader;
109 /// use std::fs::File;
110 ///
111 /// fn main() -> core::result::Result<()> {
112 /// let f1 = File::open("log.txt")?;
113 /// let mut reader = BufReader::new(f1);
114 ///
115 /// let f2 = reader.get_mut();
116 /// Ok(())
117 /// }
118 /// ```
119 pub fn get_mut(&mut self) -> &mut R {
120 &mut self.inner
121 }
122
123 /// Returns a reference to the internally buffered data.
124 ///
125 /// Unlike [`fill_buf`], this will not attempt to fill the buffer if it is empty.
126 ///
127 /// [`fill_buf`]: BufRead::fill_buf
128 ///
129 /// # Examples
130 ///
131 /// ```no_run
132 /// use std::{BufReader, BufRead};
133 /// use std::fs::File;
134 ///
135 /// fn main() -> core::result::Result<()> {
136 /// let f = File::open("log.txt")?;
137 /// let mut reader = BufReader::new(f);
138 /// assert!(reader.buffer().is_empty());
139 ///
140 /// if reader.fill_buf()?.len() > 0 {
141 /// assert!(!reader.buffer().is_empty());
142 /// }
143 /// Ok(())
144 /// }
145 /// ```
146 pub fn buffer(&self) -> &[u8] {
147 &self.buf[self.pos..self.cap]
148 }
149
150 /// Returns the number of bytes the internal buffer can hold at once.
151 ///
152 /// # Examples
153 ///
154 /// ```no_run
155 /// use std::{BufReader, BufRead};
156 /// use std::fs::File;
157 ///
158 /// fn main() -> core::result::Result<()> {
159 /// let f = File::open("log.txt")?;
160 /// let mut reader = BufReader::new(f);
161 ///
162 /// let capacity = reader.capacity();
163 /// let buffer = reader.fill_buf()?;
164 /// assert!(buffer.len() <= capacity);
165 /// Ok(())
166 /// }
167 /// ```
168 pub fn capacity(&self) -> usize {
169 S
170 }
171
172 /// Unwraps this `BufReader<R, S>`, returning the underlying reader.
173 ///
174 /// Note that any leftover data in the internal buffer is lost. Therefore,
175 /// a following read from the underlying reader may lead to data loss.
176 ///
177 /// # Examples
178 ///
179 /// ```no_run
180 /// use core2::io::BufReader;
181 /// use std::fs::File;
182 ///
183 /// fn main() -> core::result::Result<()> {
184 /// let f1 = File::open("log.txt")?;
185 /// let reader = BufReader::new(f1);
186 ///
187 /// let f2 = reader.into_inner();
188 /// Ok(())
189 /// }
190 /// ```
191 pub fn into_inner(self) -> R {
192 self.inner
193 }
194
195 /// Invalidates all data in the internal buffer.
196 #[inline]
197 fn discard_buffer(&mut self) {
198 self.pos = 0;
199 self.cap = 0;
200 }
201 }
202
203 impl<R: Read, const S: usize> Read for BufReader<R, S> {
204 fn read(&mut self, buf: &mut [u8]) -> Result<usize> {
205 // If we don't have any buffered data and we're doing a massive read
206 // (larger than our internal buffer), bypass our internal buffer
207 // entirely.
208 if self.pos == self.cap && buf.len() >= S {
209 self.discard_buffer();
210 return self.inner.read(buf);
211 }
212 let nread = {
213 let mut rem = self.fill_buf()?;
214 rem.read(buf)?
215 };
216 self.consume(nread);
217 Ok(nread)
218 }
219 }
220
221 impl<R: Read, const S: usize> BufRead for BufReader<R, S> {
222 fn fill_buf(&mut self) -> Result<&[u8]> {
223 // If we've reached the end of our internal buffer then we need to fetch
224 // some more data from the underlying reader.
225 // Branch using `>=` instead of the more correct `==`
226 // to tell the compiler that the pos..cap slice is always valid.
227 if self.pos >= self.cap {
228 debug_assert!(self.pos == self.cap);
229 self.cap = self.inner.read(&mut self.buf)?;
230 self.pos = 0;
231 }
232 Ok(&self.buf[self.pos..self.cap])
233 }
234
235 fn consume(&mut self, amt: usize) {
236 self.pos = cmp::min(self.pos + amt, self.cap);
237 }
238 }
239
240 impl<R, const S: usize> fmt::Debug for BufReader<R, S>
241 where
242 R: fmt::Debug,
243 {
244 fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
245 fmt.debug_struct("BufReader")
246 .field("reader", &self.inner)
247 .field("buffer", &format_args!("{}/{}", self.cap - self.pos, S))
248 .finish()
249 }
250 }
251
252 impl<R: Seek, const S: usize> Seek for BufReader<R, S> {
253 /// Seek to an offset, in bytes, in the underlying reader.
254 ///
255 /// The position used for seeking with [`SeekFrom::Current`]`(_)` is the
256 /// position the underlying reader would be at if the `BufReader<R, S>` had no
257 /// internal buffer.
258 ///
259 /// Seeking always discards the internal buffer, even if the seek position
260 /// would otherwise fall within it. This guarantees that calling
261 /// [`BufReader::into_inner()`] immediately after a seek yields the underlying reader
262 /// at the same position.
263 ///
264 /// To seek without discarding the internal buffer, use [`BufReader::seek_relative`].
265 ///
266 /// See [`std::Seek`] for more details.
267 ///
268 /// Note: In the edge case where you're seeking with [`SeekFrom::Current`]`(n)`
269 /// where `n` minus the internal buffer length overflows an `i64`, two
270 /// seeks will be performed instead of one. If the second seek returns
271 /// [`Err`], the underlying reader will be left at the same position it would
272 /// have if you called `seek` with [`SeekFrom::Current`]`(0)`.
273 ///
274 /// [`std::Seek`]: Seek
275 fn seek(&mut self, pos: SeekFrom) -> Result<u64> {
276 let result: u64;
277 if let SeekFrom::Current(n) = pos {
278 let remainder = (self.cap - self.pos) as i64;
279 // it should be safe to assume that remainder fits within an i64 as the alternative
280 // means we managed to allocate 8 exbibytes and that's absurd.
281 // But it's not out of the realm of possibility for some weird underlying reader to
282 // support seeking by i64::MIN so we need to handle underflow when subtracting
283 // remainder.
284 if let Some(offset) = n.checked_sub(remainder) {
285 result = self.inner.seek(SeekFrom::Current(offset))?;
286 } else {
287 // seek backwards by our remainder, and then by the offset
288 self.inner.seek(SeekFrom::Current(-remainder))?;
289 self.discard_buffer();
290 result = self.inner.seek(SeekFrom::Current(n))?;
291 }
292 } else {
293 // Seeking with Start/End doesn't care about our buffer length.
294 result = self.inner.seek(pos)?;
295 }
296 self.discard_buffer();
297 Ok(result)
298 }
299 }
300
301 /// Wraps a writer and buffers its output.
302 ///
303 /// It can be excessively inefficient to work directly with something that
304 /// implements [`Write`]. For example, every call to
305 /// [`write`][`TcpStream::write`] on [`TcpStream`] results in a system call. A
306 /// `BufWriter<W>` keeps an in-memory buffer of data and writes it to an underlying
307 /// writer in large, infrequent batches.
308 ///
309 /// `BufWriter<W>` can improve the speed of programs that make *small* and
310 /// *repeated* write calls to the same file or network socket. It does not
311 /// help when writing very large amounts at once, or writing just one or a few
312 /// times. It also provides no advantage when writing to a destination that is
313 /// in memory, like a [`Vec`]<u8>`.
314 ///
315 /// It is critical to call [`flush`] before `BufWriter<W>` is dropped. Though
316 /// dropping will attempt to flush the contents of the buffer, any errors
317 /// that happen in the process of dropping will be ignored. Calling [`flush`]
318 /// ensures that the buffer is empty and thus dropping will not even attempt
319 /// file operations.
320 ///
321 /// # Examples
322 ///
323 /// Let's write the numbers one through ten to a [`TcpStream`]:
324 ///
325 /// ```no_run
326 /// use std::prelude::*;
327 /// use std::net::TcpStream;
328 ///
329 /// let mut stream = TcpStream::connect("127.0.0.1:34254").unwrap();
330 ///
331 /// for i in 0..10 {
332 /// stream.write(&[i+1]).unwrap();
333 /// }
334 /// ```
335 ///
336 /// Because we're not buffering, we write each one in turn, incurring the
337 /// overhead of a system call per byte written. We can fix this with a
338 /// `BufWriter<W>`:
339 ///
340 /// ```no_run
341 /// use std::prelude::*;
342 /// use core2::io::BufWriter;
343 /// use std::net::TcpStream;
344 ///
345 /// let mut stream = BufWriter::new(TcpStream::connect("127.0.0.1:34254").unwrap());
346 ///
347 /// for i in 0..10 {
348 /// stream.write(&[i+1]).unwrap();
349 /// }
350 /// stream.flush().unwrap();
351 /// ```
352 ///
353 /// By wrapping the stream with a `BufWriter<W>`, these ten writes are all grouped
354 /// together by the buffer and will all be written out in one system call when
355 /// the `stream` is flushed.
356 ///
357 /// [`TcpStream::write`]: Write::write
358 /// [`TcpStream`]: crate::net::TcpStream
359 /// [`flush`]: Write::flush
360 pub struct BufWriter<W: Write, const S: usize> {
361 inner: Option<W>,
362 buf: [u8; S],
363 len: usize,
364 // #30888: If the inner writer panics in a call to write, we don't want to
365 // write the buffered data a second time in BufWriter's destructor. This
366 // flag tells the Drop impl if it should skip the flush.
367 panicked: bool,
368 }
369
370 /// An error returned by [`BufWriter::into_inner`] which combines an error that
371 /// happened while writing out the buffer, and the buffered writer object
372 /// which may be used to recover from the condition.
373 ///
374 /// # Examples
375 ///
376 /// ```no_run
377 /// use core2::io::BufWriter;
378 /// use std::net::TcpStream;
379 ///
380 /// let mut stream = BufWriter::new(TcpStream::connect("127.0.0.1:34254").unwrap());
381 ///
382 /// // do stuff with the stream
383 ///
384 /// // we want to get our `TcpStream` back, so let's try:
385 ///
386 /// let stream = match stream.into_inner() {
387 /// Ok(s) => s,
388 /// Err(e) => {
389 /// // Here, e is an IntoInnerError
390 /// panic!("An error occurred");
391 /// }
392 /// };
393 /// ```
394 #[derive(Debug)]
395 pub struct IntoInnerError<W>(W, Error);
396
397 impl<W, const S: usize> BufWriter<W, S>
398 where
399 W: Write,
400 {
401 /// Creates a new `BufWriter<W>` with a default buffer capacity. The default is currently 8 KB,
402 /// but may change in the future.
403 ///
404 /// # Examples
405 ///
406 /// ```no_run
407 /// use core2::io::BufWriter;
408 /// use std::net::TcpStream;
409 ///
410 /// let mut buffer = BufWriter::new(TcpStream::connect("127.0.0.1:34254").unwrap());
411 /// ```
412 pub fn new(inner: W) -> BufWriter<W, S> {
413 BufWriter {
414 inner: Some(inner),
415 buf: [0; S],
416 len: 0,
417 panicked: false,
418 }
419 }
420
421 /// Send data in our local buffer into the inner writer, looping as
422 /// necessary until either it's all been sent or an error occurs.
423 ///
424 /// Because all the data in the buffer has been reported to our owner as
425 /// "successfully written" (by returning nonzero success values from
426 /// `write`), any 0-length writes from `inner` must be reported as i/o
427 /// errors from this method.
428 fn flush_buf(&mut self) -> Result<()> {
429 /// Helper struct to ensure the buffer is updated after all the writes
430 /// are complete. It tracks the number of written bytes and drains them
431 /// all from the front of the buffer when dropped.
432 struct BufGuard<'a, const S: usize> {
433 buffer: &'a mut [u8; S],
434 written: usize,
435 }
436
437 impl<'a, const S: usize> BufGuard<'a, S> {
438 fn new(buffer: &'a mut [u8; S]) -> Self {
439 Self { buffer, written: 0 }
440 }
441
442 /// The unwritten part of the buffer
443 fn remaining(&self) -> &[u8] {
444 &self.buffer[self.written..]
445 }
446
447 /// Flag some bytes as removed from the front of the buffer
448 fn consume(&mut self, amt: usize) {
449 self.written += amt;
450 }
451
452 /// true if all of the bytes have been written
453 fn done(&self) -> bool {
454 self.written >= self.buffer.len()
455 }
456 }
457
458 impl<const S: usize> Drop for BufGuard<'_, S> {
459 fn drop(&mut self) {
460 if self.written > 0 {
461 let mut new_buf = [0; S];
462 new_buf.copy_from_slice(&self.buffer[self.written..]);
463 *self.buffer = new_buf;
464 }
465 }
466 }
467
468 let mut guard = BufGuard::new(&mut self.buf);
469 let inner = self.inner.as_mut().unwrap();
470 while !guard.done() {
471 self.panicked = true;
472 let r = inner.write(guard.remaining());
473 self.panicked = false;
474
475 match r {
476 Ok(0) => {
477 return Err(Error::new(
478 ErrorKind::WriteZero,
479 "failed to write the buffered data",
480 ));
481 }
482 Ok(n) => guard.consume(n),
483 Err(ref e) if e.kind() == ErrorKind::Interrupted => {}
484 Err(e) => return Err(e),
485 }
486 }
487 Ok(())
488 }
489
490 /// Buffer some data without flushing it, regardless of the size of the
491 /// data. Writes as much as possible without exceeding capacity. Returns
492 /// the number of bytes written.
493 fn write_to_buf(&mut self, buf: &[u8]) -> usize {
494 let available = S - self.len;
495 let amt_to_buffer = available.min(buf.len());
496 (&mut self.buf[available..]).copy_from_slice(&buf[..amt_to_buffer]);
497 self.len += amt_to_buffer;
498 amt_to_buffer
499 }
500
501 /// Gets a reference to the underlying writer.
502 ///
503 /// # Examples
504 ///
505 /// ```no_run
506 /// use core2::io::BufWriter;
507 /// use std::net::TcpStream;
508 ///
509 /// let mut buffer = BufWriter::new(TcpStream::connect("127.0.0.1:34254").unwrap());
510 ///
511 /// // we can use reference just like buffer
512 /// let reference = buffer.get_ref();
513 /// ```
514 pub fn get_ref(&self) -> &W {
515 self.inner.as_ref().unwrap()
516 }
517
518 /// Gets a mutable reference to the underlying writer.
519 ///
520 /// It is inadvisable to directly write to the underlying writer.
521 ///
522 /// # Examples
523 ///
524 /// ```no_run
525 /// use core2::io::BufWriter;
526 /// use std::net::TcpStream;
527 ///
528 /// let mut buffer = BufWriter::new(TcpStream::connect("127.0.0.1:34254").unwrap());
529 ///
530 /// // we can use reference just like buffer
531 /// let reference = buffer.get_mut();
532 /// ```
533 pub fn get_mut(&mut self) -> &mut W {
534 self.inner.as_mut().unwrap()
535 }
536
537 /// Returns a reference to the internally buffered data.
538 ///
539 /// # Examples
540 ///
541 /// ```no_run
542 /// use core2::io::BufWriter;
543 /// use std::net::TcpStream;
544 ///
545 /// let buf_writer = BufWriter::new(TcpStream::connect("127.0.0.1:34254").unwrap());
546 ///
547 /// // See how many bytes are currently buffered
548 /// let bytes_buffered = buf_writer.buffer().len();
549 /// ```
550 pub fn buffer(&self) -> &[u8] {
551 &self.buf
552 }
553
554 /// Returns the number of bytes the internal buffer can hold without flushing.
555 ///
556 /// # Examples
557 ///
558 /// ```no_run
559 /// use core2::io::BufWriter;
560 /// use std::net::TcpStream;
561 ///
562 /// let buf_writer = BufWriter::new(TcpStream::connect("127.0.0.1:34254").unwrap());
563 ///
564 /// // Check the capacity of the inner buffer
565 /// let capacity = buf_writer.capacity();
566 /// // Calculate how many bytes can be written without flushing
567 /// let without_flush = capacity - buf_writer.buffer().len();
568 /// ```
569 pub fn capacity(&self) -> usize {
570 S
571 }
572
573 /// Unwraps this `BufWriter<W>`, returning the underlying writer.
574 ///
575 /// The buffer is written out before returning the writer.
576 ///
577 /// # Errors
578 ///
579 /// An [`Err`] will be returned if an error occurs while flushing the buffer.
580 ///
581 /// # Examples
582 ///
583 /// ```no_run
584 /// use core2::io::BufWriter;
585 /// use std::net::TcpStream;
586 ///
587 /// let mut buffer = BufWriter::new(TcpStream::connect("127.0.0.1:34254").unwrap());
588 ///
589 /// // unwrap the TcpStream and flush the buffer
590 /// let stream = buffer.into_inner().unwrap();
591 /// ```
592 pub fn into_inner(mut self) -> core::result::Result<W, IntoInnerError<BufWriter<W, S>>> {
593 match self.flush_buf() {
594 Err(e) => Err(IntoInnerError(self, e)),
595 Ok(()) => Ok(self.inner.take().unwrap()),
596 }
597 }
598 }
599
600 impl<W: Write, const S: usize> Write for BufWriter<W, S> {
601 fn write(&mut self, buf: &[u8]) -> Result<usize> {
602 if self.len + buf.len() > S {
603 self.flush_buf()?;
604 }
605 // FIXME: Why no len > capacity? Why not buffer len == capacity? #72919
606 if buf.len() >= S {
607 self.panicked = true;
608 let r = self.get_mut().write(buf);
609 self.panicked = false;
610 r
611 } else {
612 self.buf.copy_from_slice(buf);
613 Ok(buf.len())
614 }
615 }
616
617 fn write_all(&mut self, buf: &[u8]) -> Result<()> {
618 // Normally, `write_all` just calls `write` in a loop. We can do better
619 // by calling `self.get_mut().write_all()` directly, which avoids
620 // round trips through the buffer in the event of a series of partial
621 // writes in some circumstances.
622 if self.len + buf.len() > S {
623 self.flush_buf()?;
624 }
625 // FIXME: Why no len > capacity? Why not buffer len == capacity? #72919
626 if buf.len() >= S {
627 self.panicked = true;
628 let r = self.get_mut().write_all(buf);
629 self.panicked = false;
630 r
631 } else {
632 self.buf.copy_from_slice(buf);
633 Ok(())
634 }
635 }
636
637 fn flush(&mut self) -> Result<()> {
638 self.flush_buf().and_then(|()| self.get_mut().flush())
639 }
640 }
641
642 impl<W: Write, const S: usize> fmt::Debug for BufWriter<W, S>
643 where
644 W: fmt::Debug,
645 {
646 fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
647 fmt.debug_struct("BufWriter")
648 .field("writer", &self.inner.as_ref().unwrap())
649 .field("buffer", &format_args!("{}/{}", self.buf.len(), S))
650 .finish()
651 }
652 }
653
654 impl<W: Write + Seek, const S: usize> Seek for BufWriter<W, S> {
655 /// Seek to the offset, in bytes, in the underlying writer.
656 ///
657 /// Seeking always writes out the internal buffer before seeking.
658 fn seek(&mut self, pos: SeekFrom) -> Result<u64> {
659 self.flush_buf()?;
660 self.get_mut().seek(pos)
661 }
662 }
663
664 impl<W: Write, const S: usize> Drop for BufWriter<W, S> {
665 fn drop(&mut self) {
666 if self.inner.is_some() && !self.panicked {
667 // dtors should not panic, so we ignore a failed flush
668 let _r = self.flush_buf();
669 }
670 }
671 }
672
673 impl<W> IntoInnerError<W> {
674 /// Returns the error which caused the call to [`BufWriter::into_inner()`]
675 /// to fail.
676 ///
677 /// This error was returned when attempting to write the internal buffer.
678 ///
679 /// # Examples
680 ///
681 /// ```no_run
682 /// use core2::io::BufWriter;
683 /// use std::net::TcpStream;
684 ///
685 /// let mut stream = BufWriter::new(TcpStream::connect("127.0.0.1:34254").unwrap());
686 ///
687 /// // do stuff with the stream
688 ///
689 /// // we want to get our `TcpStream` back, so let's try:
690 ///
691 /// let stream = match stream.into_inner() {
692 /// Ok(s) => s,
693 /// Err(e) => {
694 /// // Here, e is an IntoInnerError, let's log the inner error.
695 /// //
696 /// // We'll just 'log' to stdout for this example.
697 /// println!("{}", e.error());
698 ///
699 /// panic!("An unexpected error occurred.");
700 /// }
701 /// };
702 /// ```
703 pub fn error(&self) -> &Error {
704 &self.1
705 }
706
707 /// Returns the buffered writer instance which generated the error.
708 ///
709 /// The returned object can be used for error recovery, such as
710 /// re-inspecting the buffer.
711 ///
712 /// # Examples
713 ///
714 /// ```no_run
715 /// use core2::io::BufWriter;
716 /// use std::net::TcpStream;
717 ///
718 /// let mut stream = BufWriter::new(TcpStream::connect("127.0.0.1:34254").unwrap());
719 ///
720 /// // do stuff with the stream
721 ///
722 /// // we want to get our `TcpStream` back, so let's try:
723 ///
724 /// let stream = match stream.into_inner() {
725 /// Ok(s) => s,
726 /// Err(e) => {
727 /// // Here, e is an IntoInnerError, let's re-examine the buffer:
728 /// let buffer = e.into_inner();
729 ///
730 /// // do stuff to try to recover
731 ///
732 /// // afterwards, let's just return the stream
733 /// buffer.into_inner().unwrap()
734 /// }
735 /// };
736 /// ```
737 pub fn into_inner(self) -> W {
738 self.0
739 }
740 }
741
742 impl<W> From<IntoInnerError<W>> for Error {
743 fn from(iie: IntoInnerError<W>) -> Error {
744 iie.1
745 }
746 }
747
748 impl<W> fmt::Display for IntoInnerError<W> {
749 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
750 self.error().fmt(f)
751 }
752 }
753
754 /// Private helper struct for implementing the line-buffered writing logic.
755 /// This shim temporarily wraps a BufWriter, and uses its internals to
756 /// implement a line-buffered writer (specifically by using the internal
757 /// methods like write_to_buf and flush_buf). In this way, a more
758 /// efficient abstraction can be created than one that only had access to
759 /// `write` and `flush`, without needlessly duplicating a lot of the
760 /// implementation details of BufWriter. This also allows existing
761 /// `BufWriters` to be temporarily given line-buffering logic; this is what
762 /// enables Stdout to be alternately in line-buffered or block-buffered mode.
763 #[derive(Debug)]
764 pub(super) struct LineWriterShim<'a, W: Write, const S: usize> {
765 buffer: &'a mut BufWriter<W, S>,
766 }
767
768 impl<'a, W: Write, const S: usize> LineWriterShim<'a, W, S> {
769 pub fn new(buffer: &'a mut BufWriter<W, S>) -> Self {
770 Self { buffer }
771 }
772
773 /// Get a mutable reference to the inner writer (that is, the writer
774 /// wrapped by the BufWriter). Be careful with this writer, as writes to
775 /// it will bypass the buffer.
776 fn inner_mut(&mut self) -> &mut W {
777 self.buffer.get_mut()
778 }
779
780 /// Get the content currently buffered in self.buffer
781 fn buffered(&self) -> &[u8] {
782 self.buffer.buffer()
783 }
784
785 /// Flush the buffer iff the last byte is a newline (indicating that an
786 /// earlier write only succeeded partially, and we want to retry flushing
787 /// the buffered line before continuing with a subsequent write)
788 fn flush_if_completed_line(&mut self) -> Result<()> {
789 match self.buffered().last().copied() {
790 Some(b'\n') => self.buffer.flush_buf(),
791 _ => Ok(()),
792 }
793 }
794 }
795
796 impl<'a, W: Write, const S: usize> Write for LineWriterShim<'a, W, S> {
797 /// Write some data into this BufReader with line buffering. This means
798 /// that, if any newlines are present in the data, the data up to the last
799 /// newline is sent directly to the underlying writer, and data after it
800 /// is buffered. Returns the number of bytes written.
801 ///
802 /// This function operates on a "best effort basis"; in keeping with the
803 /// convention of `Write::write`, it makes at most one attempt to write
804 /// new data to the underlying writer. If that write only reports a partial
805 /// success, the remaining data will be buffered.
806 ///
807 /// Because this function attempts to send completed lines to the underlying
808 /// writer, it will also flush the existing buffer if it ends with a
809 /// newline, even if the incoming data does not contain any newlines.
810 fn write(&mut self, buf: &[u8]) -> Result<usize> {
811 let newline_idx = match memchr::memrchr(b'\n', buf) {
812 // If there are no new newlines (that is, if this write is less than
813 // one line), just do a regular buffered write (which may flush if
814 // we exceed the inner buffer's size)
815 None => {
816 self.flush_if_completed_line()?;
817 return self.buffer.write(buf);
818 }
819 // Otherwise, arrange for the lines to be written directly to the
820 // inner writer.
821 Some(newline_idx) => newline_idx + 1,
822 };
823
824 // Flush existing content to prepare for our write. We have to do this
825 // before attempting to write `buf` in order to maintain consistency;
826 // if we add `buf` to the buffer then try to flush it all at once,
827 // we're obligated to return Ok(), which would mean suppressing any
828 // errors that occur during flush.
829 self.buffer.flush_buf()?;
830
831 // This is what we're going to try to write directly to the inner
832 // writer. The rest will be buffered, if nothing goes wrong.
833 let lines = &buf[..newline_idx];
834
835 // Write `lines` directly to the inner writer. In keeping with the
836 // `write` convention, make at most one attempt to add new (unbuffered)
837 // data. Because this write doesn't touch the BufWriter state directly,
838 // and the buffer is known to be empty, we don't need to worry about
839 // self.buffer.panicked here.
840 let flushed = self.inner_mut().write(lines)?;
841
842 // If buffer returns Ok(0), propagate that to the caller without
843 // doing additional buffering; otherwise we're just guaranteeing
844 // an "ErrorKind::WriteZero" later.
845 if flushed == 0 {
846 return Ok(0);
847 }
848
849 // Now that the write has succeeded, buffer the rest (or as much of
850 // the rest as possible). If there were any unwritten newlines, we
851 // only buffer out to the last unwritten newline that fits in the
852 // buffer; this helps prevent flushing partial lines on subsequent
853 // calls to LineWriterShim::write.
854
855 // Handle the cases in order of most-common to least-common, under
856 // the presumption that most writes succeed in totality, and that most
857 // writes are smaller than the buffer.
858 // - Is this a partial line (ie, no newlines left in the unwritten tail)
859 // - If not, does the data out to the last unwritten newline fit in
860 // the buffer?
861 // - If not, scan for the last newline that *does* fit in the buffer
862 let tail = if flushed >= newline_idx {
863 &buf[flushed..]
864 } else if newline_idx - flushed <= self.buffer.capacity() {
865 &buf[flushed..newline_idx]
866 } else {
867 let scan_area = &buf[flushed..];
868 let scan_area = &scan_area[..self.buffer.capacity()];
869 match memchr::memrchr(b'\n', scan_area) {
870 Some(newline_idx) => &scan_area[..newline_idx + 1],
871 None => scan_area,
872 }
873 };
874
875 let buffered = self.buffer.write_to_buf(tail);
876 Ok(flushed + buffered)
877 }
878
879 fn flush(&mut self) -> Result<()> {
880 self.buffer.flush()
881 }
882
883 /// Write some data into this BufReader with line buffering. This means
884 /// that, if any newlines are present in the data, the data up to the last
885 /// newline is sent directly to the underlying writer, and data after it
886 /// is buffered.
887 ///
888 /// Because this function attempts to send completed lines to the underlying
889 /// writer, it will also flush the existing buffer if it contains any
890 /// newlines, even if the incoming data does not contain any newlines.
891 fn write_all(&mut self, buf: &[u8]) -> Result<()> {
892 match memchr::memrchr(b'\n', buf) {
893 // If there are no new newlines (that is, if this write is less than
894 // one line), just do a regular buffered write (which may flush if
895 // we exceed the inner buffer's size)
896 None => {
897 self.flush_if_completed_line()?;
898 self.buffer.write_all(buf)
899 }
900 Some(newline_idx) => {
901 let (lines, tail) = buf.split_at(newline_idx + 1);
902
903 if self.buffered().is_empty() {
904 self.inner_mut().write_all(lines)?;
905 } else {
906 // If there is any buffered data, we add the incoming lines
907 // to that buffer before flushing, which saves us at least
908 // one write call. We can't really do this with `write`,
909 // since we can't do this *and* not suppress errors *and*
910 // report a consistent state to the caller in a return
911 // value, but here in write_all it's fine.
912 self.buffer.write_all(lines)?;
913 self.buffer.flush_buf()?;
914 }
915
916 self.buffer.write_all(tail)
917 }
918 }
919 }
920 }
921
922 /// Wraps a writer and buffers output to it, flushing whenever a newline
923 /// (`0x0a`, `'\n'`) is detected.
924 ///
925 /// The [`BufWriter`] struct wraps a writer and buffers its output.
926 /// But it only does this batched write when it goes out of scope, or when the
927 /// internal buffer is full. Sometimes, you'd prefer to write each line as it's
928 /// completed, rather than the entire buffer at once. Enter `LineWriter`. It
929 /// does exactly that.
930 ///
931 /// Like [`BufWriter`], a `LineWriter`’s buffer will also be flushed when the
932 /// `LineWriter` goes out of scope or when its internal buffer is full.
933 ///
934 /// If there's still a partial line in the buffer when the `LineWriter` is
935 /// dropped, it will flush those contents.
936 ///
937 /// # Examples
938 ///
939 /// We can use `LineWriter` to write one line at a time, significantly
940 /// reducing the number of actual writes to the file.
941 ///
942 /// ```no_run
943 /// use std::fs::{self, File};
944 /// use std::prelude::*;
945 /// use core2::io::LineWriter;
946 ///
947 /// fn main() -> core::result::Result<()> {
948 /// let road_not_taken = b"I shall be telling this with a sigh
949 /// Somewhere ages and ages hence:
950 /// Two roads diverged in a wood, and I -
951 /// I took the one less traveled by,
952 /// And that has made all the difference.";
953 ///
954 /// let file = File::create("poem.txt")?;
955 /// let mut file = LineWriter::new(file);
956 ///
957 /// file.write_all(b"I shall be telling this with a sigh")?;
958 ///
959 /// // No bytes are written until a newline is encountered (or
960 /// // the internal buffer is filled).
961 /// assert_eq!(fs::read_to_string("poem.txt")?, "");
962 /// file.write_all(b"\n")?;
963 /// assert_eq!(
964 /// fs::read_to_string("poem.txt")?,
965 /// "I shall be telling this with a sigh\n",
966 /// );
967 ///
968 /// // Write the rest of the poem.
969 /// file.write_all(b"Somewhere ages and ages hence:
970 /// Two roads diverged in a wood, and I -
971 /// I took the one less traveled by,
972 /// And that has made all the difference.")?;
973 ///
974 /// // The last line of the poem doesn't end in a newline, so
975 /// // we have to flush or drop the `LineWriter` to finish
976 /// // writing.
977 /// file.flush()?;
978 ///
979 /// // Confirm the whole poem was written.
980 /// assert_eq!(fs::read("poem.txt")?, &road_not_taken[..]);
981 /// Ok(())
982 /// }
983 /// ```
984 pub struct LineWriter<W: Write, const S: usize> {
985 inner: BufWriter<W, S>,
986 }
987
988 impl<W: Write, const S: usize> LineWriter<W, S> {
989 /// Creates a new `LineWriter`.
990 ///
991 /// # Examples
992 ///
993 /// ```no_run
994 /// use std::fs::File;
995 /// use core2::io::LineWriter;
996 ///
997 /// fn main() -> core::result::Result<()> {
998 /// let file = File::create("poem.txt")?;
999 /// let file = LineWriter::new(file);
1000 /// Ok(())
1001 /// }
1002 /// ```
1003 pub fn new(inner: W) -> LineWriter<W, S> {
1004 LineWriter {
1005 inner: BufWriter::new(inner),
1006 }
1007 }
1008
1009 /// Gets a reference to the underlying writer.
1010 ///
1011 /// # Examples
1012 ///
1013 /// ```no_run
1014 /// use std::fs::File;
1015 /// use core2::io::LineWriter;
1016 ///
1017 /// fn main() -> core::result::Result<()> {
1018 /// let file = File::create("poem.txt")?;
1019 /// let file = LineWriter::new(file);
1020 ///
1021 /// let reference = file.get_ref();
1022 /// Ok(())
1023 /// }
1024 /// ```
1025 pub fn get_ref(&self) -> &W {
1026 self.inner.get_ref()
1027 }
1028
1029 /// Gets a mutable reference to the underlying writer.
1030 ///
1031 /// Caution must be taken when calling methods on the mutable reference
1032 /// returned as extra writes could corrupt the output stream.
1033 ///
1034 /// # Examples
1035 ///
1036 /// ```no_run
1037 /// use std::fs::File;
1038 /// use core2::io::LineWriter;
1039 ///
1040 /// fn main() -> core::result::Result<()> {
1041 /// let file = File::create("poem.txt")?;
1042 /// let mut file = LineWriter::new(file);
1043 ///
1044 /// // we can use reference just like file
1045 /// let reference = file.get_mut();
1046 /// Ok(())
1047 /// }
1048 /// ```
1049 pub fn get_mut(&mut self) -> &mut W {
1050 self.inner.get_mut()
1051 }
1052
1053 /// Unwraps this `LineWriter`, returning the underlying writer.
1054 ///
1055 /// The internal buffer is written out before returning the writer.
1056 ///
1057 /// # Errors
1058 ///
1059 /// An [`Err`] will be returned if an error occurs while flushing the buffer.
1060 ///
1061 /// # Examples
1062 ///
1063 /// ```no_run
1064 /// use std::fs::File;
1065 /// use core2::io::LineWriter;
1066 ///
1067 /// fn main() -> core::result::Result<()> {
1068 /// let file = File::create("poem.txt")?;
1069 ///
1070 /// let writer: LineWriter<File> = LineWriter::new(file);
1071 ///
1072 /// let file: File = writer.into_inner()?;
1073 /// Ok(())
1074 /// }
1075 /// ```
1076 pub fn into_inner(self) -> core::result::Result<W, IntoInnerError<LineWriter<W, S>>> {
1077 self.inner
1078 .into_inner()
1079 .map_err(|IntoInnerError(buf, e)| IntoInnerError(LineWriter { inner: buf }, e))
1080 }
1081 }
1082
1083 impl<W: Write, const S: usize> Write for LineWriter<W, S> {
1084 fn write(&mut self, buf: &[u8]) -> Result<usize> {
1085 LineWriterShim::new(&mut self.inner).write(buf)
1086 }
1087
1088 fn flush(&mut self) -> Result<()> {
1089 self.inner.flush()
1090 }
1091
1092 fn write_all(&mut self, buf: &[u8]) -> Result<()> {
1093 LineWriterShim::new(&mut self.inner).write_all(buf)
1094 }
1095
1096 fn write_fmt(&mut self, fmt: fmt::Arguments<'_>) -> Result<()> {
1097 LineWriterShim::new(&mut self.inner).write_fmt(fmt)
1098 }
1099 }
1100
1101 impl<W: Write, const S: usize> fmt::Debug for LineWriter<W, S>
1102 where
1103 W: fmt::Debug,
1104 {
1105 fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
1106 fmt.debug_struct("LineWriter")
1107 .field("writer", &self.inner.inner)
1108 .field("buffer", &format_args!("{}/{}", self.inner.len, S))
1109 .finish()
1110 }
1111 }