| Age | Commit message (Collapse) | Author | Lines |
|---|
|
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.
|
|
r=GuillaumeGomez,QuietMisdreavus
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 incorrect error type in Read::byte docs
None
|
|
|
|
|
|
|
|
The default impl for read_to_end does a bunch of bookkeeping
that isn't necessary for slices and is about 4 times slower
on my machine.
|
|
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?
|
|
|
|
|
|
This is just undoing changes from #41991 because we are not running markdown rendering twice.
|
|
|
|
This fixes headings reading "Unsafety" and "Example", they should be
"Safety" and "Examples" according to RFC 1574.
|
|
|
|
|
|
Like #43008 (f668999), but _much more aggressive_.
|
|
|
|
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
This is an API that allows types to indicate that they can be passed
buffers of uninitialized memory which can improve performance.
|
|
Remove sometimes in std::io::Read doc
We use it immediately in the next sentence, and the word is filler.
A different conversation to make is whether we want to call them Readers in the documentation at all. And whether it's actually called "Readers" elsewhere.
|
|
`compiler-plugins.html` is moved into the Unstable Book.
Explanation is slightly modified to match the change.
|
|
We use it immediately in the next sentence, and the word is filler.
|
|
|
|
|
|
* Factor out the nigh-identical bodies of `_print` and `_eprint` to a helper
function `print_to` (I was sorely tempted to call it `_doprnt`).
* Update the issue number for the unstable `eprint` feature.
* Add entries to the "unstable book" for `eprint` and `eprint_internal`.
* Style corrections to the documentation.
|
|
These are exactly the same as `print!` and `println!` except that
they write to stderr instead of stdout. Issue #39228.
|
|
Add internal accessor methods to io::{Chain, Take}.
Resolves #29067.
|
|
|
|
|
|
Resolves #29067.
|
|
Also spell out that read and write operations should be retried on
`ErrorKind::Interrupted` errors.
Fixes #38494.
|
|
* 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.
|
|
Add helpful hint in io docs about how ? is not allowed in main()
This is my effort to help alleviate the confusion caused by the error message:
```rust
error[E0277]: the trait bound `(): std::ops::Carrier` is not satisfied
--> hello_world.rs:72:5
|
72 | io::stdin().read_line(&mut d_input)?;
| ------------------------------------
| |
| the trait `std::ops::Carrier` is not implemented for `()`
| in this macro invocation
|
= note: required by `std::ops::Carrier::from_error`
error: aborting due to previous error
```
This has been discussed at length in https://github.com/rust-lang/rust/issues/35946, but I figured it would be helpful to mention in the docs.
Reading user input is one of the first things beginners will look up in the docs, so my thinking was they'd see this warning here and not have to deal with the [tricky error message](https://blog.rust-lang.org/2017/03/02/lang-ergonomics.html).
If you think this isn't the right place to put this in the docs, that's understandable, I'm open to suggestions for putting it elsewhere or removing it entirely.
|
|
Document Cursor::new position is 0
... even if contained `Vec` is not empty. E. g. for
```
let v = vec![10u8, 20];
let mut c = io::Cursor::new(v);
c.write_all(b"aaaa").unwrap();
println!("{:?}", c.into_inner());
```
result is
```
[97, 97, 97, 97]
```
and not
```
[10, 20, 97, 97, 97, 97]
```
|
|
|
|
|
|
Prior to this commit, most of the `BufRead` examples used `StdinLock` to
demonstrate how certain `BufRead` methods worked. Using `StdinLock` is
not ideal since:
* Relying on run-time data means we can't show concrete examples of how
these methods work up-front. The user is required to run them in order
to see how they behave.
* If the user tries to run an example in the playpen, it won't work
because the playpen doesn't support user input to stdin.
|
