Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Clarify docs for Read::read's return value #82892

Merged
merged 1 commit into from
Mar 19, 2021

Conversation

jix
Copy link
Contributor

@jix jix commented Mar 8, 2021

Right now the docs for Read::read's return value are phrased in a way that makes it easy for the reader to assume that the return value is never larger than the passed buffer. This PR clarifies that this is a requirement for implementations of the trait, but that callers have to expect a buggy yet safe implementation failing to do so, especially if unchecked accesses to the buffer are done afterwards.

I fell into this trap recently, and when I noticed, I looked at the docs again and had the feeling that I might not have been the first one to miss this.

The same issue of trusting the return value of read was also present in std itself for about 2.5 years and only fixed recently, see #80895.

I hope that clarifying the docs might help others to avoid this issue.

@rust-highfive
Copy link
Collaborator

r? @KodrAus

(rust-highfive has picked a reviewer for you, use r? to override)

@rust-highfive rust-highfive added the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Mar 8, 2021
@joshtriplett
Copy link
Member

@bors r+ rollup

@bors
Copy link
Contributor

bors commented Mar 18, 2021

📌 Commit 9dfda62 has been approved by joshtriplett

@bors bors added S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Mar 18, 2021
Dylan-DPC-zz pushed a commit to Dylan-DPC-zz/rust that referenced this pull request Mar 18, 2021
Clarify docs for Read::read's return value

Right now the docs for `Read::read`'s return value are phrased in a way that makes it easy for the reader to assume that the return value is never larger than the passed buffer. This PR clarifies that this is a requirement for implementations of the trait, but that callers have to expect a buggy yet safe implementation failing to do so, especially if unchecked accesses to the buffer are done afterwards.

I fell into this trap recently, and when I noticed, I looked at the docs again and had the feeling that I might not have been the first one to miss this.

The same issue of trusting the return value of `read` was also present in std itself for about 2.5 years and only fixed recently, see rust-lang#80895.

I hope that clarifying the docs might help others to avoid this issue.
Dylan-DPC-zz pushed a commit to Dylan-DPC-zz/rust that referenced this pull request Mar 19, 2021
Clarify docs for Read::read's return value

Right now the docs for `Read::read`'s return value are phrased in a way that makes it easy for the reader to assume that the return value is never larger than the passed buffer. This PR clarifies that this is a requirement for implementations of the trait, but that callers have to expect a buggy yet safe implementation failing to do so, especially if unchecked accesses to the buffer are done afterwards.

I fell into this trap recently, and when I noticed, I looked at the docs again and had the feeling that I might not have been the first one to miss this.

The same issue of trusting the return value of `read` was also present in std itself for about 2.5 years and only fixed recently, see rust-lang#80895.

I hope that clarifying the docs might help others to avoid this issue.
Dylan-DPC-zz pushed a commit to Dylan-DPC-zz/rust that referenced this pull request Mar 19, 2021
Clarify docs for Read::read's return value

Right now the docs for `Read::read`'s return value are phrased in a way that makes it easy for the reader to assume that the return value is never larger than the passed buffer. This PR clarifies that this is a requirement for implementations of the trait, but that callers have to expect a buggy yet safe implementation failing to do so, especially if unchecked accesses to the buffer are done afterwards.

I fell into this trap recently, and when I noticed, I looked at the docs again and had the feeling that I might not have been the first one to miss this.

The same issue of trusting the return value of `read` was also present in std itself for about 2.5 years and only fixed recently, see rust-lang#80895.

I hope that clarifying the docs might help others to avoid this issue.
JohnTitor added a commit to JohnTitor/rust that referenced this pull request Mar 19, 2021
Clarify docs for Read::read's return value

Right now the docs for `Read::read`'s return value are phrased in a way that makes it easy for the reader to assume that the return value is never larger than the passed buffer. This PR clarifies that this is a requirement for implementations of the trait, but that callers have to expect a buggy yet safe implementation failing to do so, especially if unchecked accesses to the buffer are done afterwards.

I fell into this trap recently, and when I noticed, I looked at the docs again and had the feeling that I might not have been the first one to miss this.

The same issue of trusting the return value of `read` was also present in std itself for about 2.5 years and only fixed recently, see rust-lang#80895.

I hope that clarifying the docs might help others to avoid this issue.
Dylan-DPC-zz pushed a commit to Dylan-DPC-zz/rust that referenced this pull request Mar 19, 2021
Clarify docs for Read::read's return value

Right now the docs for `Read::read`'s return value are phrased in a way that makes it easy for the reader to assume that the return value is never larger than the passed buffer. This PR clarifies that this is a requirement for implementations of the trait, but that callers have to expect a buggy yet safe implementation failing to do so, especially if unchecked accesses to the buffer are done afterwards.

I fell into this trap recently, and when I noticed, I looked at the docs again and had the feeling that I might not have been the first one to miss this.

The same issue of trusting the return value of `read` was also present in std itself for about 2.5 years and only fixed recently, see rust-lang#80895.

I hope that clarifying the docs might help others to avoid this issue.
bors added a commit to rust-lang-ci/rust that referenced this pull request Mar 19, 2021
Rollup of 11 pull requests

Successful merges:

 - rust-lang#82500 (Reuse `std::sys::unsupported::pipe` on `hermit`)
 - rust-lang#82759 (Remove unwrap_none/expect_none from compiler/.)
 - rust-lang#82846 (rustdoc: allow list syntax for #[doc(alias)] attributes)
 - rust-lang#82892 (Clarify docs for Read::read's return value)
 - rust-lang#83179 (Extend `proc_macro_back_compat` lint to `actix-web`)
 - rust-lang#83197 (Move some test-only code to test files)
 - rust-lang#83208 (Fix gitattibutes for old git versions)
 - rust-lang#83215 (Deprecate std::os::haiku::raw, which accidentally wasn't deprecated)
 - rust-lang#83230 (Remove unnecessary `forward_inner_docs` hack)
 - rust-lang#83236 (Upgrade memmap to memmap2)
 - rust-lang#83270 (Fix typo/inaccuracy in the documentation of Iterator::skip_while)

Failed merges:

r? `@ghost`
`@rustbot` modify labels: rollup
@bors bors merged commit db4a97c into rust-lang:master Mar 19, 2021
@rustbot rustbot added this to the 1.52.0 milestone Mar 19, 2021
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

6 participants