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.

Sign up for GitHub

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

Jump to bottom

Improve the documentation of black_box #106144

Merged
merged 1 commit into from
Jan 22, 2023
Merged

Improve the documentation of black_box #106144

merged 1 commit into from
Jan 22, 2023

Conversation

tgross35
Copy link
Contributor

There don't seem to be many great resources on how black_box should be used, so I added some information here

@rustbot
Copy link
Collaborator

rustbot commented Dec 25, 2022

Thanks for the pull request, and welcome! The Rust team is excited to review your changes, and you should hear from @joshtriplett (or someone else) soon.

Please see the contribution instructions for more information.

@rustbot rustbot added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. T-libs Relevant to the library team, which will review and decide on the PR/issue. labels Dec 25, 2022
@rustbot
Copy link
Collaborator

rustbot commented Dec 25, 2022

Hey! It looks like you've submitted a new PR for the library teams!

If this PR contains changes to any rust-lang/rust public library APIs then please comment with @rustbot label +T-libs-api -T-libs to tag it appropriately. If this PR contains changes to any unstable APIs please edit the PR description to add a link to the relevant API Change Proposal or create one if you haven't already. If you're unsure where your change falls no worries, just leave it as is and the reviewer will take a look and make a decision to forward on if necessary.

Examples of T-libs-api changes:

  • Stabilizing library features
  • Introducing insta-stable changes such as new implementations of existing stable traits on existing stable types
  • Introducing new or changing existing unstable library APIs (excluding permanently unstable features / features without a tracking issue)
  • Changing public documentation in ways that create new stability guarantees
  • Changing observable runtime behavior of library APIs

@rust-log-analyzer

This comment has been minimized.

Sign in to view
@tgross35
Copy link
Contributor Author

@rustbot label +A-docs

@rustbot rustbot added the A-docs Area: documentation for any part of the project, including the compiler, standard library, and tools label Dec 25, 2022
Mark-Simulacrum
Mark-Simulacrum reviewed Dec 25, 2022
View reviewed changes
library/core/src/hint.rs Outdated
/// This makes our benchmark much more realistic to how the function would be used in situ, where
/// arguments are usually not known at compile time and the result is used in some way.
///
/// It is important to note that `black_box` cannot stop all optimizations across its call in all
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this might be understating a little - I know there was some discussion prior to stabilization/on the release blog post about emphasizing more of the lack of guarantees (cc @nagisa @saethlin).

I think at minimum, we shouldn't try to phrase it as "not stopping all optimizations", which makes it sound like some are guaranteed.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Would something like this be better?

A word on guarantees

It is important to reiterate the above: black_box does not guarantee with any certainty what optimizations may or may not happen. Variations such as different compiler backends, different targets,
or even just corner case code may mean it has no effects at all. The Rust team attempts to make sure this doesn't happen, but it cannot be guaratnteed: for that reason, black_box should never be relied on for controlling behavior outside of test cases or benchmarks.

For the most performance-critical cases, there is no substitute for validating the generated assembly and using performance tools (e.g. perf or callgrind) to analyze your code. That being said, black_box is suitable for creating fairly accurate benchmarks in most cases, for most users.

I don't think I know enough about the specific context to know how accurate that is, so open to suggestions (didn't see too much on #64102)

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would prefer changing the wording of the text you're proposing adding, as opposed to adding another section. Documentation here should emphasize everywhere that black_box having any effect at all on a program is entirely best-effort, it may do nothing at all, and therefore this is only for benchmarks. The are already people who think it is for writing cryptography code, and that is wrong.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In practice this function is pretty reliable, but it is absolutely NOT completely reliable, and even if it were, documenting what it actually accomplishes if it were reliable sounds like a nightmare.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've rearranged this somewhat and now that bit is at the beginning: https://github.com/rust-lang/rust/blob/79cf860f397aff83d283ac8de0ac77057ec59147/library/core/src/hint.rs#L225-L233

Folyd
Folyd reviewed Dec 26, 2022
View reviewed changes
library/core/src/hint.rs Outdated Show resolved Hide resolved
@tgross35 tgross35 force-pushed the patch-1 branch 2 times, most recently from 6f5c50f to 79cf860 Compare January 4, 2023 07:20
saethlin
saethlin reviewed Jan 7, 2023
View reviewed changes
library/core/src/hint.rs Outdated Show resolved Hide resolved
saethlin
saethlin reviewed Jan 7, 2023
View reviewed changes
library/core/src/hint.rs Outdated Show resolved Hide resolved
@saethlin
Copy link
Member

saethlin commented Jan 7, 2023

I really like the changes you've made. The documentation as-written now answers all my concerns, I've just left some grammar/phrasing tweaks.

@tgross35
Copy link
Contributor Author

tgross35 commented Jan 7, 2023

Thank you, I've applied your changes & rebased

@tgross35
Copy link
Contributor Author

I don't think there are further changes (let me know if so) so

r? Mark-Simulacrum

(Not sure if you can merge saethlin)

@Mark-Simulacrum
Copy link
Member

@bors r+ rollup

@bors
Copy link
Contributor

bors commented Jan 21, 2023

📌 Commit 13e25b8 has been approved by Mark-Simulacrum

It is now in the queue for this repository.

@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 Jan 21, 2023
matthiaskrgr added a commit to matthiaskrgr/rust that referenced this pull request Jan 21, 2023
@matthiaskrgr
Rollup merge of rust-lang#106144 - tgross35:patch-1, r=Mark-Simulacrum
66aa7d8 
Improve the documentation of `black_box`

There don't seem to be many great resources on how `black_box` should be used, so I added some information here
@matthiaskrgr matthiaskrgr mentioned this pull request Jan 21, 2023
Closed
@tgross35
Copy link
Contributor Author

Thanks!

compiler-errors added a commit to compiler-errors/rust that referenced this pull request Jan 22, 2023
@compiler-errors
Rollup merge of rust-lang#106144 - tgross35:patch-1, r=Mark-Simulacrum
03a069c 
Improve the documentation of `black_box`

There don't seem to be many great resources on how `black_box` should be used, so I added some information here
This was referenced Jan 22, 2023
Closed
Merged
bors added a commit to rust-lang-ci/rust that referenced this pull request Jan 22, 2023
@bors
Auto merge of rust-lang#107185 - compiler-errors:rollup-wkomjma, r=co…
940d00f 
…mpiler-errors

Rollup of 8 pull requests

Successful merges:

 - rust-lang#103418 (Add `SEMICOLON_IN_EXPRESSIONS_FROM_MACROS` to future-incompat report)
 - rust-lang#106113 (llvm-wrapper: adapt for LLVM API change)
 - rust-lang#106144 (Improve the documentation of `black_box`)
 - rust-lang#106578 (Label closure captures/generator locals that make opaque types recursive)
 - rust-lang#106749 (Update cc to 1.0.77)
 - rust-lang#106935 (Fix `SingleUseLifetime` ICE)
 - rust-lang#107015 (Re-enable building rust-analyzer on riscv64)
 - rust-lang#107029 (Add new bootstrap members to triagebot.toml)

Failed merges:

r? `@ghost`
`@rustbot` modify labels: rollup
@bors bors merged commit d1405c8 into rust-lang:master Jan 22, 2023
@rustbot rustbot added this to the 1.68.0 milestone Jan 22, 2023
@tgross35 tgross35 deleted the patch-1 branch March 7, 2023 17:21
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@Folyd Folyd Folyd left review comments

@Mark-Simulacrum Mark-Simulacrum Mark-Simulacrum left review comments

@saethlin saethlin saethlin left review comments

Assignees

@Mark-Simulacrum Mark-Simulacrum

Labels
A-docs Area: documentation for any part of the project, including the compiler, standard library, and tools S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. T-libs Relevant to the library team, which will review and decide on the PR/issue.
Projects
None yet
Milestone
1.68.0
Development

Successfully merging this pull request may close these issues.
8 participants
@tgross35 @rustbot @rust-log-analyzer @saethlin @Mark-Simulacrum @bors @Folyd @joshtriplett