Stabilize hint::assert_unchecked

[tgross35]

Make the following API stable, including const:

// core::hint, std::hint

pub const unsafe fn assert_unchecked(p: bool);

This PR also reworks some of the documentation and adds an example.

Tracking issue: #119131
FCP: #119131 (comment). The docs update should resolve the remaining concern.

[rustbot]

r? @jhpratt

rustbot has assigned @jhpratt.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

[tgross35]

I don't think there is much purpose in keeping a separate const_* feature gate if const stabilization happens at the same time, so merged the gates.

r? libs-api
@rustbot label -T-libs +T-libs-api
cc @scottmcm
cc @rust-lang/wg-const-eval (and @RalfJung directly since it seems like that ping doesn't always work) for const concerns

[RalfJung]

cc @rust-lang/wg-const-eval (and @RalfJung directly since it seems like that ping doesn't always work)

It doesn't? I think it always works, except that the person writing the post has to be an org member to ping org teams. (You can tell because the team doesn't get highlighted and linked if a non-org-member writes @rust-lang/wg-const-eval.)

[Mark-Simulacrum]

This feels like a pretty weird example. Do we not have something better? We even have to defend the example later in the documentation as being not real world.

One example that feels more illustrative is guaranteeing that the returned integer is in-bounds for some slice. For example, binary search tells LLVM that the indexes it returns are in-bounds of the length. Replicating binary search here probably is too much, but replicating a simpler algorithm (e.g., &[(u32, usize)] where you search for a particular needle and every usize is guaranteed to be an index in the array -- so before returning it you want to tell LLVM that) feels like a better example.

[tgross35]

I didn't think there was much purpose in showing a real example of how it may be used in practice since we say elsewhere that you should only use this after benchmarking, and that a smarter optimizer may be able to figure it out at some point. So rather than showing an real usecase that might go away, I figured a dummy example of how it can actually affect codegen may be more useful.

But I am happy to change here as needed, maybe I can rework this example to make its intent more obvious.

[BurntSushi]

I like this example. It's not necessarily real world, but I do think it is effective at demonstrating the principle here in a pretty small and easily digestible code snippet.

[tgross35]

cc @rust-lang/wg-const-eval (and @RalfJung directly since it seems like that ping doesn't always work)

It doesn't? I think it always works, except that the person writing the post has to be an org member to ping org teams. (You can tell because the team doesn't get highlighted and linked if a non-org-member writes @rust-lang/wg-const-eval.)

Ah, I remember a couple of times when @ed the team on a PR and you said you didn't get it, must have just been from before I was a member then. Makes sense.

[bors]

☔ The latest upstream changes (presumably #104087) made this pull request unmergeable. Please resolve the merge conflicts.

[c410-f3r]

ping @BurntSushi

Was your concern resolved by the documentation presented in this PR?

[BurntSushi]

I like this example. It's not necessarily real world, but I do think it is effective at demonstrating the principle here in a pretty small and easily digestible code snippet.

[BurntSushi]

@c410-f3r Yes, I'd be happy to resolve my concern once this is merged.

[c410-f3r]

Thanks @BurntSushi

[jhpratt]

@BurntSushi Given that FCP is blocked on docs and this PR is open to both stabilize and resolve the concern, what would you prefer? Should the PR be split up such that docs can be merged, the concern resolved, and FCP started, or should the concern be lifted on the basis that it will be resolved at the same time as stabilization? I'd prefer the latter for simplicity.

[tgross35]

Ah this slipped my mind but is waiting on me, I’ll incorporate the feedback tomorrow. I think burntsushi said somehow that this PR is suitable to resolve the docs concern.

@rustbot author

[BurntSushi]

Yeah I see the conflict here. I think when I was reviewing this, I thought this was just a doc update. Yes, in the future, I think that should be de-coupled from stabilization itself, otherwise we have a chicken & egg problem. Generally speaking, I'd like to see doc updates merged before resolving my concern. But I've resolved the concern in #119131.

[tgross35]

I updated the docs based on the feedback. Since you have been pretty involved here,
r? @BurntSushi

[tgross35]

Oh whoops, forgot the important labels

@rustbot ready

[dtolnay]

Thanks!

[dtolnay]

@bors r+

[bors]

📌 Commit 5745c22 has been approved by dtolnay

It is now in the queue for this repository.