1//! Provides the [`assert_unsafe_precondition`] macro as well as some utility functions that cover
2//! common preconditions.
3
4use crate::intrinsics::{self, const_eval_select};
5
6/// Check that the preconditions of an unsafe function are followed. The check is enabled at
7/// runtime if debug assertions are enabled when the caller is monomorphized. In const-eval/Miri
8/// checks implemented with this macro for language UB are always ignored.
9///
10/// This macro should be called as
11/// `assert_unsafe_precondition!(check_{library,lang}_ub, "message", (ident: type = expr, ident: type = expr) => check_expr)`
12/// where each `expr` will be evaluated and passed in as function argument `ident: type`. Then all
13/// those arguments are passed to a function with the body `check_expr`.
14/// Pick `check_language_ub` when this is guarding a violation of language UB, i.e., immediate UB
15/// according to the Rust Abstract Machine. Pick `check_library_ub` when this is guarding a violation
16/// of a documented library precondition that does not *immediately* lead to language UB.
17///
18/// If `check_library_ub` is used but the check is actually guarding language UB, the check will
19/// slow down const-eval/Miri and we'll get the panic message instead of the interpreter's nice
20/// diagnostic, but our ability to detect UB is unchanged.
21/// But if `check_language_ub` is used when the check is actually for library UB, the check is
22/// omitted in const-eval/Miri and thus if we eventually execute language UB which relies on the
23/// library UB, the backtrace Miri reports may be far removed from original cause.
24///
25/// These checks are behind a condition which is evaluated at codegen time, not expansion time like
26/// [`debug_assert`]. This means that a standard library built with optimizations and debug
27/// assertions disabled will have these checks optimized out of its monomorphizations, but if a
28/// caller of the standard library has debug assertions enabled and monomorphizes an expansion of
29/// this macro, that monomorphization will contain the check.
30///
31/// Since these checks cannot be optimized out in MIR, some care must be taken in both call and
32/// implementation to mitigate their compile-time overhead. Calls to this macro always expand to
33/// this structure:
34/// ```ignore (pseudocode)
35/// if ::core::intrinsics::check_language_ub() {
36/// precondition_check(args)
37/// }
38/// ```
39/// where `precondition_check` is monomorphic with the attributes `#[rustc_nounwind]`, `#[inline]` and
40/// `#[rustc_no_mir_inline]`. This combination of attributes ensures that the actual check logic is
41/// compiled only once and generates a minimal amount of IR because the check cannot be inlined in
42/// MIR, but *can* be inlined and fully optimized by a codegen backend.
43///
44/// Callers should avoid introducing any other `let` bindings or any code outside this macro in
45/// order to call it. Since the precompiled standard library is built with full debuginfo and these
46/// variables cannot be optimized out in MIR, an innocent-looking `let` can produce enough
47/// debuginfo to have a measurable compile-time impact on debug builds.
48#[allow_internal_unstable(const_ub_checks)] // permit this to be called in stably-const fn
49macro_rules! assert_unsafe_precondition {
50 ($kind:ident, $message:expr, ($($name:ident:$ty:ty = $arg:expr),*$(,)?) => $e:expr $(,)?) => {
51 {
52 // This check is inlineable, but not by the MIR inliner.
53 // The reason for this is that the MIR inliner is in an exceptionally bad position
54 // to think about whether or not to inline this. In MIR, this call is gated behind `debug_assertions`,
55 // which will codegen to `false` in release builds. Inlining the check would be wasted work in that case and
56 // would be bad for compile times.
57 //
58 // LLVM on the other hand sees the constant branch, so if it's `false`, it can immediately delete it without
59 // inlining the check. If it's `true`, it can inline it and get significantly better performance.
60 #[rustc_no_mir_inline]
61 #[inline]
62 #[rustc_nounwind]
63 #[rustc_const_unstable(feature = "const_ub_checks", issue = "none")]
64 const fn precondition_check($($name:$ty),*) {
65 if !$e {
66 ::core::panicking::panic_nounwind(
67 concat!("unsafe precondition(s) violated: ", $message)
68 );
69 }
70 }
71
72 if ::core::ub_checks::$kind() {
73 precondition_check($($arg,)*);
74 }
75 }
76 };
77}
78pub(crate) use assert_unsafe_precondition;
79
80/// Checking library UB is always enabled when UB-checking is done
81/// (and we use a reexport so that there is no unnecessary wrapper function).
82pub(crate) use intrinsics::ub_checks as check_library_ub;
83
84/// Determines whether we should check for language UB.
85///
86/// The intention is to not do that when running in the interpreter, as that one has its own
87/// language UB checks which generally produce better errors.
88#[rustc_const_unstable(feature = "const_ub_checks", issue = "none")]
89#[inline]
90pub(crate) const fn check_language_ub() -> bool {
91 #[inline]
92 fn runtime() -> bool {
93 // Disable UB checks in Miri.
94 !cfg!(miri)
95 }
96
97 #[inline]
98 const fn comptime() -> bool {
99 // Always disable UB checks.
100 false
101 }
102
103 // Only used for UB checks so we may const_eval_select.
104 intrinsics::ub_checks() && const_eval_select((), _called_in_const:comptime, _called_at_rt:runtime)
105}
106
107/// Checks whether `ptr` is properly aligned with respect to
108/// `align_of::<T>()`.
109///
110/// In `const` this is approximate and can fail spuriously. It is primarily intended
111/// for `assert_unsafe_precondition!` with `check_language_ub`, in which case the
112/// check is anyway not executed in `const`.
113#[inline]
114pub(crate) const fn is_aligned_and_not_null(ptr: *const (), align: usize) -> bool {
115 !ptr.is_null() && ptr.is_aligned_to(align)
116}
117
118#[inline]
119pub(crate) const fn is_valid_allocation_size(size: usize, len: usize) -> bool {
120 let max_len: usize = if size == 0 { usize::MAX } else { isize::MAX as usize / size };
121 len <= max_len
122}
123
124/// Checks whether the regions of memory starting at `src` and `dst` of size
125/// `count * size` do *not* overlap.
126///
127/// Note that in const-eval this function just returns `true` and therefore must
128/// only be used with `assert_unsafe_precondition!`, similar to `is_aligned_and_not_null`.
129#[inline]
130pub(crate) const fn is_nonoverlapping(
131 src: *const (),
132 dst: *const (),
133 size: usize,
134 count: usize,
135) -> bool {
136 #[inline]
137 fn runtime(src: *const (), dst: *const (), size: usize, count: usize) -> bool {
138 let src_usize: usize = src.addr();
139 let dst_usize: usize = dst.addr();
140 let Some(size: usize) = size.checked_mul(count) else {
141 crate::panicking::panic_nounwind(
142 expr:"is_nonoverlapping: `size_of::<T>() * count` overflows a usize",
143 )
144 };
145 let diff: usize = src_usize.abs_diff(dst_usize);
146 // If the absolute distance between the ptrs is at least as big as the size of the buffer,
147 // they do not overlap.
148 diff >= size
149 }
150
151 #[inline]
152 const fn comptime(_: *const (), _: *const (), _: usize, _: usize) -> bool {
153 true
154 }
155
156 // This is just for safety checks so we can const_eval_select.
157 const_eval_select((src, dst, size, count), _called_in_const:comptime, _called_at_rt:runtime)
158}
159