Description
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_uncheckedorassert_unchecked. Butassumeis 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_uncheckedand libs-api feels positive about things likeu32::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.