Expand core::hint::unreachable_unchecked() docs

[lukaslueg]

Rework the docs for unreachable_unchecked, encouraging deliberate use, and providing a better example for action at a distance.

Fixes #95865

[rust-highfive]

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 r? rust-lang/libs-api @rustbot label +T-libs-api -T-libs to request review from a libs-api team reviewer. 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-highfive]

r? @scottmcm

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

[Noratrieb]

This function should be marked unsafe, to make it clear that the invariants established in prepare_inputs must be upheld.

[scottmcm]

Agreed, and have a comment on it like

Suggested change

	/// fn do_computation(i: u32, divisors: &[u32]) -> u32 {
	/// /// # Safety
	/// /// All the elements of `divisors` must be non-zero.
	/// fn do_computation(i: u32, divisors: &[u32]) -> u32 {

As well as // Safety: ... comment on the unsafe block for the call.

[Noratrieb]

Thank you for cleaning up the docs and providing an example! I think this example is not ideal, since it could be replaced by using NonZeroU32. A more common thing that I've seen it being used for is to unwrap enum values uncheckedly, for example

enum Mascot {
    Ferris,
    Corro {
        unsafe_permit: String,
    },
}

impl Mascot {
    unsafe fn get_unsafe_permit_unchecked(&self) -> &str {
        match self {
            Mascot::Corro { unsafe_permit } => {
                unsafe_permit
            }
            Mascot::Ferris => {
                std::hint::unreachable_unchecked()
            }
        }
    }
}

I think using such an example would better illustrate the unique capabilities of this function, since it cannot be implemented in other ways. (feel free to use my example or choose another one)

[lukaslueg]

@Nilstrieb I know about NonZero and deliberately chose the example given anyway because it shows the possibly beneficial side effects of unreachable_unchecked.

[scottmcm]

nit: like you said "possibly enabling" above, I think this should also update accordingly. And I maybe "reach" could be tweaked too, since the branch arguably doesn't directly "reach" a call, but reaches a block containing the call?

Suggested change

	/// will eliminate all branches which themselves reach a call to
	/// may eliminate all branches which themselves lead to a call to

[lukaslueg]

You are referring to "possibly" -> "it will possibly eliminate"? I suggest keeping using strong language here because the programmer should always assume that the compiler does eliminate those branches, even if it technically doesn't, yet does other funky stuff which causes time travel and nose daemons.

Maybe more clear: "it will eliminate all branches in the surrounding code which the compiler can determine will invariably lead to a call to unreachable_unchecked!."

[scottmcm]

fix: We try to be really careful about "safe" in these docs, since it implies "not unsafe". I think this should be

Suggested change

	/// While using `unreachable_unchecked()` is perfectly safe in the following
	/// While using `unreachable_unchecked()` is perfectly sound in the following

[lukaslueg]

Addressed previous comments. Maybe I should add a comment to the tune that the behavior shown in the example is provided by core::num::NotZero... automatically?

[scottmcm]

Arguably "difficult to debug" is the least of the problems with UB, but that was already here, so this PR doesn't really need to fix it.

[scottmcm]

Thanks! I agree this is better than what was there before, so it's good to go in:

@bors r+ rollup=always

For future reference, to update the attributes on a PR once you've made changes, you can use @rustbot ready.

[bors]

📌 Commit cd1746b has been approved by scottmcm