Clarify how to use black_box()

[BD103]

Closes #133923.

r? libs
^ (I think that's the right group, this is my first time!)

This PR adds further clarification on the black_box() 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. Please tell me if I got anything wrong!

[rustbot]

Thanks for the pull request, and welcome! The Rust team is excited to review your changes, and you should hear from @tgross35 (or someone else) some time within the next two weeks.

Please see the contribution instructions for more information. Namely, in order to ensure the minimum review times lag, PR authors and assigned reviewers should ensure that the review label (S-waiting-on-review and S-waiting-on-author) stays updated, invoking these commands when appropriate:

• @rustbot author: the review is finished, PR author should check the comments and take action accordingly
• @rustbot review: the author is ready for a review, this PR will be queued again in the reviewer's queue

[tgross35]

Could this go into a new section like # Usage Guidelines? The docs for this method are getting pretty long.

I think it would also be better to move this new section to the end, the Note however, that black_box is only (and can only be) provided on a "best-effort" basis... section is important to have early.

@saethlin I think you've reviewed these docs a couple of times

[saethlin]

I'm already subscribed to this issue :)
Do you want me to take the review?

[tgross35]

No preference, I'm happy to but all yours if you want (same for Jubilee)

[BD103]

@rustbot author

I'll address the changes later today or sunday, thanks for looking this over!

[BD103]

@rustbot review

[BD103]

Ok, I tried my best to address the feedback! Thank you for reviewing :)

[ryanavella]

There is one other trick I sometimes use to prevent the inlining of a function, not sure if it is worth illustrating in the docs but here is what it looks like:

#[inline(always)]
fn noop() {}

pub fn bad() {
    black_box(noop());
}

pub fn good() {
    black_box(noop as fn())();
}

[saethlin]

Oh sweet that's a great example of when #[inline(always)] doesn't actually cause a function call to be inlined!

[tgross35]

r? @saethlin :)

[saethlin]

Thanks! Squash this down to 1 commit (or I can do that for you), then I'll send this off to the queue.

[workingjubilee]

Cool! Thanks for the fix, and thanks for taking the rest of the review, @saethlin!