Clarify `black_box()` docs when passed a unit-returning function

[BD103]

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:

let x: () = black_box(thread::sleep(...));

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 equivalent¹ to just:

let x: () = thread::sleep(...);

This is unclear in the documentation for black_box(), though. The docs make it seem like the actual call to thread::sleep(...) will be barred from optimizations, which isn't true. As pointed out by y21, constant-folding and other optimizations are still present:

// This...
let y = black_box(42 * 42);
// ...gets compiled to this:
let y = black_box(1764);

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

1. Mostly equivalent. black_box() does prevent optimizations from call to jmp instructions, even when the function returns unit. See Godbolt. Are there any other possible optimizations that may make this meaningful? ↩

[saethlin]

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.

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.

[workingjubilee]

Confirming: this is a library documentation issue.

[BD103]

@rustbot claim