Change wording on read_vectored docs
Closes#70154
I'm happy to work with others to make the wording on this more clear. I think what I have is an improvement but may not be the final wording.
When working with an arbitrary reader or writer, code that uses vectored
operations may end up being slower than code that copies into a single
buffer when the underlying reader or writer doesn't actually support
vectored operations. These new methods allow you to ask the reader or
witer up front if vectored operations are efficiently supported.
Currently, you have to use some heuristics to guess by e.g. checking if
the read or write only accessed the first buffer. Hyper is one concrete
example of a library that has to do this dynamically:
0eaf304644/src/proto/h1/io.rs (L582-L594)
Remove spotlight
I had a few comments saying that this feature was at best misunderstood or not even used so I decided to organize a poll about on [twitter](https://twitter.com/imperioworld_/status/1232769353503956994). After 87 votes, the result is very clear: it's not useful. Considering the amount of code we have just to run it, I think it's definitely worth it to remove it.
r? @kinnison
cc @ollie27
Some types of Write instances have a semantic meaning associated with
writing an empty buffer, such as sending an empty packet. This works
when calling `write` directly, and supplying an empty buffer. However,
calling `write_all` on an empty buffer will simply never call `write`,
because `write_all` assumes it has no work to do.
Document this behavior, to help prospective users of
datagram-packet-style Write instances.
This commit applies rustfmt with rust-lang/rust's default settings to
files in src/libstd *that are not involved in any currently open PR* to
minimize merge conflicts. THe list of files involved in open PRs was
determined by querying GitHub's GraphQL API with this script:
https://gist.github.com/dtolnay/aa9c34993dc051a4f344d1b10e4487e8
With the list of files from the script in outstanding_files, the
relevant commands were:
$ find src/libstd -name '*.rs' \
| xargs rustfmt --edition=2018 --unstable-features --skip-children
$ rg libstd outstanding_files | xargs git checkout --
Repeating this process several months apart should get us coverage of
most of the rest of libstd.
To confirm no funny business:
$ git checkout $THIS_COMMIT^
$ git show --pretty= --name-only $THIS_COMMIT \
| xargs rustfmt --edition=2018 --unstable-features --skip-children
$ git diff $THIS_COMMIT # there should be no difference
Prevously the `read_to_end` implementation for `std::io::Take` used its
own `limit` as a cap on the `reservation_size`. However, that could
still result in an over-allocation like this:
1. Call `reader.take(5).read_to_end(&mut vec)`.
2. `read_to_end_with_reservation` reserves 5 bytes and calls `read`.
3. `read` writes 5 bytes.
4. `read_to_end_with_reservation` reserves 5 bytes and calls `read`.
5. `read` writes 0 bytes.
6. The read loop ends with `vec` having length 5 and capacity 10.
The reservation of 5 bytes was correct for the read at step 2 but
unnecessary for the read at step 4. By that second read, `Take::limit`
is 0, but the `read_to_end_with_reservation` loop is still using the
same `reservation_size` it started with.
Solve this by having `read_to_end_with_reservation` take a closure,
which lets it get a fresh `reservation_size` for each read. This is an
implementation detail which doesn't affect any public API.
simplify std::io::Write::write rustdoc
The std::io::Write::write method currensly suggests consumers guaranteed
that `0 <= n <= buf.len()`, for `Ok(n)`, however `n` is of type `usize`
causing the compiler to emit a warning:
```
warning: comparison is useless due to type limits
--> lib.rs:6:18
|
6 | Ok(n) => 0 <= n && n <= output.len(),
| ^^^^^^
|
= note: #[warn(unused_comparisons)] on by default
```
This PR removes the suggestion to check `0 <= n` since it is moot.
r? @steveklabnik
The std::io::Write::write method currensly suggests consumers guaranteed
that `0 <= n <= buf.len()`, for `Ok(n)`, however `n` is of type `usize`
causing the compiler to emit a warning:
```
warning: comparison is useless due to type limits
--> lib.rs:6:18
|
6 | Ok(n) => 0 <= n && n <= output.len(),
| ^^^^^^
|
= note: #[warn(unused_comparisons)] on by default
```
This PR removes the suggestion to check `0 <= n` since it is moot.
r? @steveklabnik
This renames `std::io::IoVec` to `std::io::IoSlice` and
`std::io::IoVecMut` to `std::io::IoSliceMut`, and stabilizes
`std::io::IoSlice`, `std::io::IoSliceMut`,
`std::io::Read::read_vectored`, and `std::io::Write::write_vectored`.
Closes#58452
Calling `Read::read` or `Write::write` without checking the returned
`usize` value is almost always an error. Example code in the
documentation should demonstrate how to use the return value correctly.
Otherwise, people might copy the example code thinking that it is okay
to "fire and forget" these methods.
Add provided methods `Seek::{stream_len, stream_position}`
This adds two new, provided methods to the `io::Seek` trait:
- `fn stream_len(&mut self) -> Result<u64>`
- `fn stream_position(&mut self) -> Result<u64>`
Both are added for convenience and to improve readability in user code. Reading `file.stream_len()` is much better than to manually seek two or three times. Similarly, `file.stream_position()` is much more clear than `file.seek(SeekFrom::Current(0))`.
You can find prior discussions [in this internals thread](https://internals.rust-lang.org/t/pre-rfc-idea-extend-io-seek-with-convenience-methods-with-e-g-stream-len/9262). I think I addressed all concerns in that thread.
I already wrote three RFCs to add a small new API to libstd but I noticed that many public changes to libstd happen without an RFC. So I figured I can try opening a PR directly without going through RFCs first. After all, we do have rfcbot here too. If you think this change is too big to merge without an RFC, I can still close this PR and write an RFC.
