Add new test case for possible bug in BufReader
When reading a large chunk from a BufReader, if all the bytes from the buffer have been already consumed, the internal buffer is bypassed entirely. However, it is not invalidated, and it's possible to access its contents using the `seek_relative` method, because it tries to reuse the existing buffer.
There are two moments when a BufRead object needs to empty it's internal
buffer:
- In a seek call;
- In a read call when all data in the internal buffer had been already
consumed and the output buffer has a greater or equal size than the
internal buffer.
In both cases, the buffer was not being properly emptied, but only
marked as consumed (self.pos = self.cap). That should be no problem if
the inner reader is only Read, but if it is Seek as well, then it's
possible to access the data in the buffer by using the seek_relative
method. In order to prevent this from happening, both self.pos and
self.cap should be set to 0.
Two test cases were added to detect that failure:
- test_buffered_reader_invalidated_after_read
- test_buffered_reader_invalidated_after_seek
Both tests are very similar to each other. The inner reader contains the
following data: [5, 6, 7, 0, 1, 2, 3, 4]. The buffer capacity is 3
bytes.
- First, we call fill_buffer, which loads [5, 6, 7] into the internal
buffer, and then consume those 3 bytes.
- Then we either read the 5 remaining bytes in a single read call or we
move to the end of the stream by calling seek. In both cases the
buffer should be emptied to prevent the previous data [5, 6, 7] from
being read.
- We now call seek_relative(-2) and read two bytes, which should give us
the last 2 bytes of the stream: [3, 4].
Before this commit, the the seek_relative method would consider that
we're still in the range of the internal buffer, so instead of fetching
data from the inner reader, it would return the two last bytes that were
incorrectly still in the buffer: [6, 7]. Therefore, the test would fail.
Now, when seek_relative is called the buffer is empty. So the expected
data [3, 4] is fetched from the inner reader and the test passes.
Add vectored read and write support
This functionality has lived for a while in the tokio ecosystem, where
it can improve performance by minimizing copies.
r? @alexcrichton
There are two big categories of changes in here
- Removing lifetimes from common traits that can essentially never user a lifetime from an input (particularly `Drop` & `Debug`)
- Forwarding impls that are only possible because the lifetime doesn't matter (like `impl<R: Read + ?Sized> Read for &mut R`)
I omitted things that seemed like they could be more controversial, like the handful of iterators that have a `Item: 'static` despite the iterator having a lifetime or the `PartialEq` implementations where the flipped one cannot elide the lifetime.
Add some performance guidance to std::fs and std::io docs
Adds more documentation about performance to various "read" functions in `fs` and `io`, and to `BufReader`/`BufWriter`, with the goal of helping developers choose the best option for a given task.
* Since the switch to pulldown-cmark reference links need a blank line
before the URLs.
* Reference link references are not case sensitive.
* Doc comments need to be indented uniformly otherwise rustdoc gets
confused.
Previously the `LineWriter` could successfully write some bytes but then fail to
report that it has done so. Additionally, an erroneous flush after a successful
write was permanently ignored. This commit fixes these two issues by (a)
maintaining a `need_flush` flag to indicate whether a flush should be the first
operation in `LineWriter::write` and (b) avoiding returning an error once some
bytes have been successfully written.
Closes#37807
