Tracking Issue for hint::assert_unchecked

[scottmcm]

Feature gate: #![feature(hint_assert_unchecked)]

This is a tracking issue for ...

Public API

// core::hint

pub const unsafe fn assert_unchecked(p: bool);

Steps / History

• ACP: Add hint::assume libs-team#315
• Implementation: Add hint::assert_unchecked #119133
• Final comment period (FCP)¹
• Stabilization PR

Unresolved Questions

• Naming, as always: Add hint::assume libs-team#315 (comment)

Footnotes

1. https://std-dev-guide.rust-lang.org/feature-lifecycle/stabilization.html ↩

[scottmcm]

Hello libs-api folks! I'm nominating this (at low priority) because when the open issue is the name, I think it mostly needs your input to make progress.

[bend-n]

What if the name was safety_invariant?

    unsafe fn get_unchecked(self, slice: *const [T]) -> *const T {
        unsafe { slice.as_ptr().add(self) }
        unsafe {
            safety_invariant(self < slice.len());
            slice.as_ptr().add(self)
        }
    }

[Amanieu]

We discussed this in the libs-api meeting and we're happy with assert_unchecked because it follows the existing pattern of _unchecked functions in the standard library.

@rfcbot fcp merge

[rfcbot]

Team member @Amanieu has proposed to merge this. The next step is review by the rest of the tagged team members:

• @Amanieu
• @BurntSushi
• @dtolnay
• @joshtriplett
• @m-ou-se

Concerns:

• doc-example resolved by Tracking Issue for hint::assert_unchecked #119131 (comment)

Once a majority of reviewers approve (and at most 2 approvals are outstanding), this will enter its final comment period. If you spot a major issue that hasn't been raised at any point in this process, please speak up!

See this document for info about what commands tagged team members can give me.

[tgross35]

Todo list: docs could use an example

(+1 for the name assert_unchecked since it likely enables the same optimizations as assert)

[BurntSushi]

@rfcbot concern doc-example

I agree that we should have a doc example showing when someone might want to use this method. The docs otherwise look good as written!

[bend-n]

Suggestion for doc example: show example implementation of [T]::slice_unchecked?

[tgross35]

Could assert_unsafe_precondition! emit assert_unchecked when debug assertions are disabled? #123561 looks like a case where assuming the unsafe preconditions would have led to more efficient codegen, I am sure there are others.

Edit: I guess assert_unchecked calls assert_unsafe_precondition so calling intrinsics::assume would be correct.

[tgross35]

I am unsure whether the FCP at #119131 (comment) was purely for the unstable name change or an intent to stabilize; assuming the latter, I created a stabilization PR at #123588.

That PR should also resolve the docs example concern.

[scottmcm]

Could assert_unsafe_precondition! emit assert_unchecked when debug assertions are disabled?

The problem is that all those extra assumes in codegen have pretty high compile-time cost, and because they change inlining metrics can actually make runtime performance worse.

[BurntSushi]

@rfcbot resolve doc-example

[rfcbot]

🔔 This is now entering its final comment period, as per the review above. 🔔

[rfcbot]

The final comment period, with a disposition to merge, as per the review above, is now complete.

As the automated representative of the governance process, I would like to thank the author for their work and everyone else who contributed.

This will be merged soon.

[FeldrinH]

What happens if the expression passed to assert_unchecked has a side effect? I could not find a clear answer in the current documentation.

[scottmcm]

assert_unchecked is an ordinary function, not a macro. There's only a value passed to it; it works like a call to any other function.

[FeldrinH]

In that case I think the documentation could use a clarification on a few related points:

• The documentation for __builtin_assume explicitly states that side effects of the expression passed to it are discarded. If this is not the case for assert_unchecked then that difference should probably be highlighted, since the documentation for assert_unchecked implies that assert_unchecked and __builtin_assume are equivalent.
• Is the expression passed to assert_unchecked likely/guaranteed to be optimized out in a release compile if it has no side effects? This could matter quite a bit for microoptimizations.

[the8472]

Is the expression passed to assert_unchecked likely/guaranteed to be optimized out in a release compile if it has no side effects?

If there are no other uses? Probably, at some point in the optimization pipeline. But up to that point the expression is preserved which can affect earlier optimizations. Which is one of the reasons why the docs say

[... ]but it might also make the generated code slower

The usual approach is to benchmark, look at the assembly or look at the LLVM IR after optimizations to see if it's worthwhile. Blind applications of the hint are discouraged.

[jhpratt]

Closing as completed by #123588.