Better Debug impl for io::Error.
This PR includes the below changes:
1. The former impl wrapped the entire thing in `Error { repr: ... }` which was unhelpful; this has been removed.
2. The `Os` variant of `io::Error` included the code and message, but not the kind; this has been fixed.
3. The `Custom` variant of `io::Error` included a `Custom(Custom { ... })`, which is now just `Custom { ... }`.
Example of previous impl:
```rust
Error {
repr: Custom(
Custom {
kind: InvalidData,
error: Error {
repr: Os {
code: 2,
message: "no such file or directory"
}
}
}
)
}
```
Example of new impl:
```rust
Custom {
kind: InvalidData,
error: Os {
code: 2,
kind: NotFound,
message: "no such file or directory"
}
}
```
docs: do not call integer overflows as underflows
In the API docs, integer overflow is sometimes called underflow. Underflow is really when the magnitude of a floating-point number is too small so the number underflows to subnormal or zero. With integers it is always overflow, even if the expected result is less than the minimum number that can be represented.
The read_exact implementation for &[u8] is optimized and usually allows LLVM to reduce a read_exact call for small numbers of bytes to a bounds check and a register load instead of a generic memcpy. On a workload I have that decompresses, deserializes (via bincode), and processes some data, this leads to a 40% speedup by essentially eliminating the deserialization overhead entirely.
Optimize `read_to_end`.
This patch makes `read_to_end` use Vec's memory-growth pattern rather
than using a custom pattern.
This has some interesting effects:
- If memory is reserved up front, `read_to_end` can be faster, as it
starts reading at the buffer size, rather than always starting at 32
bytes. This speeds up file reading by 2x in one of my use cases.
- It can reduce the number of syscalls when reading large files.
Previously, `read_to_end` would settle into a sequence of 8192-byte
reads. With this patch, the read size follows Vec's allocation
pattern. For example, on a 16MiB file, it can do 21 read syscalls
instead of 2057. In simple benchmarks of large files though, overall
speed is still dominated by the actual I/O.
- A downside is that Read implementations that don't implement
`initializer()` may see increased memory zeroing overhead.
I benchmarked this on a variety of data sizes, with and without
preallocated buffers. Most benchmarks see no difference, but reading
a small/medium file with a pre-allocated buffer is faster.
show in docs whether the return type of a function impls Iterator/Read/Write
Closes#25928
This PR makes it so that when rustdoc documents a function, it checks the return type to see whether it implements a handful of specific traits. If so, it will print the impl and any associated types. Rather than doing this via a whitelist within rustdoc, i chose to do this by a new `#[doc]` attribute parameter, so things like `Future` could tap into this if desired.
### Known shortcomings
~~The printing of impls currently uses the `where` class over the whole thing to shrink the font size relative to the function definition itself. Naturally, when the impl has a where clause of its own, it gets shrunken even further:~~ (This is no longer a problem because the design changed and rendered this concern moot.)
The lookup currently just looks at the top-level type, not looking inside things like Result or Option, which renders the spotlights on Read/Write a little less useful:
<details><summary>`File::{open, create}` don't have spotlight info (pic of old design)</summary>
</details>
All three of the initially spotlighted traits are generically implemented on `&mut` references. Rustdoc currently treats a `&mut T` reference-to-a-generic as an impl on the reference primitive itself. `&mut Self` counts as a generic in the eyes of rustdoc. All this combines to create this lovely scene on `Iterator::by_ref`:
<details><summary>`Iterator::by_ref` spotlights Iterator, Read, and Write (pic of old design)</summary>
</details>
This patch makes `read_to_end` use Vec's memory-growth pattern rather
than using a custom pattern.
This has some interesting effects:
- If memory is reserved up front, `read_to_end` can be faster, as it
starts reading at the buffer size, rather than always starting at 32
bytes. This speeds up file reading by 2x in one of my use cases.
- It can reduce the number of syscalls when reading large files.
Previously, `read_to_end` would settle into a sequence of 8192-byte
reads. With this patch, the read size follows Vec's allocation
pattern. For example, on a 16MiB file, it can do 21 read syscalls
instead of 2057. In simple benchmarks of large files though, overall
speed is still dominated by the actual I/O.
- A downside is that Read implementations that don't implement
`initializer()` may see increased memory zeroing overhead.
I benchmarked this on a variety of data sizes, with and without
preallocated buffers. Most benchmarks see no difference, but reading
a small/medium file with a pre-allocated buffer is faster.
This commit removes the reexport of `EBADF_ERR` as a constant from
libstd's portability facade, instead opting for a platform-specific
function that specifically queries an `io::Error`. Not all platforms may
have a constant for this, so it makes the intent a little more clear
that a code need not be supplied, just an answer to a query.
Implement is_empty() for BufReader
Simple implementation of `is_empty` method for BufReader so it is possible to tell whether there is any data in its buffer.
I didn't know correct stability annotation to place on the function. Presumably there is no reason to place this feature behind a feature flag, but I wasn't sure how to tag it as an unstable feature without that.
CC: #45323
fix an incorrect assertion in the doc example for `std::io::copy`
I think this wasn't caught by CI because the `foo` wrapper function was only defined and not called. This seems to be the norm for doc examples that define a `foo` function. Is that on purpose?
Add warning to BufWriter documentation
When using `BufWriter`, it is very easy to unintentionally ignore errors, because errors which occur when flushing buffered data when the `BufWriter` is dropped are ignored. This has been noted in a couple places: #32677, #37045.
There has been some discussion about how to fix this problem in #32677, but no solution seems likely to land in the near future. For now, anyone who wishes to have robust error handling must remember to manually call `flush()` on a `BufWriter` before it is dropped. Until a permanent fix is in place, it seems worthwhile to add a warning to that effect to the documentation.
