-
Notifications
You must be signed in to change notification settings - Fork 12.9k
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 black_box()
docs when passed a unit-returning function
#133923
Comments
Those mean exactly the same thing. But I agree that the docs should be improved, and I think an example of misuse like from y21 is probably the way to make the point that it's a normal function, not a different kind of syntax that obscures the expression between the parens. |
Confirming: this is a library documentation issue. |
@rustbot claim |
Clarify how to use `black_box()` Closes rust-lang#133923. r? libs ^ (I think that's the right group, this is my first time!) This PR adds further clarification on the [`black_box()`](https://doc.rust-lang.org/stable/std/hint/fn.black_box.html) documentation. Specifically, it teaches _how_ to use it, instead of just _when_ to use it. I tried my best to make it clear and accurate, but a lot of my information is sourced from rust-lang/rust-clippy#12707 and [manually inspecting assembly](https://godbolt.org/). Please tell me if I got anything wrong!
Clarify how to use `black_box()` Closes rust-lang#133923. r? libs ^ (I think that's the right group, this is my first time!) This PR adds further clarification on the [`black_box()`](https://doc.rust-lang.org/stable/std/hint/fn.black_box.html) documentation. Specifically, it teaches _how_ to use it, instead of just _when_ to use it. I tried my best to make it clear and accurate, but a lot of my information is sourced from rust-lang/rust-clippy#12707 and [manually inspecting assembly](https://godbolt.org/). Please tell me if I got anything wrong!
Clarify how to use `black_box()` Closes rust-lang#133923. r? libs ^ (I think that's the right group, this is my first time!) This PR adds further clarification on the [`black_box()`](https://doc.rust-lang.org/stable/std/hint/fn.black_box.html) documentation. Specifically, it teaches _how_ to use it, instead of just _when_ to use it. I tried my best to make it clear and accurate, but a lot of my information is sourced from rust-lang/rust-clippy#12707 and [manually inspecting assembly](https://godbolt.org/). Please tell me if I got anything wrong!
Clarify how to use `black_box()` Closes rust-lang#133923. r? libs ^ (I think that's the right group, this is my first time!) This PR adds further clarification on the [`black_box()`](https://doc.rust-lang.org/stable/std/hint/fn.black_box.html) documentation. Specifically, it teaches _how_ to use it, instead of just _when_ to use it. I tried my best to make it clear and accurate, but a lot of my information is sourced from rust-lang/rust-clippy#12707 and [manually inspecting assembly](https://godbolt.org/). Please tell me if I got anything wrong!
Clarify how to use `black_box()` Closes rust-lang#133923. r? libs ^ (I think that's the right group, this is my first time!) This PR adds further clarification on the [`black_box()`](https://doc.rust-lang.org/stable/std/hint/fn.black_box.html) documentation. Specifically, it teaches _how_ to use it, instead of just _when_ to use it. I tried my best to make it clear and accurate, but a lot of my information is sourced from rust-lang/rust-clippy#12707 and [manually inspecting assembly](https://godbolt.org/). Please tell me if I got anything wrong!
Clarify how to use `black_box()` Closes rust-lang#133923. r? libs ^ (I think that's the right group, this is my first time!) This PR adds further clarification on the [`black_box()`](https://doc.rust-lang.org/stable/std/hint/fn.black_box.html) documentation. Specifically, it teaches _how_ to use it, instead of just _when_ to use it. I tried my best to make it clear and accurate, but a lot of my information is sourced from rust-lang/rust-clippy#12707 and [manually inspecting assembly](https://godbolt.org/). Please tell me if I got anything wrong!
Clarify how to use `black_box()` Closes rust-lang#133923. r? libs ^ (I think that's the right group, this is my first time!) This PR adds further clarification on the [`black_box()`](https://doc.rust-lang.org/stable/std/hint/fn.black_box.html) documentation. Specifically, it teaches _how_ to use it, instead of just _when_ to use it. I tried my best to make it clear and accurate, but a lot of my information is sourced from rust-lang/rust-clippy#12707 and [manually inspecting assembly](https://godbolt.org/). Please tell me if I got anything wrong!
Clarify how to use `black_box()` Closes rust-lang#133923. r? libs ^ (I think that's the right group, this is my first time!) This PR adds further clarification on the [`black_box()`](https://doc.rust-lang.org/stable/std/hint/fn.black_box.html) documentation. Specifically, it teaches _how_ to use it, instead of just _when_ to use it. I tried my best to make it clear and accurate, but a lot of my information is sourced from rust-lang/rust-clippy#12707 and [manually inspecting assembly](https://godbolt.org/). Please tell me if I got anything wrong!
Rollup merge of rust-lang#133942 - BD103:black-box-docs, r=saethlin Clarify how to use `black_box()` Closes rust-lang#133923. r? libs ^ (I think that's the right group, this is my first time!) This PR adds further clarification on the [`black_box()`](https://doc.rust-lang.org/stable/std/hint/fn.black_box.html) documentation. Specifically, it teaches _how_ to use it, instead of just _when_ to use it. I tried my best to make it clear and accurate, but a lot of my information is sourced from rust-lang/rust-clippy#12707 and [manually inspecting assembly](https://godbolt.org/). Please tell me if I got anything wrong!
Location
The API documentation for
black_box()
.Summary
Please see rust-lang/rust-clippy#12707 for more context!
I believe the API docs for
black_box()
are unclear when passed a unit-returning function. For example:The
black_box()
call makes the returned value treated as volatile, which is pointless because it is a zero-sized type. The above code is equivalent1 to just:This is unclear in the documentation for
black_box()
, though. The docs make it seem like the actual call tothread::sleep(...)
will be barred from optimizations, which isn't true. As pointed out by y21, constant-folding and other optimizations are still present:I propose that the docs be updated to mention that
black_box()
makes the value appear volatile to the compiler, and does not affect the argument passed to it.Footnotes
Mostly equivalent.
black_box()
does prevent optimizations fromcall
tojmp
instructions, even when the function returns unit. See Godbolt. Are there any other possible optimizations that may make this meaningful? ↩The text was updated successfully, but these errors were encountered: