Add hint::assume

[scottmcm]

Proposal

Now that hint::unreachable_unchecked() is stable, people say things like

strategically placed core::hint::unreachable_unchecked?

when intentionally adding UB in certain paths.

We should just have hint::assume(cond) rather than making those people write out if !cond { hint::unreachable_unchecked() }.

assume has its own gotchas, certainly, like how adding it can actually make things slower. But that's even more so the case for writing out the condition yourself, so I don't think that's a reason to not have a canonical way to write it.

The canonical way could also expose implement it with https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/mir/syntax/enum.NonDivergingIntrinsic.html#variant.Assume -- because that's what the assume intrinsic does already -- which is nicer in MIR than the if phrasing since it doesn't split basic blocks.

Solution sketch

// in core::hint (and std::hint)

/// Makes a *soundness* promise to the compiler that `cond` holds.
///
/// This may allow the optimizer to simplify things,
/// but it might also make the generated code slower.
/// Either way, calling it will most likely make compilation take longer.
///
/// This is a situational tool for micro-optimization, and is allowed to do nothing.
/// Any use should come with a repeatable benchmark to show the value
/// and allow removing it later should the optimizer get smarter and no longer need it.
///
/// The more complicated the condition the less likely this is to be fruitful.
/// For example, `assume(foo.is_sorted())` is a complex enough value that
/// the compiler is unlikely to be able to take advantage of it.
///
/// There's also no need to `assume` basic properties of things.  For example,
/// the compiler already knows the range of `count_ones`, so there's no benefit
/// to `let n = u32::count_ones(x); assume(n <= u32::BITS);`.  
///
/// This promotes a correctness requirement to a soundness requirement.
/// Don't do that without very good reason.
///
/// # Safety
///
/// `cond` must be `true`.  It's immediate UB to call this with `false`.
///
#[inline(always)]
pub const unsafe fn assume(cond: bool) { unsafe { crate::intrinsics::assume(cond) } }

Alternatives

• This isn't strictly necessary. We could have people continue to write it with unreachable_unchecked.
• This could be done as a macro instead, since it's particularly useless without inlining. With MIR inlining, though, it should be reliably inlined, since it's a trivial 1-thing basic block.
• It could have a different name, like assume_unchecked or assert_unchecked. But assume is a long-standing name for this, so it's what I proposed. I'm fine to use whatever name libs-api would like best.
• For a long time we were intentionally not adding things like this, but now that we have explicitly-UB things like unreachable_unchecked and libs-api feels positive about things like u32::unchecked_add, I think having this fits with modern precedent .

What happens now?

This issue contains an API change proposal (or ACP) and is part of the libs-api team feature lifecycle. Once this issue is filed, the libs-api team will review open proposals as capability becomes available. Current response times do not have a clear estimate, but may be up to several months.

Possible responses

The libs team may respond in various different ways. First, the team will consider the problem (this doesn't require any concrete solution or alternatives to have been proposed):

• We think this problem seems worth solving, and the standard library might be the right place to solve it.
• We think that this probably doesn't belong in the standard library.

Second, if there's a concrete solution:

• We think this specific solution looks roughly right, approved, you or someone else should implement this. (Further review will still happen on the subsequent implementation PR.)
• We're not sure this is the right solution, and the alternatives or other materials don't give us enough information to be sure about that. Here are some questions we have that aren't answered, or rough ideas about alternatives we'd want to see discussed.

[Noratrieb]

I prefer the name assume_unchecked, it better mirrors unreachable_unchecked. unreachable is also the common for the latter in C and codegen backends, yet we still added the unchecked suffix (in part to show the uncheckedness, in part because unreachable was already used). We should do the same to assume.

[the8472]

The _unchecked methods usually have a checked, safe equivalent. A safe assume_checked wouldn't make much sense I think and it would not really be a hint anymore. People already get those effects from sprinkling assert in the right places for example.

[RalfJung]

So, assert_unchecked then?

[the8472]

I guess that works. I was so used to assume that I didn't even consider it. But we could slap an alias on it for anyone looking for assume.

[joshtriplett]

We discussed this in today's @rust-lang/libs-api meeting. We had consensus that we want this method, and ended up bikeshedding over the name. We also had consensus that we wanted unchecked in the name; we were just debating assume_unchecked vs assert_unchecked.

[scottmcm]

If it's going to have _unchecked, I like asset_unchecked better personally.

Having unreachable!() + unsafe unreachable_unchecked() already definitely pushes me to assert!() + unsafe assert_unchecked().

I'll send a PR; we can always bikeshed in nightly.

EDIT: Tracking issue rust-lang/rust#119131

[tgross35]

Can this ACP be closed since the feature was added?