core\intrinsics/mod.rs
1//! Compiler intrinsics.
2//!
3//! The corresponding definitions are in <https://github.com/rust-lang/rust/blob/master/compiler/rustc_codegen_llvm/src/intrinsic.rs>.
4//! The corresponding const implementations are in <https://github.com/rust-lang/rust/blob/master/compiler/rustc_const_eval/src/interpret/intrinsics.rs>.
5//!
6//! # Const intrinsics
7//!
8//! In order to make an intrinsic unstable usable at compile-time, copy the implementation from
9//! <https://github.com/rust-lang/miri/blob/master/src/intrinsics> to
10//! <https://github.com/rust-lang/rust/blob/master/compiler/rustc_const_eval/src/interpret/intrinsics.rs>
11//! and make the intrinsic declaration below a `const fn`. This should be done in coordination with
12//! wg-const-eval.
13//!
14//! If an intrinsic is supposed to be used from a `const fn` with a `rustc_const_stable` attribute,
15//! `#[rustc_intrinsic_const_stable_indirect]` needs to be added to the intrinsic. Such a change requires
16//! T-lang approval, because it may bake a feature into the language that cannot be replicated in
17//! user code without compiler support.
18//!
19//! # Volatiles
20//!
21//! The volatile intrinsics provide operations intended to act on I/O
22//! memory, which are guaranteed to not be reordered by the compiler
23//! across other volatile intrinsics. See the LLVM documentation on
24//! [[volatile]].
25//!
26//! [volatile]: https://llvm.org/docs/LangRef.html#volatile-memory-accesses
27//!
28//! # Atomics
29//!
30//! The atomic intrinsics provide common atomic operations on machine
31//! words, with multiple possible memory orderings. They obey the same
32//! semantics as C++11. See the LLVM documentation on [[atomics]].
33//!
34//! [atomics]: https://llvm.org/docs/Atomics.html
35//!
36//! A quick refresher on memory ordering:
37//!
38//! * Acquire - a barrier for acquiring a lock. Subsequent reads and writes
39//! take place after the barrier.
40//! * Release - a barrier for releasing a lock. Preceding reads and writes
41//! take place before the barrier.
42//! * Sequentially consistent - sequentially consistent operations are
43//! guaranteed to happen in order. This is the standard mode for working
44//! with atomic types and is equivalent to Java's `volatile`.
45//!
46//! # Unwinding
47//!
48//! Rust intrinsics may, in general, unwind. If an intrinsic can never unwind, add the
49//! `#[rustc_nounwind]` attribute so that the compiler can make use of this fact.
50//!
51//! However, even for intrinsics that may unwind, rustc assumes that a Rust intrinsics will never
52//! initiate a foreign (non-Rust) unwind, and thus for panic=abort we can always assume that these
53//! intrinsics cannot unwind.
54
55#![unstable(
56 feature = "core_intrinsics",
57 reason = "intrinsics are unlikely to ever be stabilized, instead \
58 they should be used through stabilized interfaces \
59 in the rest of the standard library",
60 issue = "none"
61)]
62#![allow(missing_docs)]
63
64use crate::marker::{DiscriminantKind, Tuple};
65use crate::mem::SizedTypeProperties;
66use crate::{ptr, ub_checks};
67
68pub mod fallback;
69pub mod mir;
70pub mod simd;
71
72// These imports are used for simplifying intra-doc links
73#[allow(unused_imports)]
74#[cfg(all(target_has_atomic = "8", target_has_atomic = "32", target_has_atomic = "ptr"))]
75use crate::sync::atomic::{self, AtomicBool, AtomicI32, AtomicIsize, AtomicU32, Ordering};
76
77// N.B., these intrinsics take raw pointers because they mutate aliased
78// memory, which is not valid for either `&` or `&mut`.
79
80/// Stores a value if the current value is the same as the `old` value.
81/// `T` must be an integer or pointer type.
82///
83/// The stabilized version of this intrinsic is available on the
84/// [`atomic`] types via the `compare_exchange` method by passing
85/// [`Ordering::Relaxed`] as both the success and failure parameters.
86/// For example, [`AtomicBool::compare_exchange`].
87#[rustc_intrinsic]
88#[rustc_nounwind]
89pub unsafe fn atomic_cxchg_relaxed_relaxed<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool);
90/// Stores a value if the current value is the same as the `old` value.
91/// `T` must be an integer or pointer type.
92///
93/// The stabilized version of this intrinsic is available on the
94/// [`atomic`] types via the `compare_exchange` method by passing
95/// [`Ordering::Relaxed`] and [`Ordering::Acquire`] as the success and failure parameters.
96/// For example, [`AtomicBool::compare_exchange`].
97#[rustc_intrinsic]
98#[rustc_nounwind]
99pub unsafe fn atomic_cxchg_relaxed_acquire<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool);
100/// Stores a value if the current value is the same as the `old` value.
101/// `T` must be an integer or pointer type.
102///
103/// The stabilized version of this intrinsic is available on the
104/// [`atomic`] types via the `compare_exchange` method by passing
105/// [`Ordering::Relaxed`] and [`Ordering::SeqCst`] as the success and failure parameters.
106/// For example, [`AtomicBool::compare_exchange`].
107#[rustc_intrinsic]
108#[rustc_nounwind]
109pub unsafe fn atomic_cxchg_relaxed_seqcst<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool);
110/// Stores a value if the current value is the same as the `old` value.
111/// `T` must be an integer or pointer type.
112///
113/// The stabilized version of this intrinsic is available on the
114/// [`atomic`] types via the `compare_exchange` method by passing
115/// [`Ordering::Acquire`] and [`Ordering::Relaxed`] as the success and failure parameters.
116/// For example, [`AtomicBool::compare_exchange`].
117#[rustc_intrinsic]
118#[rustc_nounwind]
119pub unsafe fn atomic_cxchg_acquire_relaxed<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool);
120/// Stores a value if the current value is the same as the `old` value.
121/// `T` must be an integer or pointer type.
122///
123/// The stabilized version of this intrinsic is available on the
124/// [`atomic`] types via the `compare_exchange` method by passing
125/// [`Ordering::Acquire`] as both the success and failure parameters.
126/// For example, [`AtomicBool::compare_exchange`].
127#[rustc_intrinsic]
128#[rustc_nounwind]
129pub unsafe fn atomic_cxchg_acquire_acquire<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool);
130/// Stores a value if the current value is the same as the `old` value.
131/// `T` must be an integer or pointer type.
132///
133/// The stabilized version of this intrinsic is available on the
134/// [`atomic`] types via the `compare_exchange` method by passing
135/// [`Ordering::Acquire`] and [`Ordering::SeqCst`] as the success and failure parameters.
136/// For example, [`AtomicBool::compare_exchange`].
137#[rustc_intrinsic]
138#[rustc_nounwind]
139pub unsafe fn atomic_cxchg_acquire_seqcst<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool);
140/// Stores a value if the current value is the same as the `old` value.
141/// `T` must be an integer or pointer type.
142///
143/// The stabilized version of this intrinsic is available on the
144/// [`atomic`] types via the `compare_exchange` method by passing
145/// [`Ordering::Release`] and [`Ordering::Relaxed`] as the success and failure parameters.
146/// For example, [`AtomicBool::compare_exchange`].
147#[rustc_intrinsic]
148#[rustc_nounwind]
149pub unsafe fn atomic_cxchg_release_relaxed<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool);
150/// Stores a value if the current value is the same as the `old` value.
151/// `T` must be an integer or pointer type.
152///
153/// The stabilized version of this intrinsic is available on the
154/// [`atomic`] types via the `compare_exchange` method by passing
155/// [`Ordering::Release`] and [`Ordering::Acquire`] as the success and failure parameters.
156/// For example, [`AtomicBool::compare_exchange`].
157#[rustc_intrinsic]
158#[rustc_nounwind]
159pub unsafe fn atomic_cxchg_release_acquire<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool);
160/// Stores a value if the current value is the same as the `old` value.
161/// `T` must be an integer or pointer type.
162///
163/// The stabilized version of this intrinsic is available on the
164/// [`atomic`] types via the `compare_exchange` method by passing
165/// [`Ordering::Release`] and [`Ordering::SeqCst`] as the success and failure parameters.
166/// For example, [`AtomicBool::compare_exchange`].
167#[rustc_intrinsic]
168#[rustc_nounwind]
169pub unsafe fn atomic_cxchg_release_seqcst<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool);
170/// Stores a value if the current value is the same as the `old` value.
171/// `T` must be an integer or pointer type.
172///
173/// The stabilized version of this intrinsic is available on the
174/// [`atomic`] types via the `compare_exchange` method by passing
175/// [`Ordering::AcqRel`] and [`Ordering::Relaxed`] as the success and failure parameters.
176/// For example, [`AtomicBool::compare_exchange`].
177#[rustc_intrinsic]
178#[rustc_nounwind]
179pub unsafe fn atomic_cxchg_acqrel_relaxed<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool);
180/// Stores a value if the current value is the same as the `old` value.
181/// `T` must be an integer or pointer type.
182///
183/// The stabilized version of this intrinsic is available on the
184/// [`atomic`] types via the `compare_exchange` method by passing
185/// [`Ordering::AcqRel`] and [`Ordering::Acquire`] as the success and failure parameters.
186/// For example, [`AtomicBool::compare_exchange`].
187#[rustc_intrinsic]
188#[rustc_nounwind]
189pub unsafe fn atomic_cxchg_acqrel_acquire<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool);
190/// Stores a value if the current value is the same as the `old` value.
191/// `T` must be an integer or pointer type.
192///
193/// The stabilized version of this intrinsic is available on the
194/// [`atomic`] types via the `compare_exchange` method by passing
195/// [`Ordering::AcqRel`] and [`Ordering::SeqCst`] as the success and failure parameters.
196/// For example, [`AtomicBool::compare_exchange`].
197#[rustc_intrinsic]
198#[rustc_nounwind]
199pub unsafe fn atomic_cxchg_acqrel_seqcst<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool);
200/// Stores a value if the current value is the same as the `old` value.
201/// `T` must be an integer or pointer type.
202///
203/// The stabilized version of this intrinsic is available on the
204/// [`atomic`] types via the `compare_exchange` method by passing
205/// [`Ordering::SeqCst`] and [`Ordering::Relaxed`] as the success and failure parameters.
206/// For example, [`AtomicBool::compare_exchange`].
207#[rustc_intrinsic]
208#[rustc_nounwind]
209pub unsafe fn atomic_cxchg_seqcst_relaxed<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool);
210/// Stores a value if the current value is the same as the `old` value.
211/// `T` must be an integer or pointer type.
212///
213/// The stabilized version of this intrinsic is available on the
214/// [`atomic`] types via the `compare_exchange` method by passing
215/// [`Ordering::SeqCst`] and [`Ordering::Acquire`] as the success and failure parameters.
216/// For example, [`AtomicBool::compare_exchange`].
217#[rustc_intrinsic]
218#[rustc_nounwind]
219pub unsafe fn atomic_cxchg_seqcst_acquire<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool);
220/// Stores a value if the current value is the same as the `old` value.
221/// `T` must be an integer or pointer type.
222///
223/// The stabilized version of this intrinsic is available on the
224/// [`atomic`] types via the `compare_exchange` method by passing
225/// [`Ordering::SeqCst`] as both the success and failure parameters.
226/// For example, [`AtomicBool::compare_exchange`].
227#[rustc_intrinsic]
228#[rustc_nounwind]
229pub unsafe fn atomic_cxchg_seqcst_seqcst<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool);
230
231/// Stores a value if the current value is the same as the `old` value.
232/// `T` must be an integer or pointer type.
233///
234/// The stabilized version of this intrinsic is available on the
235/// [`atomic`] types via the `compare_exchange_weak` method by passing
236/// [`Ordering::Relaxed`] as both the success and failure parameters.
237/// For example, [`AtomicBool::compare_exchange_weak`].
238#[rustc_intrinsic]
239#[rustc_nounwind]
240pub unsafe fn atomic_cxchgweak_relaxed_relaxed<T: Copy>(
241 _dst: *mut T,
242 _old: T,
243 _src: T,
244) -> (T, bool);
245/// Stores a value if the current value is the same as the `old` value.
246/// `T` must be an integer or pointer type.
247///
248/// The stabilized version of this intrinsic is available on the
249/// [`atomic`] types via the `compare_exchange_weak` method by passing
250/// [`Ordering::Relaxed`] and [`Ordering::Acquire`] as the success and failure parameters.
251/// For example, [`AtomicBool::compare_exchange_weak`].
252#[rustc_intrinsic]
253#[rustc_nounwind]
254pub unsafe fn atomic_cxchgweak_relaxed_acquire<T: Copy>(
255 _dst: *mut T,
256 _old: T,
257 _src: T,
258) -> (T, bool);
259/// Stores a value if the current value is the same as the `old` value.
260/// `T` must be an integer or pointer type.
261///
262/// The stabilized version of this intrinsic is available on the
263/// [`atomic`] types via the `compare_exchange_weak` method by passing
264/// [`Ordering::Relaxed`] and [`Ordering::SeqCst`] as the success and failure parameters.
265/// For example, [`AtomicBool::compare_exchange_weak`].
266#[rustc_intrinsic]
267#[rustc_nounwind]
268pub unsafe fn atomic_cxchgweak_relaxed_seqcst<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool);
269/// Stores a value if the current value is the same as the `old` value.
270/// `T` must be an integer or pointer type.
271///
272/// The stabilized version of this intrinsic is available on the
273/// [`atomic`] types via the `compare_exchange_weak` method by passing
274/// [`Ordering::Acquire`] and [`Ordering::Relaxed`] as the success and failure parameters.
275/// For example, [`AtomicBool::compare_exchange_weak`].
276#[rustc_intrinsic]
277#[rustc_nounwind]
278pub unsafe fn atomic_cxchgweak_acquire_relaxed<T: Copy>(
279 _dst: *mut T,
280 _old: T,
281 _src: T,
282) -> (T, bool);
283/// Stores a value if the current value is the same as the `old` value.
284/// `T` must be an integer or pointer type.
285///
286/// The stabilized version of this intrinsic is available on the
287/// [`atomic`] types via the `compare_exchange_weak` method by passing
288/// [`Ordering::Acquire`] as both the success and failure parameters.
289/// For example, [`AtomicBool::compare_exchange_weak`].
290#[rustc_intrinsic]
291#[rustc_nounwind]
292pub unsafe fn atomic_cxchgweak_acquire_acquire<T: Copy>(
293 _dst: *mut T,
294 _old: T,
295 _src: T,
296) -> (T, bool);
297/// Stores a value if the current value is the same as the `old` value.
298/// `T` must be an integer or pointer type.
299///
300/// The stabilized version of this intrinsic is available on the
301/// [`atomic`] types via the `compare_exchange_weak` method by passing
302/// [`Ordering::Acquire`] and [`Ordering::SeqCst`] as the success and failure parameters.
303/// For example, [`AtomicBool::compare_exchange_weak`].
304#[rustc_intrinsic]
305#[rustc_nounwind]
306pub unsafe fn atomic_cxchgweak_acquire_seqcst<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool);
307/// Stores a value if the current value is the same as the `old` value.
308/// `T` must be an integer or pointer type.
309///
310/// The stabilized version of this intrinsic is available on the
311/// [`atomic`] types via the `compare_exchange_weak` method by passing
312/// [`Ordering::Release`] and [`Ordering::Relaxed`] as the success and failure parameters.
313/// For example, [`AtomicBool::compare_exchange_weak`].
314#[rustc_intrinsic]
315#[rustc_nounwind]
316pub unsafe fn atomic_cxchgweak_release_relaxed<T: Copy>(
317 _dst: *mut T,
318 _old: T,
319 _src: T,
320) -> (T, bool);
321/// Stores a value if the current value is the same as the `old` value.
322/// `T` must be an integer or pointer type.
323///
324/// The stabilized version of this intrinsic is available on the
325/// [`atomic`] types via the `compare_exchange_weak` method by passing
326/// [`Ordering::Release`] and [`Ordering::Acquire`] as the success and failure parameters.
327/// For example, [`AtomicBool::compare_exchange_weak`].
328#[rustc_intrinsic]
329#[rustc_nounwind]
330pub unsafe fn atomic_cxchgweak_release_acquire<T: Copy>(
331 _dst: *mut T,
332 _old: T,
333 _src: T,
334) -> (T, bool);
335/// Stores a value if the current value is the same as the `old` value.
336/// `T` must be an integer or pointer type.
337///
338/// The stabilized version of this intrinsic is available on the
339/// [`atomic`] types via the `compare_exchange_weak` method by passing
340/// [`Ordering::Release`] and [`Ordering::SeqCst`] as the success and failure parameters.
341/// For example, [`AtomicBool::compare_exchange_weak`].
342#[rustc_intrinsic]
343#[rustc_nounwind]
344pub unsafe fn atomic_cxchgweak_release_seqcst<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool);
345/// Stores a value if the current value is the same as the `old` value.
346/// `T` must be an integer or pointer type.
347///
348/// The stabilized version of this intrinsic is available on the
349/// [`atomic`] types via the `compare_exchange_weak` method by passing
350/// [`Ordering::AcqRel`] and [`Ordering::Relaxed`] as the success and failure parameters.
351/// For example, [`AtomicBool::compare_exchange_weak`].
352#[rustc_intrinsic]
353#[rustc_nounwind]
354pub unsafe fn atomic_cxchgweak_acqrel_relaxed<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool);
355/// Stores a value if the current value is the same as the `old` value.
356/// `T` must be an integer or pointer type.
357///
358/// The stabilized version of this intrinsic is available on the
359/// [`atomic`] types via the `compare_exchange_weak` method by passing
360/// [`Ordering::AcqRel`] and [`Ordering::Acquire`] as the success and failure parameters.
361/// For example, [`AtomicBool::compare_exchange_weak`].
362#[rustc_intrinsic]
363#[rustc_nounwind]
364pub unsafe fn atomic_cxchgweak_acqrel_acquire<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool);
365/// Stores a value if the current value is the same as the `old` value.
366/// `T` must be an integer or pointer type.
367///
368/// The stabilized version of this intrinsic is available on the
369/// [`atomic`] types via the `compare_exchange_weak` method by passing
370/// [`Ordering::AcqRel`] and [`Ordering::SeqCst`] as the success and failure parameters.
371/// For example, [`AtomicBool::compare_exchange_weak`].
372#[rustc_intrinsic]
373#[rustc_nounwind]
374pub unsafe fn atomic_cxchgweak_acqrel_seqcst<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool);
375/// Stores a value if the current value is the same as the `old` value.
376/// `T` must be an integer or pointer type.
377///
378/// The stabilized version of this intrinsic is available on the
379/// [`atomic`] types via the `compare_exchange_weak` method by passing
380/// [`Ordering::SeqCst`] and [`Ordering::Relaxed`] as the success and failure parameters.
381/// For example, [`AtomicBool::compare_exchange_weak`].
382#[rustc_intrinsic]
383#[rustc_nounwind]
384pub unsafe fn atomic_cxchgweak_seqcst_relaxed<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool);
385/// Stores a value if the current value is the same as the `old` value.
386/// `T` must be an integer or pointer type.
387///
388/// The stabilized version of this intrinsic is available on the
389/// [`atomic`] types via the `compare_exchange_weak` method by passing
390/// [`Ordering::SeqCst`] and [`Ordering::Acquire`] as the success and failure parameters.
391/// For example, [`AtomicBool::compare_exchange_weak`].
392#[rustc_intrinsic]
393#[rustc_nounwind]
394pub unsafe fn atomic_cxchgweak_seqcst_acquire<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool);
395/// Stores a value if the current value is the same as the `old` value.
396/// `T` must be an integer or pointer type.
397///
398/// The stabilized version of this intrinsic is available on the
399/// [`atomic`] types via the `compare_exchange_weak` method by passing
400/// [`Ordering::SeqCst`] as both the success and failure parameters.
401/// For example, [`AtomicBool::compare_exchange_weak`].
402#[rustc_intrinsic]
403#[rustc_nounwind]
404pub unsafe fn atomic_cxchgweak_seqcst_seqcst<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool);
405
406/// Loads the current value of the pointer.
407/// `T` must be an integer or pointer type.
408///
409/// The stabilized version of this intrinsic is available on the
410/// [`atomic`] types via the `load` method by passing
411/// [`Ordering::SeqCst`] as the `order`. For example, [`AtomicBool::load`].
412#[rustc_intrinsic]
413#[rustc_nounwind]
414pub unsafe fn atomic_load_seqcst<T: Copy>(src: *const T) -> T;
415/// Loads the current value of the pointer.
416/// `T` must be an integer or pointer type.
417///
418/// The stabilized version of this intrinsic is available on the
419/// [`atomic`] types via the `load` method by passing
420/// [`Ordering::Acquire`] as the `order`. For example, [`AtomicBool::load`].
421#[rustc_intrinsic]
422#[rustc_nounwind]
423pub unsafe fn atomic_load_acquire<T: Copy>(src: *const T) -> T;
424/// Loads the current value of the pointer.
425/// `T` must be an integer or pointer type.
426///
427/// The stabilized version of this intrinsic is available on the
428/// [`atomic`] types via the `load` method by passing
429/// [`Ordering::Relaxed`] as the `order`. For example, [`AtomicBool::load`].
430#[rustc_intrinsic]
431#[rustc_nounwind]
432pub unsafe fn atomic_load_relaxed<T: Copy>(src: *const T) -> T;
433
434/// Stores the value at the specified memory location.
435/// `T` must be an integer or pointer type.
436///
437/// The stabilized version of this intrinsic is available on the
438/// [`atomic`] types via the `store` method by passing
439/// [`Ordering::SeqCst`] as the `order`. For example, [`AtomicBool::store`].
440#[rustc_intrinsic]
441#[rustc_nounwind]
442pub unsafe fn atomic_store_seqcst<T: Copy>(dst: *mut T, val: T);
443/// Stores the value at the specified memory location.
444/// `T` must be an integer or pointer type.
445///
446/// The stabilized version of this intrinsic is available on the
447/// [`atomic`] types via the `store` method by passing
448/// [`Ordering::Release`] as the `order`. For example, [`AtomicBool::store`].
449#[rustc_intrinsic]
450#[rustc_nounwind]
451pub unsafe fn atomic_store_release<T: Copy>(dst: *mut T, val: T);
452/// Stores the value at the specified memory location.
453/// `T` must be an integer or pointer type.
454///
455/// The stabilized version of this intrinsic is available on the
456/// [`atomic`] types via the `store` method by passing
457/// [`Ordering::Relaxed`] as the `order`. For example, [`AtomicBool::store`].
458#[rustc_intrinsic]
459#[rustc_nounwind]
460pub unsafe fn atomic_store_relaxed<T: Copy>(dst: *mut T, val: T);
461
462/// Stores the value at the specified memory location, returning the old value.
463/// `T` must be an integer or pointer type.
464///
465/// The stabilized version of this intrinsic is available on the
466/// [`atomic`] types via the `swap` method by passing
467/// [`Ordering::SeqCst`] as the `order`. For example, [`AtomicBool::swap`].
468#[rustc_intrinsic]
469#[rustc_nounwind]
470pub unsafe fn atomic_xchg_seqcst<T: Copy>(dst: *mut T, src: T) -> T;
471/// Stores the value at the specified memory location, returning the old value.
472/// `T` must be an integer or pointer type.
473///
474/// The stabilized version of this intrinsic is available on the
475/// [`atomic`] types via the `swap` method by passing
476/// [`Ordering::Acquire`] as the `order`. For example, [`AtomicBool::swap`].
477#[rustc_intrinsic]
478#[rustc_nounwind]
479pub unsafe fn atomic_xchg_acquire<T: Copy>(dst: *mut T, src: T) -> T;
480/// Stores the value at the specified memory location, returning the old value.
481/// `T` must be an integer or pointer type.
482///
483/// The stabilized version of this intrinsic is available on the
484/// [`atomic`] types via the `swap` method by passing
485/// [`Ordering::Release`] as the `order`. For example, [`AtomicBool::swap`].
486#[rustc_intrinsic]
487#[rustc_nounwind]
488pub unsafe fn atomic_xchg_release<T: Copy>(dst: *mut T, src: T) -> T;
489/// Stores the value at the specified memory location, returning the old value.
490/// `T` must be an integer or pointer type.
491///
492/// The stabilized version of this intrinsic is available on the
493/// [`atomic`] types via the `swap` method by passing
494/// [`Ordering::AcqRel`] as the `order`. For example, [`AtomicBool::swap`].
495#[rustc_intrinsic]
496#[rustc_nounwind]
497pub unsafe fn atomic_xchg_acqrel<T: Copy>(dst: *mut T, src: T) -> T;
498/// Stores the value at the specified memory location, returning the old value.
499/// `T` must be an integer or pointer type.
500///
501/// The stabilized version of this intrinsic is available on the
502/// [`atomic`] types via the `swap` method by passing
503/// [`Ordering::Relaxed`] as the `order`. For example, [`AtomicBool::swap`].
504#[rustc_intrinsic]
505#[rustc_nounwind]
506pub unsafe fn atomic_xchg_relaxed<T: Copy>(dst: *mut T, src: T) -> T;
507
508/// Adds to the current value, returning the previous value.
509/// `T` must be an integer or pointer type.
510/// If `T` is a pointer type, the provenance of `src` is ignored: both the return value and the new
511/// value stored at `*dst` will have the provenance of the old value stored there.
512///
513/// The stabilized version of this intrinsic is available on the
514/// [`atomic`] types via the `fetch_add` method by passing
515/// [`Ordering::SeqCst`] as the `order`. For example, [`AtomicIsize::fetch_add`].
516#[rustc_intrinsic]
517#[rustc_nounwind]
518pub unsafe fn atomic_xadd_seqcst<T: Copy>(dst: *mut T, src: T) -> T;
519/// Adds to the current value, returning the previous value.
520/// `T` must be an integer or pointer type.
521/// If `T` is a pointer type, the provenance of `src` is ignored: both the return value and the new
522/// value stored at `*dst` will have the provenance of the old value stored there.
523///
524/// The stabilized version of this intrinsic is available on the
525/// [`atomic`] types via the `fetch_add` method by passing
526/// [`Ordering::Acquire`] as the `order`. For example, [`AtomicIsize::fetch_add`].
527#[rustc_intrinsic]
528#[rustc_nounwind]
529pub unsafe fn atomic_xadd_acquire<T: Copy>(dst: *mut T, src: T) -> T;
530/// Adds to the current value, returning the previous value.
531/// `T` must be an integer or pointer type.
532/// If `T` is a pointer type, the provenance of `src` is ignored: both the return value and the new
533/// value stored at `*dst` will have the provenance of the old value stored there.
534///
535/// The stabilized version of this intrinsic is available on the
536/// [`atomic`] types via the `fetch_add` method by passing
537/// [`Ordering::Release`] as the `order`. For example, [`AtomicIsize::fetch_add`].
538#[rustc_intrinsic]
539#[rustc_nounwind]
540pub unsafe fn atomic_xadd_release<T: Copy>(dst: *mut T, src: T) -> T;
541/// Adds to the current value, returning the previous value.
542/// `T` must be an integer or pointer type.
543/// If `T` is a pointer type, the provenance of `src` is ignored: both the return value and the new
544/// value stored at `*dst` will have the provenance of the old value stored there.
545///
546/// The stabilized version of this intrinsic is available on the
547/// [`atomic`] types via the `fetch_add` method by passing
548/// [`Ordering::AcqRel`] as the `order`. For example, [`AtomicIsize::fetch_add`].
549#[rustc_intrinsic]
550#[rustc_nounwind]
551pub unsafe fn atomic_xadd_acqrel<T: Copy>(dst: *mut T, src: T) -> T;
552/// Adds to the current value, returning the previous value.
553/// `T` must be an integer or pointer type.
554/// If `T` is a pointer type, the provenance of `src` is ignored: both the return value and the new
555/// value stored at `*dst` will have the provenance of the old value stored there.
556///
557/// The stabilized version of this intrinsic is available on the
558/// [`atomic`] types via the `fetch_add` method by passing
559/// [`Ordering::Relaxed`] as the `order`. For example, [`AtomicIsize::fetch_add`].
560#[rustc_intrinsic]
561#[rustc_nounwind]
562pub unsafe fn atomic_xadd_relaxed<T: Copy>(dst: *mut T, src: T) -> T;
563
564/// Subtract from the current value, returning the previous value.
565/// `T` must be an integer or pointer type.
566/// If `T` is a pointer type, the provenance of `src` is ignored: both the return value and the new
567/// value stored at `*dst` will have the provenance of the old value stored there.
568///
569/// The stabilized version of this intrinsic is available on the
570/// [`atomic`] types via the `fetch_sub` method by passing
571/// [`Ordering::SeqCst`] as the `order`. For example, [`AtomicIsize::fetch_sub`].
572#[rustc_intrinsic]
573#[rustc_nounwind]
574pub unsafe fn atomic_xsub_seqcst<T: Copy>(dst: *mut T, src: T) -> T;
575/// Subtract from the current value, returning the previous value.
576/// `T` must be an integer or pointer type.
577/// If `T` is a pointer type, the provenance of `src` is ignored: both the return value and the new
578/// value stored at `*dst` will have the provenance of the old value stored there.
579///
580/// The stabilized version of this intrinsic is available on the
581/// [`atomic`] types via the `fetch_sub` method by passing
582/// [`Ordering::Acquire`] as the `order`. For example, [`AtomicIsize::fetch_sub`].
583#[rustc_intrinsic]
584#[rustc_nounwind]
585pub unsafe fn atomic_xsub_acquire<T: Copy>(dst: *mut T, src: T) -> T;
586/// Subtract from the current value, returning the previous value.
587/// `T` must be an integer or pointer type.
588/// If `T` is a pointer type, the provenance of `src` is ignored: both the return value and the new
589/// value stored at `*dst` will have the provenance of the old value stored there.
590///
591/// The stabilized version of this intrinsic is available on the
592/// [`atomic`] types via the `fetch_sub` method by passing
593/// [`Ordering::Release`] as the `order`. For example, [`AtomicIsize::fetch_sub`].
594#[rustc_intrinsic]
595#[rustc_nounwind]
596pub unsafe fn atomic_xsub_release<T: Copy>(dst: *mut T, src: T) -> T;
597/// Subtract from the current value, returning the previous value.
598/// `T` must be an integer or pointer type.
599/// If `T` is a pointer type, the provenance of `src` is ignored: both the return value and the new
600/// value stored at `*dst` will have the provenance of the old value stored there.
601///
602/// The stabilized version of this intrinsic is available on the
603/// [`atomic`] types via the `fetch_sub` method by passing
604/// [`Ordering::AcqRel`] as the `order`. For example, [`AtomicIsize::fetch_sub`].
605#[rustc_intrinsic]
606#[rustc_nounwind]
607pub unsafe fn atomic_xsub_acqrel<T: Copy>(dst: *mut T, src: T) -> T;
608/// Subtract from the current value, returning the previous value.
609/// `T` must be an integer or pointer type.
610/// If `T` is a pointer type, the provenance of `src` is ignored: both the return value and the new
611/// value stored at `*dst` will have the provenance of the old value stored there.
612///
613/// The stabilized version of this intrinsic is available on the
614/// [`atomic`] types via the `fetch_sub` method by passing
615/// [`Ordering::Relaxed`] as the `order`. For example, [`AtomicIsize::fetch_sub`].
616#[rustc_intrinsic]
617#[rustc_nounwind]
618pub unsafe fn atomic_xsub_relaxed<T: Copy>(dst: *mut T, src: T) -> T;
619
620/// Bitwise and with the current value, returning the previous value.
621/// `T` must be an integer or pointer type.
622/// If `T` is a pointer type, the provenance of `src` is ignored: both the return value and the new
623/// value stored at `*dst` will have the provenance of the old value stored there.
624///
625/// The stabilized version of this intrinsic is available on the
626/// [`atomic`] types via the `fetch_and` method by passing
627/// [`Ordering::SeqCst`] as the `order`. For example, [`AtomicBool::fetch_and`].
628#[rustc_intrinsic]
629#[rustc_nounwind]
630pub unsafe fn atomic_and_seqcst<T: Copy>(dst: *mut T, src: T) -> T;
631/// Bitwise and with the current value, returning the previous value.
632/// `T` must be an integer or pointer type.
633/// If `T` is a pointer type, the provenance of `src` is ignored: both the return value and the new
634/// value stored at `*dst` will have the provenance of the old value stored there.
635///
636/// The stabilized version of this intrinsic is available on the
637/// [`atomic`] types via the `fetch_and` method by passing
638/// [`Ordering::Acquire`] as the `order`. For example, [`AtomicBool::fetch_and`].
639#[rustc_intrinsic]
640#[rustc_nounwind]
641pub unsafe fn atomic_and_acquire<T: Copy>(dst: *mut T, src: T) -> T;
642/// Bitwise and with the current value, returning the previous value.
643/// `T` must be an integer or pointer type.
644/// If `T` is a pointer type, the provenance of `src` is ignored: both the return value and the new
645/// value stored at `*dst` will have the provenance of the old value stored there.
646///
647/// The stabilized version of this intrinsic is available on the
648/// [`atomic`] types via the `fetch_and` method by passing
649/// [`Ordering::Release`] as the `order`. For example, [`AtomicBool::fetch_and`].
650#[rustc_intrinsic]
651#[rustc_nounwind]
652pub unsafe fn atomic_and_release<T: Copy>(dst: *mut T, src: T) -> T;
653/// Bitwise and with the current value, returning the previous value.
654/// `T` must be an integer or pointer type.
655/// If `T` is a pointer type, the provenance of `src` is ignored: both the return value and the new
656/// value stored at `*dst` will have the provenance of the old value stored there.
657///
658/// The stabilized version of this intrinsic is available on the
659/// [`atomic`] types via the `fetch_and` method by passing
660/// [`Ordering::AcqRel`] as the `order`. For example, [`AtomicBool::fetch_and`].
661#[rustc_intrinsic]
662#[rustc_nounwind]
663pub unsafe fn atomic_and_acqrel<T: Copy>(dst: *mut T, src: T) -> T;
664/// Bitwise and with the current value, returning the previous value.
665/// `T` must be an integer or pointer type.
666/// If `T` is a pointer type, the provenance of `src` is ignored: both the return value and the new
667/// value stored at `*dst` will have the provenance of the old value stored there.
668///
669/// The stabilized version of this intrinsic is available on the
670/// [`atomic`] types via the `fetch_and` method by passing
671/// [`Ordering::Relaxed`] as the `order`. For example, [`AtomicBool::fetch_and`].
672#[rustc_intrinsic]
673#[rustc_nounwind]
674pub unsafe fn atomic_and_relaxed<T: Copy>(dst: *mut T, src: T) -> T;
675
676/// Bitwise nand with the current value, returning the previous value.
677/// `T` must be an integer or pointer type.
678/// If `T` is a pointer type, the provenance of `src` is ignored: both the return value and the new
679/// value stored at `*dst` will have the provenance of the old value stored there.
680///
681/// The stabilized version of this intrinsic is available on the
682/// [`AtomicBool`] type via the `fetch_nand` method by passing
683/// [`Ordering::SeqCst`] as the `order`. For example, [`AtomicBool::fetch_nand`].
684#[rustc_intrinsic]
685#[rustc_nounwind]
686pub unsafe fn atomic_nand_seqcst<T: Copy>(dst: *mut T, src: T) -> T;
687/// Bitwise nand with the current value, returning the previous value.
688/// `T` must be an integer or pointer type.
689/// If `T` is a pointer type, the provenance of `src` is ignored: both the return value and the new
690/// value stored at `*dst` will have the provenance of the old value stored there.
691///
692/// The stabilized version of this intrinsic is available on the
693/// [`AtomicBool`] type via the `fetch_nand` method by passing
694/// [`Ordering::Acquire`] as the `order`. For example, [`AtomicBool::fetch_nand`].
695#[rustc_intrinsic]
696#[rustc_nounwind]
697pub unsafe fn atomic_nand_acquire<T: Copy>(dst: *mut T, src: T) -> T;
698/// Bitwise nand with the current value, returning the previous value.
699/// `T` must be an integer or pointer type.
700/// If `T` is a pointer type, the provenance of `src` is ignored: both the return value and the new
701/// value stored at `*dst` will have the provenance of the old value stored there.
702///
703/// The stabilized version of this intrinsic is available on the
704/// [`AtomicBool`] type via the `fetch_nand` method by passing
705/// [`Ordering::Release`] as the `order`. For example, [`AtomicBool::fetch_nand`].
706#[rustc_intrinsic]
707#[rustc_nounwind]
708pub unsafe fn atomic_nand_release<T: Copy>(dst: *mut T, src: T) -> T;
709/// Bitwise nand with the current value, returning the previous value.
710/// `T` must be an integer or pointer type.
711/// If `T` is a pointer type, the provenance of `src` is ignored: both the return value and the new
712/// value stored at `*dst` will have the provenance of the old value stored there.
713///
714/// The stabilized version of this intrinsic is available on the
715/// [`AtomicBool`] type via the `fetch_nand` method by passing
716/// [`Ordering::AcqRel`] as the `order`. For example, [`AtomicBool::fetch_nand`].
717#[rustc_intrinsic]
718#[rustc_nounwind]
719pub unsafe fn atomic_nand_acqrel<T: Copy>(dst: *mut T, src: T) -> T;
720/// Bitwise nand with the current value, returning the previous value.
721/// `T` must be an integer or pointer type.
722/// If `T` is a pointer type, the provenance of `src` is ignored: both the return value and the new
723/// value stored at `*dst` will have the provenance of the old value stored there.
724///
725/// The stabilized version of this intrinsic is available on the
726/// [`AtomicBool`] type via the `fetch_nand` method by passing
727/// [`Ordering::Relaxed`] as the `order`. For example, [`AtomicBool::fetch_nand`].
728#[rustc_intrinsic]
729#[rustc_nounwind]
730pub unsafe fn atomic_nand_relaxed<T: Copy>(dst: *mut T, src: T) -> T;
731
732/// Bitwise or with the current value, returning the previous value.
733/// `T` must be an integer or pointer type.
734/// If `T` is a pointer type, the provenance of `src` is ignored: both the return value and the new
735/// value stored at `*dst` will have the provenance of the old value stored there.
736///
737/// The stabilized version of this intrinsic is available on the
738/// [`atomic`] types via the `fetch_or` method by passing
739/// [`Ordering::SeqCst`] as the `order`. For example, [`AtomicBool::fetch_or`].
740#[rustc_intrinsic]
741#[rustc_nounwind]
742pub unsafe fn atomic_or_seqcst<T: Copy>(dst: *mut T, src: T) -> T;
743/// Bitwise or with the current value, returning the previous value.
744/// `T` must be an integer or pointer type.
745/// If `T` is a pointer type, the provenance of `src` is ignored: both the return value and the new
746/// value stored at `*dst` will have the provenance of the old value stored there.
747///
748/// The stabilized version of this intrinsic is available on the
749/// [`atomic`] types via the `fetch_or` method by passing
750/// [`Ordering::Acquire`] as the `order`. For example, [`AtomicBool::fetch_or`].
751#[rustc_intrinsic]
752#[rustc_nounwind]
753pub unsafe fn atomic_or_acquire<T: Copy>(dst: *mut T, src: T) -> T;
754/// Bitwise or with the current value, returning the previous value.
755/// `T` must be an integer or pointer type.
756/// If `T` is a pointer type, the provenance of `src` is ignored: both the return value and the new
757/// value stored at `*dst` will have the provenance of the old value stored there.
758///
759/// The stabilized version of this intrinsic is available on the
760/// [`atomic`] types via the `fetch_or` method by passing
761/// [`Ordering::Release`] as the `order`. For example, [`AtomicBool::fetch_or`].
762#[rustc_intrinsic]
763#[rustc_nounwind]
764pub unsafe fn atomic_or_release<T: Copy>(dst: *mut T, src: T) -> T;
765/// Bitwise or with the current value, returning the previous value.
766/// `T` must be an integer or pointer type.
767/// If `T` is a pointer type, the provenance of `src` is ignored: both the return value and the new
768/// value stored at `*dst` will have the provenance of the old value stored there.
769///
770/// The stabilized version of this intrinsic is available on the
771/// [`atomic`] types via the `fetch_or` method by passing
772/// [`Ordering::AcqRel`] as the `order`. For example, [`AtomicBool::fetch_or`].
773#[rustc_intrinsic]
774#[rustc_nounwind]
775pub unsafe fn atomic_or_acqrel<T: Copy>(dst: *mut T, src: T) -> T;
776/// Bitwise or with the current value, returning the previous value.
777/// `T` must be an integer or pointer type.
778/// If `T` is a pointer type, the provenance of `src` is ignored: both the return value and the new
779/// value stored at `*dst` will have the provenance of the old value stored there.
780///
781/// The stabilized version of this intrinsic is available on the
782/// [`atomic`] types via the `fetch_or` method by passing
783/// [`Ordering::Relaxed`] as the `order`. For example, [`AtomicBool::fetch_or`].
784#[rustc_intrinsic]
785#[rustc_nounwind]
786pub unsafe fn atomic_or_relaxed<T: Copy>(dst: *mut T, src: T) -> T;
787
788/// Bitwise xor with the current value, returning the previous value.
789/// `T` must be an integer or pointer type.
790/// If `T` is a pointer type, the provenance of `src` is ignored: both the return value and the new
791/// value stored at `*dst` will have the provenance of the old value stored there.
792///
793/// The stabilized version of this intrinsic is available on the
794/// [`atomic`] types via the `fetch_xor` method by passing
795/// [`Ordering::SeqCst`] as the `order`. For example, [`AtomicBool::fetch_xor`].
796#[rustc_intrinsic]
797#[rustc_nounwind]
798pub unsafe fn atomic_xor_seqcst<T: Copy>(dst: *mut T, src: T) -> T;
799/// Bitwise xor with the current value, returning the previous value.
800/// `T` must be an integer or pointer type.
801/// If `T` is a pointer type, the provenance of `src` is ignored: both the return value and the new
802/// value stored at `*dst` will have the provenance of the old value stored there.
803///
804/// The stabilized version of this intrinsic is available on the
805/// [`atomic`] types via the `fetch_xor` method by passing
806/// [`Ordering::Acquire`] as the `order`. For example, [`AtomicBool::fetch_xor`].
807#[rustc_intrinsic]
808#[rustc_nounwind]
809pub unsafe fn atomic_xor_acquire<T: Copy>(dst: *mut T, src: T) -> T;
810/// Bitwise xor with the current value, returning the previous value.
811/// `T` must be an integer or pointer type.
812/// If `T` is a pointer type, the provenance of `src` is ignored: both the return value and the new
813/// value stored at `*dst` will have the provenance of the old value stored there.
814///
815/// The stabilized version of this intrinsic is available on the
816/// [`atomic`] types via the `fetch_xor` method by passing
817/// [`Ordering::Release`] as the `order`. For example, [`AtomicBool::fetch_xor`].
818#[rustc_intrinsic]
819#[rustc_nounwind]
820pub unsafe fn atomic_xor_release<T: Copy>(dst: *mut T, src: T) -> T;
821/// Bitwise xor with the current value, returning the previous value.
822/// `T` must be an integer or pointer type.
823/// If `T` is a pointer type, the provenance of `src` is ignored: both the return value and the new
824/// value stored at `*dst` will have the provenance of the old value stored there.
825///
826/// The stabilized version of this intrinsic is available on the
827/// [`atomic`] types via the `fetch_xor` method by passing
828/// [`Ordering::AcqRel`] as the `order`. For example, [`AtomicBool::fetch_xor`].
829#[rustc_intrinsic]
830#[rustc_nounwind]
831pub unsafe fn atomic_xor_acqrel<T: Copy>(dst: *mut T, src: T) -> T;
832/// Bitwise xor with the current value, returning the previous value.
833/// `T` must be an integer or pointer type.
834/// If `T` is a pointer type, the provenance of `src` is ignored: both the return value and the new
835/// value stored at `*dst` will have the provenance of the old value stored there.
836///
837/// The stabilized version of this intrinsic is available on the
838/// [`atomic`] types via the `fetch_xor` method by passing
839/// [`Ordering::Relaxed`] as the `order`. For example, [`AtomicBool::fetch_xor`].
840#[rustc_intrinsic]
841#[rustc_nounwind]
842pub unsafe fn atomic_xor_relaxed<T: Copy>(dst: *mut T, src: T) -> T;
843
844/// Maximum with the current value using a signed comparison.
845/// `T` must be a signed integer type.
846///
847/// The stabilized version of this intrinsic is available on the
848/// [`atomic`] signed integer types via the `fetch_max` method by passing
849/// [`Ordering::SeqCst`] as the `order`. For example, [`AtomicI32::fetch_max`].
850#[rustc_intrinsic]
851#[rustc_nounwind]
852pub unsafe fn atomic_max_seqcst<T: Copy>(dst: *mut T, src: T) -> T;
853/// Maximum with the current value using a signed comparison.
854/// `T` must be a signed integer type.
855///
856/// The stabilized version of this intrinsic is available on the
857/// [`atomic`] signed integer types via the `fetch_max` method by passing
858/// [`Ordering::Acquire`] as the `order`. For example, [`AtomicI32::fetch_max`].
859#[rustc_intrinsic]
860#[rustc_nounwind]
861pub unsafe fn atomic_max_acquire<T: Copy>(dst: *mut T, src: T) -> T;
862/// Maximum with the current value using a signed comparison.
863/// `T` must be a signed integer type.
864///
865/// The stabilized version of this intrinsic is available on the
866/// [`atomic`] signed integer types via the `fetch_max` method by passing
867/// [`Ordering::Release`] as the `order`. For example, [`AtomicI32::fetch_max`].
868#[rustc_intrinsic]
869#[rustc_nounwind]
870pub unsafe fn atomic_max_release<T: Copy>(dst: *mut T, src: T) -> T;
871/// Maximum with the current value using a signed comparison.
872/// `T` must be a signed integer type.
873///
874/// The stabilized version of this intrinsic is available on the
875/// [`atomic`] signed integer types via the `fetch_max` method by passing
876/// [`Ordering::AcqRel`] as the `order`. For example, [`AtomicI32::fetch_max`].
877#[rustc_intrinsic]
878#[rustc_nounwind]
879pub unsafe fn atomic_max_acqrel<T: Copy>(dst: *mut T, src: T) -> T;
880/// Maximum with the current value using a signed comparison.
881/// `T` must be a signed integer type.
882///
883/// The stabilized version of this intrinsic is available on the
884/// [`atomic`] signed integer types via the `fetch_max` method by passing
885/// [`Ordering::Relaxed`] as the `order`. For example, [`AtomicI32::fetch_max`].
886#[rustc_intrinsic]
887#[rustc_nounwind]
888pub unsafe fn atomic_max_relaxed<T: Copy>(dst: *mut T, src: T) -> T;
889
890/// Minimum with the current value using a signed comparison.
891/// `T` must be a signed integer type.
892///
893/// The stabilized version of this intrinsic is available on the
894/// [`atomic`] signed integer types via the `fetch_min` method by passing
895/// [`Ordering::SeqCst`] as the `order`. For example, [`AtomicI32::fetch_min`].
896#[rustc_intrinsic]
897#[rustc_nounwind]
898pub unsafe fn atomic_min_seqcst<T: Copy>(dst: *mut T, src: T) -> T;
899/// Minimum with the current value using a signed comparison.
900/// `T` must be a signed integer type.
901///
902/// The stabilized version of this intrinsic is available on the
903/// [`atomic`] signed integer types via the `fetch_min` method by passing
904/// [`Ordering::Acquire`] as the `order`. For example, [`AtomicI32::fetch_min`].
905#[rustc_intrinsic]
906#[rustc_nounwind]
907pub unsafe fn atomic_min_acquire<T: Copy>(dst: *mut T, src: T) -> T;
908/// Minimum with the current value using a signed comparison.
909/// `T` must be a signed integer type.
910///
911/// The stabilized version of this intrinsic is available on the
912/// [`atomic`] signed integer types via the `fetch_min` method by passing
913/// [`Ordering::Release`] as the `order`. For example, [`AtomicI32::fetch_min`].
914#[rustc_intrinsic]
915#[rustc_nounwind]
916pub unsafe fn atomic_min_release<T: Copy>(dst: *mut T, src: T) -> T;
917/// Minimum with the current value using a signed comparison.
918/// `T` must be a signed integer type.
919///
920/// The stabilized version of this intrinsic is available on the
921/// [`atomic`] signed integer types via the `fetch_min` method by passing
922/// [`Ordering::AcqRel`] as the `order`. For example, [`AtomicI32::fetch_min`].
923#[rustc_intrinsic]
924#[rustc_nounwind]
925pub unsafe fn atomic_min_acqrel<T: Copy>(dst: *mut T, src: T) -> T;
926/// Minimum with the current value using a signed comparison.
927/// `T` must be a signed integer type.
928///
929/// The stabilized version of this intrinsic is available on the
930/// [`atomic`] signed integer types via the `fetch_min` method by passing
931/// [`Ordering::Relaxed`] as the `order`. For example, [`AtomicI32::fetch_min`].
932#[rustc_intrinsic]
933#[rustc_nounwind]
934pub unsafe fn atomic_min_relaxed<T: Copy>(dst: *mut T, src: T) -> T;
935
936/// Minimum with the current value using an unsigned comparison.
937/// `T` must be an unsigned integer type.
938///
939/// The stabilized version of this intrinsic is available on the
940/// [`atomic`] unsigned integer types via the `fetch_min` method by passing
941/// [`Ordering::SeqCst`] as the `order`. For example, [`AtomicU32::fetch_min`].
942#[rustc_intrinsic]
943#[rustc_nounwind]
944pub unsafe fn atomic_umin_seqcst<T: Copy>(dst: *mut T, src: T) -> T;
945/// Minimum with the current value using an unsigned comparison.
946/// `T` must be an unsigned integer type.
947///
948/// The stabilized version of this intrinsic is available on the
949/// [`atomic`] unsigned integer types via the `fetch_min` method by passing
950/// [`Ordering::Acquire`] as the `order`. For example, [`AtomicU32::fetch_min`].
951#[rustc_intrinsic]
952#[rustc_nounwind]
953pub unsafe fn atomic_umin_acquire<T: Copy>(dst: *mut T, src: T) -> T;
954/// Minimum with the current value using an unsigned comparison.
955/// `T` must be an unsigned integer type.
956///
957/// The stabilized version of this intrinsic is available on the
958/// [`atomic`] unsigned integer types via the `fetch_min` method by passing
959/// [`Ordering::Release`] as the `order`. For example, [`AtomicU32::fetch_min`].
960#[rustc_intrinsic]
961#[rustc_nounwind]
962pub unsafe fn atomic_umin_release<T: Copy>(dst: *mut T, src: T) -> T;
963/// Minimum with the current value using an unsigned comparison.
964/// `T` must be an unsigned integer type.
965///
966/// The stabilized version of this intrinsic is available on the
967/// [`atomic`] unsigned integer types via the `fetch_min` method by passing
968/// [`Ordering::AcqRel`] as the `order`. For example, [`AtomicU32::fetch_min`].
969#[rustc_intrinsic]
970#[rustc_nounwind]
971pub unsafe fn atomic_umin_acqrel<T: Copy>(dst: *mut T, src: T) -> T;
972/// Minimum with the current value using an unsigned comparison.
973/// `T` must be an unsigned integer type.
974///
975/// The stabilized version of this intrinsic is available on the
976/// [`atomic`] unsigned integer types via the `fetch_min` method by passing
977/// [`Ordering::Relaxed`] as the `order`. For example, [`AtomicU32::fetch_min`].
978#[rustc_intrinsic]
979#[rustc_nounwind]
980pub unsafe fn atomic_umin_relaxed<T: Copy>(dst: *mut T, src: T) -> T;
981
982/// Maximum with the current value using an unsigned comparison.
983/// `T` must be an unsigned integer type.
984///
985/// The stabilized version of this intrinsic is available on the
986/// [`atomic`] unsigned integer types via the `fetch_max` method by passing
987/// [`Ordering::SeqCst`] as the `order`. For example, [`AtomicU32::fetch_max`].
988#[rustc_intrinsic]
989#[rustc_nounwind]
990pub unsafe fn atomic_umax_seqcst<T: Copy>(dst: *mut T, src: T) -> T;
991/// Maximum with the current value using an unsigned comparison.
992/// `T` must be an unsigned integer type.
993///
994/// The stabilized version of this intrinsic is available on the
995/// [`atomic`] unsigned integer types via the `fetch_max` method by passing
996/// [`Ordering::Acquire`] as the `order`. For example, [`AtomicU32::fetch_max`].
997#[rustc_intrinsic]
998#[rustc_nounwind]
999pub unsafe fn atomic_umax_acquire<T: Copy>(dst: *mut T, src: T) -> T;
1000/// Maximum with the current value using an unsigned comparison.
1001/// `T` must be an unsigned integer type.
1002///
1003/// The stabilized version of this intrinsic is available on the
1004/// [`atomic`] unsigned integer types via the `fetch_max` method by passing
1005/// [`Ordering::Release`] as the `order`. For example, [`AtomicU32::fetch_max`].
1006#[rustc_intrinsic]
1007#[rustc_nounwind]
1008pub unsafe fn atomic_umax_release<T: Copy>(dst: *mut T, src: T) -> T;
1009/// Maximum with the current value using an unsigned comparison.
1010/// `T` must be an unsigned integer type.
1011///
1012/// The stabilized version of this intrinsic is available on the
1013/// [`atomic`] unsigned integer types via the `fetch_max` method by passing
1014/// [`Ordering::AcqRel`] as the `order`. For example, [`AtomicU32::fetch_max`].
1015#[rustc_intrinsic]
1016#[rustc_nounwind]
1017pub unsafe fn atomic_umax_acqrel<T: Copy>(dst: *mut T, src: T) -> T;
1018/// Maximum with the current value using an unsigned comparison.
1019/// `T` must be an unsigned integer type.
1020///
1021/// The stabilized version of this intrinsic is available on the
1022/// [`atomic`] unsigned integer types via the `fetch_max` method by passing
1023/// [`Ordering::Relaxed`] as the `order`. For example, [`AtomicU32::fetch_max`].
1024#[rustc_intrinsic]
1025#[rustc_nounwind]
1026pub unsafe fn atomic_umax_relaxed<T: Copy>(dst: *mut T, src: T) -> T;
1027
1028/// An atomic fence.
1029///
1030/// The stabilized version of this intrinsic is available in
1031/// [`atomic::fence`] by passing [`Ordering::SeqCst`]
1032/// as the `order`.
1033#[rustc_intrinsic]
1034#[rustc_nounwind]
1035pub unsafe fn atomic_fence_seqcst();
1036/// An atomic fence.
1037///
1038/// The stabilized version of this intrinsic is available in
1039/// [`atomic::fence`] by passing [`Ordering::Acquire`]
1040/// as the `order`.
1041#[rustc_intrinsic]
1042#[rustc_nounwind]
1043pub unsafe fn atomic_fence_acquire();
1044/// An atomic fence.
1045///
1046/// The stabilized version of this intrinsic is available in
1047/// [`atomic::fence`] by passing [`Ordering::Release`]
1048/// as the `order`.
1049#[rustc_intrinsic]
1050#[rustc_nounwind]
1051pub unsafe fn atomic_fence_release();
1052/// An atomic fence.
1053///
1054/// The stabilized version of this intrinsic is available in
1055/// [`atomic::fence`] by passing [`Ordering::AcqRel`]
1056/// as the `order`.
1057#[rustc_intrinsic]
1058#[rustc_nounwind]
1059pub unsafe fn atomic_fence_acqrel();
1060
1061/// A compiler-only memory barrier.
1062///
1063/// Memory accesses will never be reordered across this barrier by the
1064/// compiler, but no instructions will be emitted for it. This is
1065/// appropriate for operations on the same thread that may be preempted,
1066/// such as when interacting with signal handlers.
1067///
1068/// The stabilized version of this intrinsic is available in
1069/// [`atomic::compiler_fence`] by passing [`Ordering::SeqCst`]
1070/// as the `order`.
1071#[rustc_intrinsic]
1072#[rustc_nounwind]
1073pub unsafe fn atomic_singlethreadfence_seqcst();
1074/// A compiler-only memory barrier.
1075///
1076/// Memory accesses will never be reordered across this barrier by the
1077/// compiler, but no instructions will be emitted for it. This is
1078/// appropriate for operations on the same thread that may be preempted,
1079/// such as when interacting with signal handlers.
1080///
1081/// The stabilized version of this intrinsic is available in
1082/// [`atomic::compiler_fence`] by passing [`Ordering::Acquire`]
1083/// as the `order`.
1084#[rustc_intrinsic]
1085#[rustc_nounwind]
1086pub unsafe fn atomic_singlethreadfence_acquire();
1087/// A compiler-only memory barrier.
1088///
1089/// Memory accesses will never be reordered across this barrier by the
1090/// compiler, but no instructions will be emitted for it. This is
1091/// appropriate for operations on the same thread that may be preempted,
1092/// such as when interacting with signal handlers.
1093///
1094/// The stabilized version of this intrinsic is available in
1095/// [`atomic::compiler_fence`] by passing [`Ordering::Release`]
1096/// as the `order`.
1097#[rustc_intrinsic]
1098#[rustc_nounwind]
1099pub unsafe fn atomic_singlethreadfence_release();
1100/// A compiler-only memory barrier.
1101///
1102/// Memory accesses will never be reordered across this barrier by the
1103/// compiler, but no instructions will be emitted for it. This is
1104/// appropriate for operations on the same thread that may be preempted,
1105/// such as when interacting with signal handlers.
1106///
1107/// The stabilized version of this intrinsic is available in
1108/// [`atomic::compiler_fence`] by passing [`Ordering::AcqRel`]
1109/// as the `order`.
1110#[rustc_intrinsic]
1111#[rustc_nounwind]
1112pub unsafe fn atomic_singlethreadfence_acqrel();
1113
1114/// The `prefetch` intrinsic is a hint to the code generator to insert a prefetch instruction
1115/// if supported; otherwise, it is a no-op.
1116/// Prefetches have no effect on the behavior of the program but can change its performance
1117/// characteristics.
1118///
1119/// The `locality` argument must be a constant integer and is a temporal locality specifier
1120/// ranging from (0) - no locality, to (3) - extremely local keep in cache.
1121///
1122/// This intrinsic does not have a stable counterpart.
1123#[rustc_intrinsic]
1124#[rustc_nounwind]
1125pub unsafe fn prefetch_read_data<T>(data: *const T, locality: i32);
1126/// The `prefetch` intrinsic is a hint to the code generator to insert a prefetch instruction
1127/// if supported; otherwise, it is a no-op.
1128/// Prefetches have no effect on the behavior of the program but can change its performance
1129/// characteristics.
1130///
1131/// The `locality` argument must be a constant integer and is a temporal locality specifier
1132/// ranging from (0) - no locality, to (3) - extremely local keep in cache.
1133///
1134/// This intrinsic does not have a stable counterpart.
1135#[rustc_intrinsic]
1136#[rustc_nounwind]
1137pub unsafe fn prefetch_write_data<T>(data: *const T, locality: i32);
1138/// The `prefetch` intrinsic is a hint to the code generator to insert a prefetch instruction
1139/// if supported; otherwise, it is a no-op.
1140/// Prefetches have no effect on the behavior of the program but can change its performance
1141/// characteristics.
1142///
1143/// The `locality` argument must be a constant integer and is a temporal locality specifier
1144/// ranging from (0) - no locality, to (3) - extremely local keep in cache.
1145///
1146/// This intrinsic does not have a stable counterpart.
1147#[rustc_intrinsic]
1148#[rustc_nounwind]
1149pub unsafe fn prefetch_read_instruction<T>(data: *const T, locality: i32);
1150/// The `prefetch` intrinsic is a hint to the code generator to insert a prefetch instruction
1151/// if supported; otherwise, it is a no-op.
1152/// Prefetches have no effect on the behavior of the program but can change its performance
1153/// characteristics.
1154///
1155/// The `locality` argument must be a constant integer and is a temporal locality specifier
1156/// ranging from (0) - no locality, to (3) - extremely local keep in cache.
1157///
1158/// This intrinsic does not have a stable counterpart.
1159#[rustc_intrinsic]
1160#[rustc_nounwind]
1161pub unsafe fn prefetch_write_instruction<T>(data: *const T, locality: i32);
1162
1163/// Executes a breakpoint trap, for inspection by a debugger.
1164///
1165/// This intrinsic does not have a stable counterpart.
1166#[rustc_intrinsic]
1167#[rustc_nounwind]
1168pub fn breakpoint();
1169
1170/// Magic intrinsic that derives its meaning from attributes
1171/// attached to the function.
1172///
1173/// For example, dataflow uses this to inject static assertions so
1174/// that `rustc_peek(potentially_uninitialized)` would actually
1175/// double-check that dataflow did indeed compute that it is
1176/// uninitialized at that point in the control flow.
1177///
1178/// This intrinsic should not be used outside of the compiler.
1179#[rustc_nounwind]
1180#[rustc_intrinsic]
1181pub fn rustc_peek<T>(_: T) -> T;
1182
1183/// Aborts the execution of the process.
1184///
1185/// Note that, unlike most intrinsics, this is safe to call;
1186/// it does not require an `unsafe` block.
1187/// Therefore, implementations must not require the user to uphold
1188/// any safety invariants.
1189///
1190/// [`std::process::abort`](../../std/process/fn.abort.html) is to be preferred if possible,
1191/// as its behavior is more user-friendly and more stable.
1192///
1193/// The current implementation of `intrinsics::abort` is to invoke an invalid instruction,
1194/// on most platforms.
1195/// On Unix, the
1196/// process will probably terminate with a signal like `SIGABRT`, `SIGILL`, `SIGTRAP`, `SIGSEGV` or
1197/// `SIGBUS`. The precise behavior is not guaranteed and not stable.
1198#[rustc_nounwind]
1199#[rustc_intrinsic]
1200pub fn abort() -> !;
1201
1202/// Informs the optimizer that this point in the code is not reachable,
1203/// enabling further optimizations.
1204///
1205/// N.B., this is very different from the `unreachable!()` macro: Unlike the
1206/// macro, which panics when it is executed, it is *undefined behavior* to
1207/// reach code marked with this function.
1208///
1209/// The stabilized version of this intrinsic is [`core::hint::unreachable_unchecked`].
1210#[rustc_intrinsic_const_stable_indirect]
1211#[rustc_nounwind]
1212#[rustc_intrinsic]
1213pub const unsafe fn unreachable() -> !;
1214
1215/// Informs the optimizer that a condition is always true.
1216/// If the condition is false, the behavior is undefined.
1217///
1218/// No code is generated for this intrinsic, but the optimizer will try
1219/// to preserve it (and its condition) between passes, which may interfere
1220/// with optimization of surrounding code and reduce performance. It should
1221/// not be used if the invariant can be discovered by the optimizer on its
1222/// own, or if it does not enable any significant optimizations.
1223///
1224/// The stabilized version of this intrinsic is [`core::hint::assert_unchecked`].
1225#[rustc_intrinsic_const_stable_indirect]
1226#[rustc_nounwind]
1227#[unstable(feature = "core_intrinsics", issue = "none")]
1228#[rustc_intrinsic]
1229pub const unsafe fn assume(b: bool) {
1230 if !b {
1231 // SAFETY: the caller must guarantee the argument is never `false`
1232 unsafe { unreachable() }
1233 }
1234}
1235
1236/// Hints to the compiler that current code path is cold.
1237///
1238/// Note that, unlike most intrinsics, this is safe to call;
1239/// it does not require an `unsafe` block.
1240/// Therefore, implementations must not require the user to uphold
1241/// any safety invariants.
1242///
1243/// This intrinsic does not have a stable counterpart.
1244#[unstable(feature = "core_intrinsics", issue = "none")]
1245#[rustc_intrinsic]
1246#[rustc_nounwind]
1247#[miri::intrinsic_fallback_is_spec]
1248#[cold]
1249pub const fn cold_path() {}
1250
1251/// Hints to the compiler that branch condition is likely to be true.
1252/// Returns the value passed to it.
1253///
1254/// Any use other than with `if` statements will probably not have an effect.
1255///
1256/// Note that, unlike most intrinsics, this is safe to call;
1257/// it does not require an `unsafe` block.
1258/// Therefore, implementations must not require the user to uphold
1259/// any safety invariants.
1260///
1261/// This intrinsic does not have a stable counterpart.
1262#[unstable(feature = "core_intrinsics", issue = "none")]
1263#[rustc_nounwind]
1264#[inline(always)]
1265pub const fn likely(b: bool) -> bool {
1266 if b {
1267 true
1268 } else {
1269 cold_path();
1270 false
1271 }
1272}
1273
1274/// Hints to the compiler that branch condition is likely to be false.
1275/// Returns the value passed to it.
1276///
1277/// Any use other than with `if` statements will probably not have an effect.
1278///
1279/// Note that, unlike most intrinsics, this is safe to call;
1280/// it does not require an `unsafe` block.
1281/// Therefore, implementations must not require the user to uphold
1282/// any safety invariants.
1283///
1284/// This intrinsic does not have a stable counterpart.
1285#[unstable(feature = "core_intrinsics", issue = "none")]
1286#[rustc_nounwind]
1287#[inline(always)]
1288pub const fn unlikely(b: bool) -> bool {
1289 if b {
1290 cold_path();
1291 true
1292 } else {
1293 false
1294 }
1295}
1296
1297/// Returns either `true_val` or `false_val` depending on condition `b` with a
1298/// hint to the compiler that this condition is unlikely to be correctly
1299/// predicted by a CPU's branch predictor (e.g. a binary search).
1300///
1301/// This is otherwise functionally equivalent to `if b { true_val } else { false_val }`.
1302///
1303/// Note that, unlike most intrinsics, this is safe to call;
1304/// it does not require an `unsafe` block.
1305/// Therefore, implementations must not require the user to uphold
1306/// any safety invariants.
1307///
1308/// The public form of this instrinsic is [`core::hint::select_unpredictable`].
1309/// However unlike the public form, the intrinsic will not drop the value that
1310/// is not selected.
1311#[unstable(feature = "core_intrinsics", issue = "none")]
1312#[rustc_intrinsic]
1313#[rustc_nounwind]
1314#[miri::intrinsic_fallback_is_spec]
1315#[inline]
1316pub fn select_unpredictable<T>(b: bool, true_val: T, false_val: T) -> T {
1317 if b { true_val } else { false_val }
1318}
1319
1320/// A guard for unsafe functions that cannot ever be executed if `T` is uninhabited:
1321/// This will statically either panic, or do nothing.
1322///
1323/// This intrinsic does not have a stable counterpart.
1324#[rustc_intrinsic_const_stable_indirect]
1325#[rustc_nounwind]
1326#[rustc_intrinsic]
1327pub const fn assert_inhabited<T>();
1328
1329/// A guard for unsafe functions that cannot ever be executed if `T` does not permit
1330/// zero-initialization: This will statically either panic, or do nothing.
1331///
1332/// This intrinsic does not have a stable counterpart.
1333#[rustc_intrinsic_const_stable_indirect]
1334#[rustc_nounwind]
1335#[rustc_intrinsic]
1336pub const fn assert_zero_valid<T>();
1337
1338/// A guard for `std::mem::uninitialized`. This will statically either panic, or do nothing.
1339///
1340/// This intrinsic does not have a stable counterpart.
1341#[rustc_intrinsic_const_stable_indirect]
1342#[rustc_nounwind]
1343#[rustc_intrinsic]
1344pub const fn assert_mem_uninitialized_valid<T>();
1345
1346/// Gets a reference to a static `Location` indicating where it was called.
1347///
1348/// Note that, unlike most intrinsics, this is safe to call;
1349/// it does not require an `unsafe` block.
1350/// Therefore, implementations must not require the user to uphold
1351/// any safety invariants.
1352///
1353/// Consider using [`core::panic::Location::caller`] instead.
1354#[rustc_intrinsic_const_stable_indirect]
1355#[rustc_nounwind]
1356#[rustc_intrinsic]
1357pub const fn caller_location() -> &'static crate::panic::Location<'static>;
1358
1359/// Moves a value out of scope without running drop glue.
1360///
1361/// This exists solely for [`crate::mem::forget_unsized`]; normal `forget` uses
1362/// `ManuallyDrop` instead.
1363///
1364/// Note that, unlike most intrinsics, this is safe to call;
1365/// it does not require an `unsafe` block.
1366/// Therefore, implementations must not require the user to uphold
1367/// any safety invariants.
1368#[rustc_intrinsic_const_stable_indirect]
1369#[rustc_nounwind]
1370#[rustc_intrinsic]
1371pub const fn forget<T: ?Sized>(_: T);
1372
1373/// Reinterprets the bits of a value of one type as another type.
1374///
1375/// Both types must have the same size. Compilation will fail if this is not guaranteed.
1376///
1377/// `transmute` is semantically equivalent to a bitwise move of one type
1378/// into another. It copies the bits from the source value into the
1379/// destination value, then forgets the original. Note that source and destination
1380/// are passed by-value, which means if `Src` or `Dst` contain padding, that padding
1381/// is *not* guaranteed to be preserved by `transmute`.
1382///
1383/// Both the argument and the result must be [valid](../../nomicon/what-unsafe-does.html) at
1384/// their given type. Violating this condition leads to [undefined behavior][ub]. The compiler
1385/// will generate code *assuming that you, the programmer, ensure that there will never be
1386/// undefined behavior*. It is therefore your responsibility to guarantee that every value
1387/// passed to `transmute` is valid at both types `Src` and `Dst`. Failing to uphold this condition
1388/// may lead to unexpected and unstable compilation results. This makes `transmute` **incredibly
1389/// unsafe**. `transmute` should be the absolute last resort.
1390///
1391/// Because `transmute` is a by-value operation, alignment of the *transmuted values
1392/// themselves* is not a concern. As with any other function, the compiler already ensures
1393/// both `Src` and `Dst` are properly aligned. However, when transmuting values that *point
1394/// elsewhere* (such as pointers, references, boxes…), the caller has to ensure proper
1395/// alignment of the pointed-to values.
1396///
1397/// The [nomicon](../../nomicon/transmutes.html) has additional documentation.
1398///
1399/// [ub]: ../../reference/behavior-considered-undefined.html
1400///
1401/// # Transmutation between pointers and integers
1402///
1403/// Special care has to be taken when transmuting between pointers and integers, e.g.
1404/// transmuting between `*const ()` and `usize`.
1405///
1406/// Transmuting *pointers to integers* in a `const` context is [undefined behavior][ub], unless
1407/// the pointer was originally created *from* an integer. (That includes this function
1408/// specifically, integer-to-pointer casts, and helpers like [`dangling`][crate::ptr::dangling],
1409/// but also semantically-equivalent conversions such as punning through `repr(C)` union
1410/// fields.) Any attempt to use the resulting value for integer operations will abort
1411/// const-evaluation. (And even outside `const`, such transmutation is touching on many
1412/// unspecified aspects of the Rust memory model and should be avoided. See below for
1413/// alternatives.)
1414///
1415/// Transmuting *integers to pointers* is a largely unspecified operation. It is likely *not*
1416/// equivalent to an `as` cast. Doing non-zero-sized memory accesses with a pointer constructed
1417/// this way is currently considered undefined behavior.
1418///
1419/// All this also applies when the integer is nested inside an array, tuple, struct, or enum.
1420/// However, `MaybeUninit<usize>` is not considered an integer type for the purpose of this
1421/// section. Transmuting `*const ()` to `MaybeUninit<usize>` is fine---but then calling
1422/// `assume_init()` on that result is considered as completing the pointer-to-integer transmute
1423/// and thus runs into the issues discussed above.
1424///
1425/// In particular, doing a pointer-to-integer-to-pointer roundtrip via `transmute` is *not* a
1426/// lossless process. If you want to round-trip a pointer through an integer in a way that you
1427/// can get back the original pointer, you need to use `as` casts, or replace the integer type
1428/// by `MaybeUninit<$int>` (and never call `assume_init()`). If you are looking for a way to
1429/// store data of arbitrary type, also use `MaybeUninit<T>` (that will also handle uninitialized
1430/// memory due to padding). If you specifically need to store something that is "either an
1431/// integer or a pointer", use `*mut ()`: integers can be converted to pointers and back without
1432/// any loss (via `as` casts or via `transmute`).
1433///
1434/// # Examples
1435///
1436/// There are a few things that `transmute` is really useful for.
1437///
1438/// Turning a pointer into a function pointer. This is *not* portable to
1439/// machines where function pointers and data pointers have different sizes.
1440///
1441/// ```
1442/// fn foo() -> i32 {
1443/// 0
1444/// }
1445/// // Crucially, we `as`-cast to a raw pointer before `transmute`ing to a function pointer.
1446/// // This avoids an integer-to-pointer `transmute`, which can be problematic.
1447/// // Transmuting between raw pointers and function pointers (i.e., two pointer types) is fine.
1448/// let pointer = foo as *const ();
1449/// let function = unsafe {
1450/// std::mem::transmute::<*const (), fn() -> i32>(pointer)
1451/// };
1452/// assert_eq!(function(), 0);
1453/// ```
1454///
1455/// Extending a lifetime, or shortening an invariant lifetime. This is
1456/// advanced, very unsafe Rust!
1457///
1458/// ```
1459/// struct R<'a>(&'a i32);
1460/// unsafe fn extend_lifetime<'b>(r: R<'b>) -> R<'static> {
1461/// unsafe { std::mem::transmute::<R<'b>, R<'static>>(r) }
1462/// }
1463///
1464/// unsafe fn shorten_invariant_lifetime<'b, 'c>(r: &'b mut R<'static>)
1465/// -> &'b mut R<'c> {
1466/// unsafe { std::mem::transmute::<&'b mut R<'static>, &'b mut R<'c>>(r) }
1467/// }
1468/// ```
1469///
1470/// # Alternatives
1471///
1472/// Don't despair: many uses of `transmute` can be achieved through other means.
1473/// Below are common applications of `transmute` which can be replaced with safer
1474/// constructs.
1475///
1476/// Turning raw bytes (`[u8; SZ]`) into `u32`, `f64`, etc.:
1477///
1478/// ```
1479/// # #![allow(unnecessary_transmutes)]
1480/// let raw_bytes = [0x78, 0x56, 0x34, 0x12];
1481///
1482/// let num = unsafe {
1483/// std::mem::transmute::<[u8; 4], u32>(raw_bytes)
1484/// };
1485///
1486/// // use `u32::from_ne_bytes` instead
1487/// let num = u32::from_ne_bytes(raw_bytes);
1488/// // or use `u32::from_le_bytes` or `u32::from_be_bytes` to specify the endianness
1489/// let num = u32::from_le_bytes(raw_bytes);
1490/// assert_eq!(num, 0x12345678);
1491/// let num = u32::from_be_bytes(raw_bytes);
1492/// assert_eq!(num, 0x78563412);
1493/// ```
1494///
1495/// Turning a pointer into a `usize`:
1496///
1497/// ```no_run
1498/// let ptr = &0;
1499/// let ptr_num_transmute = unsafe {
1500/// std::mem::transmute::<&i32, usize>(ptr)
1501/// };
1502///
1503/// // Use an `as` cast instead
1504/// let ptr_num_cast = ptr as *const i32 as usize;
1505/// ```
1506///
1507/// Note that using `transmute` to turn a pointer to a `usize` is (as noted above) [undefined
1508/// behavior][ub] in `const` contexts. Also outside of consts, this operation might not behave
1509/// as expected -- this is touching on many unspecified aspects of the Rust memory model.
1510/// Depending on what the code is doing, the following alternatives are preferable to
1511/// pointer-to-integer transmutation:
1512/// - If the code just wants to store data of arbitrary type in some buffer and needs to pick a
1513/// type for that buffer, it can use [`MaybeUninit`][crate::mem::MaybeUninit].
1514/// - If the code actually wants to work on the address the pointer points to, it can use `as`
1515/// casts or [`ptr.addr()`][pointer::addr].
1516///
1517/// Turning a `*mut T` into a `&mut T`:
1518///
1519/// ```
1520/// let ptr: *mut i32 = &mut 0;
1521/// let ref_transmuted = unsafe {
1522/// std::mem::transmute::<*mut i32, &mut i32>(ptr)
1523/// };
1524///
1525/// // Use a reborrow instead
1526/// let ref_casted = unsafe { &mut *ptr };
1527/// ```
1528///
1529/// Turning a `&mut T` into a `&mut U`:
1530///
1531/// ```
1532/// let ptr = &mut 0;
1533/// let val_transmuted = unsafe {
1534/// std::mem::transmute::<&mut i32, &mut u32>(ptr)
1535/// };
1536///
1537/// // Now, put together `as` and reborrowing - note the chaining of `as`
1538/// // `as` is not transitive
1539/// let val_casts = unsafe { &mut *(ptr as *mut i32 as *mut u32) };
1540/// ```
1541///
1542/// Turning a `&str` into a `&[u8]`:
1543///
1544/// ```
1545/// // this is not a good way to do this.
1546/// let slice = unsafe { std::mem::transmute::<&str, &[u8]>("Rust") };
1547/// assert_eq!(slice, &[82, 117, 115, 116]);
1548///
1549/// // You could use `str::as_bytes`
1550/// let slice = "Rust".as_bytes();
1551/// assert_eq!(slice, &[82, 117, 115, 116]);
1552///
1553/// // Or, just use a byte string, if you have control over the string
1554/// // literal
1555/// assert_eq!(b"Rust", &[82, 117, 115, 116]);
1556/// ```
1557///
1558/// Turning a `Vec<&T>` into a `Vec<Option<&T>>`.
1559///
1560/// To transmute the inner type of the contents of a container, you must make sure to not
1561/// violate any of the container's invariants. For `Vec`, this means that both the size
1562/// *and alignment* of the inner types have to match. Other containers might rely on the
1563/// size of the type, alignment, or even the `TypeId`, in which case transmuting wouldn't
1564/// be possible at all without violating the container invariants.
1565///
1566/// ```
1567/// let store = [0, 1, 2, 3];
1568/// let v_orig = store.iter().collect::<Vec<&i32>>();
1569///
1570/// // clone the vector as we will reuse them later
1571/// let v_clone = v_orig.clone();
1572///
1573/// // Using transmute: this relies on the unspecified data layout of `Vec`, which is a
1574/// // bad idea and could cause Undefined Behavior.
1575/// // However, it is no-copy.
1576/// let v_transmuted = unsafe {
1577/// std::mem::transmute::<Vec<&i32>, Vec<Option<&i32>>>(v_clone)
1578/// };
1579///
1580/// let v_clone = v_orig.clone();
1581///
1582/// // This is the suggested, safe way.
1583/// // It may copy the entire vector into a new one though, but also may not.
1584/// let v_collected = v_clone.into_iter()
1585/// .map(Some)
1586/// .collect::<Vec<Option<&i32>>>();
1587///
1588/// let v_clone = v_orig.clone();
1589///
1590/// // This is the proper no-copy, unsafe way of "transmuting" a `Vec`, without relying on the
1591/// // data layout. Instead of literally calling `transmute`, we perform a pointer cast, but
1592/// // in terms of converting the original inner type (`&i32`) to the new one (`Option<&i32>`),
1593/// // this has all the same caveats. Besides the information provided above, also consult the
1594/// // [`from_raw_parts`] documentation.
1595/// let v_from_raw = unsafe {
1596// FIXME Update this when vec_into_raw_parts is stabilized
1597/// // Ensure the original vector is not dropped.
1598/// let mut v_clone = std::mem::ManuallyDrop::new(v_clone);
1599/// Vec::from_raw_parts(v_clone.as_mut_ptr() as *mut Option<&i32>,
1600/// v_clone.len(),
1601/// v_clone.capacity())
1602/// };
1603/// ```
1604///
1605/// [`from_raw_parts`]: ../../std/vec/struct.Vec.html#method.from_raw_parts
1606///
1607/// Implementing `split_at_mut`:
1608///
1609/// ```
1610/// use std::{slice, mem};
1611///
1612/// // There are multiple ways to do this, and there are multiple problems
1613/// // with the following (transmute) way.
1614/// fn split_at_mut_transmute<T>(slice: &mut [T], mid: usize)
1615/// -> (&mut [T], &mut [T]) {
1616/// let len = slice.len();
1617/// assert!(mid <= len);
1618/// unsafe {
1619/// let slice2 = mem::transmute::<&mut [T], &mut [T]>(slice);
1620/// // first: transmute is not type safe; all it checks is that T and
1621/// // U are of the same size. Second, right here, you have two
1622/// // mutable references pointing to the same memory.
1623/// (&mut slice[0..mid], &mut slice2[mid..len])
1624/// }
1625/// }
1626///
1627/// // This gets rid of the type safety problems; `&mut *` will *only* give
1628/// // you a `&mut T` from a `&mut T` or `*mut T`.
1629/// fn split_at_mut_casts<T>(slice: &mut [T], mid: usize)
1630/// -> (&mut [T], &mut [T]) {
1631/// let len = slice.len();
1632/// assert!(mid <= len);
1633/// unsafe {
1634/// let slice2 = &mut *(slice as *mut [T]);
1635/// // however, you still have two mutable references pointing to
1636/// // the same memory.
1637/// (&mut slice[0..mid], &mut slice2[mid..len])
1638/// }
1639/// }
1640///
1641/// // This is how the standard library does it. This is the best method, if
1642/// // you need to do something like this
1643/// fn split_at_stdlib<T>(slice: &mut [T], mid: usize)
1644/// -> (&mut [T], &mut [T]) {
1645/// let len = slice.len();
1646/// assert!(mid <= len);
1647/// unsafe {
1648/// let ptr = slice.as_mut_ptr();
1649/// // This now has three mutable references pointing at the same
1650/// // memory. `slice`, the rvalue ret.0, and the rvalue ret.1.
1651/// // `slice` is never used after `let ptr = ...`, and so one can
1652/// // treat it as "dead", and therefore, you only have two real
1653/// // mutable slices.
1654/// (slice::from_raw_parts_mut(ptr, mid),
1655/// slice::from_raw_parts_mut(ptr.add(mid), len - mid))
1656/// }
1657/// }
1658/// ```
1659#[stable(feature = "rust1", since = "1.0.0")]
1660#[rustc_allowed_through_unstable_modules = "import this function via `std::mem` instead"]
1661#[rustc_const_stable(feature = "const_transmute", since = "1.56.0")]
1662#[rustc_diagnostic_item = "transmute"]
1663#[rustc_nounwind]
1664#[rustc_intrinsic]
1665pub const unsafe fn transmute<Src, Dst>(src: Src) -> Dst;
1666
1667/// Like [`transmute`], but even less checked at compile-time: rather than
1668/// giving an error for `size_of::<Src>() != size_of::<Dst>()`, it's
1669/// **Undefined Behavior** at runtime.
1670///
1671/// Prefer normal `transmute` where possible, for the extra checking, since
1672/// both do exactly the same thing at runtime, if they both compile.
1673///
1674/// This is not expected to ever be exposed directly to users, rather it
1675/// may eventually be exposed through some more-constrained API.
1676#[rustc_intrinsic_const_stable_indirect]
1677#[rustc_nounwind]
1678#[rustc_intrinsic]
1679pub const unsafe fn transmute_unchecked<Src, Dst>(src: Src) -> Dst;
1680
1681/// Returns `true` if the actual type given as `T` requires drop
1682/// glue; returns `false` if the actual type provided for `T`
1683/// implements `Copy`.
1684///
1685/// If the actual type neither requires drop glue nor implements
1686/// `Copy`, then the return value of this function is unspecified.
1687///
1688/// Note that, unlike most intrinsics, this is safe to call;
1689/// it does not require an `unsafe` block.
1690/// Therefore, implementations must not require the user to uphold
1691/// any safety invariants.
1692///
1693/// The stabilized version of this intrinsic is [`mem::needs_drop`](crate::mem::needs_drop).
1694#[rustc_intrinsic_const_stable_indirect]
1695#[rustc_nounwind]
1696#[rustc_intrinsic]
1697pub const fn needs_drop<T: ?Sized>() -> bool;
1698
1699/// Calculates the offset from a pointer.
1700///
1701/// This is implemented as an intrinsic to avoid converting to and from an
1702/// integer, since the conversion would throw away aliasing information.
1703///
1704/// This can only be used with `Ptr` as a raw pointer type (`*mut` or `*const`)
1705/// to a `Sized` pointee and with `Delta` as `usize` or `isize`. Any other
1706/// instantiations may arbitrarily misbehave, and that's *not* a compiler bug.
1707///
1708/// # Safety
1709///
1710/// If the computed offset is non-zero, then both the starting and resulting pointer must be
1711/// either in bounds or at the end of an allocated object. If either pointer is out
1712/// of bounds or arithmetic overflow occurs then this operation is undefined behavior.
1713///
1714/// The stabilized version of this intrinsic is [`pointer::offset`].
1715#[must_use = "returns a new pointer rather than modifying its argument"]
1716#[rustc_intrinsic_const_stable_indirect]
1717#[rustc_nounwind]
1718#[rustc_intrinsic]
1719pub const unsafe fn offset<Ptr, Delta>(dst: Ptr, offset: Delta) -> Ptr;
1720
1721/// Calculates the offset from a pointer, potentially wrapping.
1722///
1723/// This is implemented as an intrinsic to avoid converting to and from an
1724/// integer, since the conversion inhibits certain optimizations.
1725///
1726/// # Safety
1727///
1728/// Unlike the `offset` intrinsic, this intrinsic does not restrict the
1729/// resulting pointer to point into or at the end of an allocated
1730/// object, and it wraps with two's complement arithmetic. The resulting
1731/// value is not necessarily valid to be used to actually access memory.
1732///
1733/// The stabilized version of this intrinsic is [`pointer::wrapping_offset`].
1734#[must_use = "returns a new pointer rather than modifying its argument"]
1735#[rustc_intrinsic_const_stable_indirect]
1736#[rustc_nounwind]
1737#[rustc_intrinsic]
1738pub const unsafe fn arith_offset<T>(dst: *const T, offset: isize) -> *const T;
1739
1740/// Masks out bits of the pointer according to a mask.
1741///
1742/// Note that, unlike most intrinsics, this is safe to call;
1743/// it does not require an `unsafe` block.
1744/// Therefore, implementations must not require the user to uphold
1745/// any safety invariants.
1746///
1747/// Consider using [`pointer::mask`] instead.
1748#[rustc_nounwind]
1749#[rustc_intrinsic]
1750pub fn ptr_mask<T>(ptr: *const T, mask: usize) -> *const T;
1751
1752/// Equivalent to the appropriate `llvm.memcpy.p0i8.0i8.*` intrinsic, with
1753/// a size of `count` * `size_of::<T>()` and an alignment of
1754/// `min_align_of::<T>()`
1755///
1756/// This intrinsic does not have a stable counterpart.
1757/// # Safety
1758///
1759/// The safety requirements are consistent with [`copy_nonoverlapping`]
1760/// while the read and write behaviors are volatile,
1761/// which means it will not be optimized out unless `_count` or `size_of::<T>()` is equal to zero.
1762///
1763/// [`copy_nonoverlapping`]: ptr::copy_nonoverlapping
1764#[rustc_intrinsic]
1765#[rustc_nounwind]
1766pub unsafe fn volatile_copy_nonoverlapping_memory<T>(dst: *mut T, src: *const T, count: usize);
1767/// Equivalent to the appropriate `llvm.memmove.p0i8.0i8.*` intrinsic, with
1768/// a size of `count * size_of::<T>()` and an alignment of
1769/// `min_align_of::<T>()`
1770///
1771/// The volatile parameter is set to `true`, so it will not be optimized out
1772/// unless size is equal to zero.
1773///
1774/// This intrinsic does not have a stable counterpart.
1775#[rustc_intrinsic]
1776#[rustc_nounwind]
1777pub unsafe fn volatile_copy_memory<T>(dst: *mut T, src: *const T, count: usize);
1778/// Equivalent to the appropriate `llvm.memset.p0i8.*` intrinsic, with a
1779/// size of `count * size_of::<T>()` and an alignment of
1780/// `min_align_of::<T>()`.
1781///
1782/// This intrinsic does not have a stable counterpart.
1783/// # Safety
1784///
1785/// The safety requirements are consistent with [`write_bytes`] while the write behavior is volatile,
1786/// which means it will not be optimized out unless `_count` or `size_of::<T>()` is equal to zero.
1787///
1788/// [`write_bytes`]: ptr::write_bytes
1789#[rustc_intrinsic]
1790#[rustc_nounwind]
1791pub unsafe fn volatile_set_memory<T>(dst: *mut T, val: u8, count: usize);
1792
1793/// Performs a volatile load from the `src` pointer.
1794///
1795/// The stabilized version of this intrinsic is [`core::ptr::read_volatile`].
1796#[rustc_intrinsic]
1797#[rustc_nounwind]
1798pub unsafe fn volatile_load<T>(src: *const T) -> T;
1799/// Performs a volatile store to the `dst` pointer.
1800///
1801/// The stabilized version of this intrinsic is [`core::ptr::write_volatile`].
1802#[rustc_intrinsic]
1803#[rustc_nounwind]
1804pub unsafe fn volatile_store<T>(dst: *mut T, val: T);
1805
1806/// Performs a volatile load from the `src` pointer
1807/// The pointer is not required to be aligned.
1808///
1809/// This intrinsic does not have a stable counterpart.
1810#[rustc_intrinsic]
1811#[rustc_nounwind]
1812#[rustc_diagnostic_item = "intrinsics_unaligned_volatile_load"]
1813pub unsafe fn unaligned_volatile_load<T>(src: *const T) -> T;
1814/// Performs a volatile store to the `dst` pointer.
1815/// The pointer is not required to be aligned.
1816///
1817/// This intrinsic does not have a stable counterpart.
1818#[rustc_intrinsic]
1819#[rustc_nounwind]
1820#[rustc_diagnostic_item = "intrinsics_unaligned_volatile_store"]
1821pub unsafe fn unaligned_volatile_store<T>(dst: *mut T, val: T);
1822
1823/// Returns the square root of an `f16`
1824///
1825/// The stabilized version of this intrinsic is
1826/// [`f16::sqrt`](../../std/primitive.f16.html#method.sqrt)
1827#[rustc_intrinsic]
1828#[rustc_nounwind]
1829pub unsafe fn sqrtf16(x: f16) -> f16;
1830/// Returns the square root of an `f32`
1831///
1832/// The stabilized version of this intrinsic is
1833/// [`f32::sqrt`](../../std/primitive.f32.html#method.sqrt)
1834#[rustc_intrinsic]
1835#[rustc_nounwind]
1836pub unsafe fn sqrtf32(x: f32) -> f32;
1837/// Returns the square root of an `f64`
1838///
1839/// The stabilized version of this intrinsic is
1840/// [`f64::sqrt`](../../std/primitive.f64.html#method.sqrt)
1841#[rustc_intrinsic]
1842#[rustc_nounwind]
1843pub unsafe fn sqrtf64(x: f64) -> f64;
1844/// Returns the square root of an `f128`
1845///
1846/// The stabilized version of this intrinsic is
1847/// [`f128::sqrt`](../../std/primitive.f128.html#method.sqrt)
1848#[rustc_intrinsic]
1849#[rustc_nounwind]
1850pub unsafe fn sqrtf128(x: f128) -> f128;
1851
1852/// Raises an `f16` to an integer power.
1853///
1854/// The stabilized version of this intrinsic is
1855/// [`f16::powi`](../../std/primitive.f16.html#method.powi)
1856#[rustc_intrinsic]
1857#[rustc_nounwind]
1858pub unsafe fn powif16(a: f16, x: i32) -> f16;
1859/// Raises an `f32` to an integer power.
1860///
1861/// The stabilized version of this intrinsic is
1862/// [`f32::powi`](../../std/primitive.f32.html#method.powi)
1863#[rustc_intrinsic]
1864#[rustc_nounwind]
1865pub unsafe fn powif32(a: f32, x: i32) -> f32;
1866/// Raises an `f64` to an integer power.
1867///
1868/// The stabilized version of this intrinsic is
1869/// [`f64::powi`](../../std/primitive.f64.html#method.powi)
1870#[rustc_intrinsic]
1871#[rustc_nounwind]
1872pub unsafe fn powif64(a: f64, x: i32) -> f64;
1873/// Raises an `f128` to an integer power.
1874///
1875/// The stabilized version of this intrinsic is
1876/// [`f128::powi`](../../std/primitive.f128.html#method.powi)
1877#[rustc_intrinsic]
1878#[rustc_nounwind]
1879pub unsafe fn powif128(a: f128, x: i32) -> f128;
1880
1881/// Returns the sine of an `f16`.
1882///
1883/// The stabilized version of this intrinsic is
1884/// [`f16::sin`](../../std/primitive.f16.html#method.sin)
1885#[rustc_intrinsic]
1886#[rustc_nounwind]
1887pub unsafe fn sinf16(x: f16) -> f16;
1888/// Returns the sine of an `f32`.
1889///
1890/// The stabilized version of this intrinsic is
1891/// [`f32::sin`](../../std/primitive.f32.html#method.sin)
1892#[rustc_intrinsic]
1893#[rustc_nounwind]
1894pub unsafe fn sinf32(x: f32) -> f32;
1895/// Returns the sine of an `f64`.
1896///
1897/// The stabilized version of this intrinsic is
1898/// [`f64::sin`](../../std/primitive.f64.html#method.sin)
1899#[rustc_intrinsic]
1900#[rustc_nounwind]
1901pub unsafe fn sinf64(x: f64) -> f64;
1902/// Returns the sine of an `f128`.
1903///
1904/// The stabilized version of this intrinsic is
1905/// [`f128::sin`](../../std/primitive.f128.html#method.sin)
1906#[rustc_intrinsic]
1907#[rustc_nounwind]
1908pub unsafe fn sinf128(x: f128) -> f128;
1909
1910/// Returns the cosine of an `f16`.
1911///
1912/// The stabilized version of this intrinsic is
1913/// [`f16::cos`](../../std/primitive.f16.html#method.cos)
1914#[rustc_intrinsic]
1915#[rustc_nounwind]
1916pub unsafe fn cosf16(x: f16) -> f16;
1917/// Returns the cosine of an `f32`.
1918///
1919/// The stabilized version of this intrinsic is
1920/// [`f32::cos`](../../std/primitive.f32.html#method.cos)
1921#[rustc_intrinsic]
1922#[rustc_nounwind]
1923pub unsafe fn cosf32(x: f32) -> f32;
1924/// Returns the cosine of an `f64`.
1925///
1926/// The stabilized version of this intrinsic is
1927/// [`f64::cos`](../../std/primitive.f64.html#method.cos)
1928#[rustc_intrinsic]
1929#[rustc_nounwind]
1930pub unsafe fn cosf64(x: f64) -> f64;
1931/// Returns the cosine of an `f128`.
1932///
1933/// The stabilized version of this intrinsic is
1934/// [`f128::cos`](../../std/primitive.f128.html#method.cos)
1935#[rustc_intrinsic]
1936#[rustc_nounwind]
1937pub unsafe fn cosf128(x: f128) -> f128;
1938
1939/// Raises an `f16` to an `f16` power.
1940///
1941/// The stabilized version of this intrinsic is
1942/// [`f16::powf`](../../std/primitive.f16.html#method.powf)
1943#[rustc_intrinsic]
1944#[rustc_nounwind]
1945pub unsafe fn powf16(a: f16, x: f16) -> f16;
1946/// Raises an `f32` to an `f32` power.
1947///
1948/// The stabilized version of this intrinsic is
1949/// [`f32::powf`](../../std/primitive.f32.html#method.powf)
1950#[rustc_intrinsic]
1951#[rustc_nounwind]
1952pub unsafe fn powf32(a: f32, x: f32) -> f32;
1953/// Raises an `f64` to an `f64` power.
1954///
1955/// The stabilized version of this intrinsic is
1956/// [`f64::powf`](../../std/primitive.f64.html#method.powf)
1957#[rustc_intrinsic]
1958#[rustc_nounwind]
1959pub unsafe fn powf64(a: f64, x: f64) -> f64;
1960/// Raises an `f128` to an `f128` power.
1961///
1962/// The stabilized version of this intrinsic is
1963/// [`f128::powf`](../../std/primitive.f128.html#method.powf)
1964#[rustc_intrinsic]
1965#[rustc_nounwind]
1966pub unsafe fn powf128(a: f128, x: f128) -> f128;
1967
1968/// Returns the exponential of an `f16`.
1969///
1970/// The stabilized version of this intrinsic is
1971/// [`f16::exp`](../../std/primitive.f16.html#method.exp)
1972#[rustc_intrinsic]
1973#[rustc_nounwind]
1974pub unsafe fn expf16(x: f16) -> f16;
1975/// Returns the exponential of an `f32`.
1976///
1977/// The stabilized version of this intrinsic is
1978/// [`f32::exp`](../../std/primitive.f32.html#method.exp)
1979#[rustc_intrinsic]
1980#[rustc_nounwind]
1981pub unsafe fn expf32(x: f32) -> f32;
1982/// Returns the exponential of an `f64`.
1983///
1984/// The stabilized version of this intrinsic is
1985/// [`f64::exp`](../../std/primitive.f64.html#method.exp)
1986#[rustc_intrinsic]
1987#[rustc_nounwind]
1988pub unsafe fn expf64(x: f64) -> f64;
1989/// Returns the exponential of an `f128`.
1990///
1991/// The stabilized version of this intrinsic is
1992/// [`f128::exp`](../../std/primitive.f128.html#method.exp)
1993#[rustc_intrinsic]
1994#[rustc_nounwind]
1995pub unsafe fn expf128(x: f128) -> f128;
1996
1997/// Returns 2 raised to the power of an `f16`.
1998///
1999/// The stabilized version of this intrinsic is
2000/// [`f16::exp2`](../../std/primitive.f16.html#method.exp2)
2001#[rustc_intrinsic]
2002#[rustc_nounwind]
2003pub unsafe fn exp2f16(x: f16) -> f16;
2004/// Returns 2 raised to the power of an `f32`.
2005///
2006/// The stabilized version of this intrinsic is
2007/// [`f32::exp2`](../../std/primitive.f32.html#method.exp2)
2008#[rustc_intrinsic]
2009#[rustc_nounwind]
2010pub unsafe fn exp2f32(x: f32) -> f32;
2011/// Returns 2 raised to the power of an `f64`.
2012///
2013/// The stabilized version of this intrinsic is
2014/// [`f64::exp2`](../../std/primitive.f64.html#method.exp2)
2015#[rustc_intrinsic]
2016#[rustc_nounwind]
2017pub unsafe fn exp2f64(x: f64) -> f64;
2018/// Returns 2 raised to the power of an `f128`.
2019///
2020/// The stabilized version of this intrinsic is
2021/// [`f128::exp2`](../../std/primitive.f128.html#method.exp2)
2022#[rustc_intrinsic]
2023#[rustc_nounwind]
2024pub unsafe fn exp2f128(x: f128) -> f128;
2025
2026/// Returns the natural logarithm of an `f16`.
2027///
2028/// The stabilized version of this intrinsic is
2029/// [`f16::ln`](../../std/primitive.f16.html#method.ln)
2030#[rustc_intrinsic]
2031#[rustc_nounwind]
2032pub unsafe fn logf16(x: f16) -> f16;
2033/// Returns the natural logarithm of an `f32`.
2034///
2035/// The stabilized version of this intrinsic is
2036/// [`f32::ln`](../../std/primitive.f32.html#method.ln)
2037#[rustc_intrinsic]
2038#[rustc_nounwind]
2039pub unsafe fn logf32(x: f32) -> f32;
2040/// Returns the natural logarithm of an `f64`.
2041///
2042/// The stabilized version of this intrinsic is
2043/// [`f64::ln`](../../std/primitive.f64.html#method.ln)
2044#[rustc_intrinsic]
2045#[rustc_nounwind]
2046pub unsafe fn logf64(x: f64) -> f64;
2047/// Returns the natural logarithm of an `f128`.
2048///
2049/// The stabilized version of this intrinsic is
2050/// [`f128::ln`](../../std/primitive.f128.html#method.ln)
2051#[rustc_intrinsic]
2052#[rustc_nounwind]
2053pub unsafe fn logf128(x: f128) -> f128;
2054
2055/// Returns the base 10 logarithm of an `f16`.
2056///
2057/// The stabilized version of this intrinsic is
2058/// [`f16::log10`](../../std/primitive.f16.html#method.log10)
2059#[rustc_intrinsic]
2060#[rustc_nounwind]
2061pub unsafe fn log10f16(x: f16) -> f16;
2062/// Returns the base 10 logarithm of an `f32`.
2063///
2064/// The stabilized version of this intrinsic is
2065/// [`f32::log10`](../../std/primitive.f32.html#method.log10)
2066#[rustc_intrinsic]
2067#[rustc_nounwind]
2068pub unsafe fn log10f32(x: f32) -> f32;
2069/// Returns the base 10 logarithm of an `f64`.
2070///
2071/// The stabilized version of this intrinsic is
2072/// [`f64::log10`](../../std/primitive.f64.html#method.log10)
2073#[rustc_intrinsic]
2074#[rustc_nounwind]
2075pub unsafe fn log10f64(x: f64) -> f64;
2076/// Returns the base 10 logarithm of an `f128`.
2077///
2078/// The stabilized version of this intrinsic is
2079/// [`f128::log10`](../../std/primitive.f128.html#method.log10)
2080#[rustc_intrinsic]
2081#[rustc_nounwind]
2082pub unsafe fn log10f128(x: f128) -> f128;
2083
2084/// Returns the base 2 logarithm of an `f16`.
2085///
2086/// The stabilized version of this intrinsic is
2087/// [`f16::log2`](../../std/primitive.f16.html#method.log2)
2088#[rustc_intrinsic]
2089#[rustc_nounwind]
2090pub unsafe fn log2f16(x: f16) -> f16;
2091/// Returns the base 2 logarithm of an `f32`.
2092///
2093/// The stabilized version of this intrinsic is
2094/// [`f32::log2`](../../std/primitive.f32.html#method.log2)
2095#[rustc_intrinsic]
2096#[rustc_nounwind]
2097pub unsafe fn log2f32(x: f32) -> f32;
2098/// Returns the base 2 logarithm of an `f64`.
2099///
2100/// The stabilized version of this intrinsic is
2101/// [`f64::log2`](../../std/primitive.f64.html#method.log2)
2102#[rustc_intrinsic]
2103#[rustc_nounwind]
2104pub unsafe fn log2f64(x: f64) -> f64;
2105/// Returns the base 2 logarithm of an `f128`.
2106///
2107/// The stabilized version of this intrinsic is
2108/// [`f128::log2`](../../std/primitive.f128.html#method.log2)
2109#[rustc_intrinsic]
2110#[rustc_nounwind]
2111pub unsafe fn log2f128(x: f128) -> f128;
2112
2113/// Returns `a * b + c` for `f16` values.
2114///
2115/// The stabilized version of this intrinsic is
2116/// [`f16::mul_add`](../../std/primitive.f16.html#method.mul_add)
2117#[rustc_intrinsic]
2118#[rustc_nounwind]
2119pub unsafe fn fmaf16(a: f16, b: f16, c: f16) -> f16;
2120/// Returns `a * b + c` for `f32` values.
2121///
2122/// The stabilized version of this intrinsic is
2123/// [`f32::mul_add`](../../std/primitive.f32.html#method.mul_add)
2124#[rustc_intrinsic]
2125#[rustc_nounwind]
2126pub unsafe fn fmaf32(a: f32, b: f32, c: f32) -> f32;
2127/// Returns `a * b + c` for `f64` values.
2128///
2129/// The stabilized version of this intrinsic is
2130/// [`f64::mul_add`](../../std/primitive.f64.html#method.mul_add)
2131#[rustc_intrinsic]
2132#[rustc_nounwind]
2133pub unsafe fn fmaf64(a: f64, b: f64, c: f64) -> f64;
2134/// Returns `a * b + c` for `f128` values.
2135///
2136/// The stabilized version of this intrinsic is
2137/// [`f128::mul_add`](../../std/primitive.f128.html#method.mul_add)
2138#[rustc_intrinsic]
2139#[rustc_nounwind]
2140pub unsafe fn fmaf128(a: f128, b: f128, c: f128) -> f128;
2141
2142/// Returns `a * b + c` for `f16` values, non-deterministically executing
2143/// either a fused multiply-add or two operations with rounding of the
2144/// intermediate result.
2145///
2146/// The operation is fused if the code generator determines that target
2147/// instruction set has support for a fused operation, and that the fused
2148/// operation is more efficient than the equivalent, separate pair of mul
2149/// and add instructions. It is unspecified whether or not a fused operation
2150/// is selected, and that may depend on optimization level and context, for
2151/// example.
2152#[rustc_intrinsic]
2153#[rustc_nounwind]
2154pub unsafe fn fmuladdf16(a: f16, b: f16, c: f16) -> f16;
2155/// Returns `a * b + c` for `f32` values, non-deterministically executing
2156/// either a fused multiply-add or two operations with rounding of the
2157/// intermediate result.
2158///
2159/// The operation is fused if the code generator determines that target
2160/// instruction set has support for a fused operation, and that the fused
2161/// operation is more efficient than the equivalent, separate pair of mul
2162/// and add instructions. It is unspecified whether or not a fused operation
2163/// is selected, and that may depend on optimization level and context, for
2164/// example.
2165#[rustc_intrinsic]
2166#[rustc_nounwind]
2167pub unsafe fn fmuladdf32(a: f32, b: f32, c: f32) -> f32;
2168/// Returns `a * b + c` for `f64` values, non-deterministically executing
2169/// either a fused multiply-add or two operations with rounding of the
2170/// intermediate result.
2171///
2172/// The operation is fused if the code generator determines that target
2173/// instruction set has support for a fused operation, and that the fused
2174/// operation is more efficient than the equivalent, separate pair of mul
2175/// and add instructions. It is unspecified whether or not a fused operation
2176/// is selected, and that may depend on optimization level and context, for
2177/// example.
2178#[rustc_intrinsic]
2179#[rustc_nounwind]
2180pub unsafe fn fmuladdf64(a: f64, b: f64, c: f64) -> f64;
2181/// Returns `a * b + c` for `f128` values, non-deterministically executing
2182/// either a fused multiply-add or two operations with rounding of the
2183/// intermediate result.
2184///
2185/// The operation is fused if the code generator determines that target
2186/// instruction set has support for a fused operation, and that the fused
2187/// operation is more efficient than the equivalent, separate pair of mul
2188/// and add instructions. It is unspecified whether or not a fused operation
2189/// is selected, and that may depend on optimization level and context, for
2190/// example.
2191#[rustc_intrinsic]
2192#[rustc_nounwind]
2193pub unsafe fn fmuladdf128(a: f128, b: f128, c: f128) -> f128;
2194
2195/// Returns the largest integer less than or equal to an `f16`.
2196///
2197/// The stabilized version of this intrinsic is
2198/// [`f16::floor`](../../std/primitive.f16.html#method.floor)
2199#[rustc_intrinsic]
2200#[rustc_nounwind]
2201pub unsafe fn floorf16(x: f16) -> f16;
2202/// Returns the largest integer less than or equal to an `f32`.
2203///
2204/// The stabilized version of this intrinsic is
2205/// [`f32::floor`](../../std/primitive.f32.html#method.floor)
2206#[rustc_intrinsic]
2207#[rustc_nounwind]
2208pub unsafe fn floorf32(x: f32) -> f32;
2209/// Returns the largest integer less than or equal to an `f64`.
2210///
2211/// The stabilized version of this intrinsic is
2212/// [`f64::floor`](../../std/primitive.f64.html#method.floor)
2213#[rustc_intrinsic]
2214#[rustc_nounwind]
2215pub unsafe fn floorf64(x: f64) -> f64;
2216/// Returns the largest integer less than or equal to an `f128`.
2217///
2218/// The stabilized version of this intrinsic is
2219/// [`f128::floor`](../../std/primitive.f128.html#method.floor)
2220#[rustc_intrinsic]
2221#[rustc_nounwind]
2222pub unsafe fn floorf128(x: f128) -> f128;
2223
2224/// Returns the smallest integer greater than or equal to an `f16`.
2225///
2226/// The stabilized version of this intrinsic is
2227/// [`f16::ceil`](../../std/primitive.f16.html#method.ceil)
2228#[rustc_intrinsic]
2229#[rustc_nounwind]
2230pub unsafe fn ceilf16(x: f16) -> f16;
2231/// Returns the smallest integer greater than or equal to an `f32`.
2232///
2233/// The stabilized version of this intrinsic is
2234/// [`f32::ceil`](../../std/primitive.f32.html#method.ceil)
2235#[rustc_intrinsic]
2236#[rustc_nounwind]
2237pub unsafe fn ceilf32(x: f32) -> f32;
2238/// Returns the smallest integer greater than or equal to an `f64`.
2239///
2240/// The stabilized version of this intrinsic is
2241/// [`f64::ceil`](../../std/primitive.f64.html#method.ceil)
2242#[rustc_intrinsic]
2243#[rustc_nounwind]
2244pub unsafe fn ceilf64(x: f64) -> f64;
2245/// Returns the smallest integer greater than or equal to an `f128`.
2246///
2247/// The stabilized version of this intrinsic is
2248/// [`f128::ceil`](../../std/primitive.f128.html#method.ceil)
2249#[rustc_intrinsic]
2250#[rustc_nounwind]
2251pub unsafe fn ceilf128(x: f128) -> f128;
2252
2253/// Returns the integer part of an `f16`.
2254///
2255/// The stabilized version of this intrinsic is
2256/// [`f16::trunc`](../../std/primitive.f16.html#method.trunc)
2257#[rustc_intrinsic]
2258#[rustc_nounwind]
2259pub unsafe fn truncf16(x: f16) -> f16;
2260/// Returns the integer part of an `f32`.
2261///
2262/// The stabilized version of this intrinsic is
2263/// [`f32::trunc`](../../std/primitive.f32.html#method.trunc)
2264#[rustc_intrinsic]
2265#[rustc_nounwind]
2266pub unsafe fn truncf32(x: f32) -> f32;
2267/// Returns the integer part of an `f64`.
2268///
2269/// The stabilized version of this intrinsic is
2270/// [`f64::trunc`](../../std/primitive.f64.html#method.trunc)
2271#[rustc_intrinsic]
2272#[rustc_nounwind]
2273pub unsafe fn truncf64(x: f64) -> f64;
2274/// Returns the integer part of an `f128`.
2275///
2276/// The stabilized version of this intrinsic is
2277/// [`f128::trunc`](../../std/primitive.f128.html#method.trunc)
2278#[rustc_intrinsic]
2279#[rustc_nounwind]
2280pub unsafe fn truncf128(x: f128) -> f128;
2281
2282/// Returns the nearest integer to an `f16`. Rounds half-way cases to the number with an even
2283/// least significant digit.
2284///
2285/// The stabilized version of this intrinsic is
2286/// [`f16::round_ties_even`](../../std/primitive.f16.html#method.round_ties_even)
2287#[rustc_intrinsic]
2288#[rustc_nounwind]
2289pub fn round_ties_even_f16(x: f16) -> f16;
2290
2291/// Returns the nearest integer to an `f32`. Rounds half-way cases to the number with an even
2292/// least significant digit.
2293///
2294/// The stabilized version of this intrinsic is
2295/// [`f32::round_ties_even`](../../std/primitive.f32.html#method.round_ties_even)
2296#[rustc_intrinsic]
2297#[rustc_nounwind]
2298pub fn round_ties_even_f32(x: f32) -> f32;
2299
2300/// Provided for compatibility with stdarch. DO NOT USE.
2301#[inline(always)]
2302pub unsafe fn rintf32(x: f32) -> f32 {
2303 round_ties_even_f32(x)
2304}
2305
2306/// Returns the nearest integer to an `f64`. Rounds half-way cases to the number with an even
2307/// least significant digit.
2308///
2309/// The stabilized version of this intrinsic is
2310/// [`f64::round_ties_even`](../../std/primitive.f64.html#method.round_ties_even)
2311#[rustc_intrinsic]
2312#[rustc_nounwind]
2313pub fn round_ties_even_f64(x: f64) -> f64;
2314
2315/// Provided for compatibility with stdarch. DO NOT USE.
2316#[inline(always)]
2317pub unsafe fn rintf64(x: f64) -> f64 {
2318 round_ties_even_f64(x)
2319}
2320
2321/// Returns the nearest integer to an `f128`. Rounds half-way cases to the number with an even
2322/// least significant digit.
2323///
2324/// The stabilized version of this intrinsic is
2325/// [`f128::round_ties_even`](../../std/primitive.f128.html#method.round_ties_even)
2326#[rustc_intrinsic]
2327#[rustc_nounwind]
2328pub fn round_ties_even_f128(x: f128) -> f128;
2329
2330/// Returns the nearest integer to an `f16`. Rounds half-way cases away from zero.
2331///
2332/// The stabilized version of this intrinsic is
2333/// [`f16::round`](../../std/primitive.f16.html#method.round)
2334#[rustc_intrinsic]
2335#[rustc_nounwind]
2336pub unsafe fn roundf16(x: f16) -> f16;
2337/// Returns the nearest integer to an `f32`. Rounds half-way cases away from zero.
2338///
2339/// The stabilized version of this intrinsic is
2340/// [`f32::round`](../../std/primitive.f32.html#method.round)
2341#[rustc_intrinsic]
2342#[rustc_nounwind]
2343pub unsafe fn roundf32(x: f32) -> f32;
2344/// Returns the nearest integer to an `f64`. Rounds half-way cases away from zero.
2345///
2346/// The stabilized version of this intrinsic is
2347/// [`f64::round`](../../std/primitive.f64.html#method.round)
2348#[rustc_intrinsic]
2349#[rustc_nounwind]
2350pub unsafe fn roundf64(x: f64) -> f64;
2351/// Returns the nearest integer to an `f128`. Rounds half-way cases away from zero.
2352///
2353/// The stabilized version of this intrinsic is
2354/// [`f128::round`](../../std/primitive.f128.html#method.round)
2355#[rustc_intrinsic]
2356#[rustc_nounwind]
2357pub unsafe fn roundf128(x: f128) -> f128;
2358
2359/// Float addition that allows optimizations based on algebraic rules.
2360/// May assume inputs are finite.
2361///
2362/// This intrinsic does not have a stable counterpart.
2363#[rustc_intrinsic]
2364#[rustc_nounwind]
2365pub unsafe fn fadd_fast<T: Copy>(a: T, b: T) -> T;
2366
2367/// Float subtraction that allows optimizations based on algebraic rules.
2368/// May assume inputs are finite.
2369///
2370/// This intrinsic does not have a stable counterpart.
2371#[rustc_intrinsic]
2372#[rustc_nounwind]
2373pub unsafe fn fsub_fast<T: Copy>(a: T, b: T) -> T;
2374
2375/// Float multiplication that allows optimizations based on algebraic rules.
2376/// May assume inputs are finite.
2377///
2378/// This intrinsic does not have a stable counterpart.
2379#[rustc_intrinsic]
2380#[rustc_nounwind]
2381pub unsafe fn fmul_fast<T: Copy>(a: T, b: T) -> T;
2382
2383/// Float division that allows optimizations based on algebraic rules.
2384/// May assume inputs are finite.
2385///
2386/// This intrinsic does not have a stable counterpart.
2387#[rustc_intrinsic]
2388#[rustc_nounwind]
2389pub unsafe fn fdiv_fast<T: Copy>(a: T, b: T) -> T;
2390
2391/// Float remainder that allows optimizations based on algebraic rules.
2392/// May assume inputs are finite.
2393///
2394/// This intrinsic does not have a stable counterpart.
2395#[rustc_intrinsic]
2396#[rustc_nounwind]
2397pub unsafe fn frem_fast<T: Copy>(a: T, b: T) -> T;
2398
2399/// Converts with LLVM’s fptoui/fptosi, which may return undef for values out of range
2400/// (<https://github.com/rust-lang/rust/issues/10184>)
2401///
2402/// Stabilized as [`f32::to_int_unchecked`] and [`f64::to_int_unchecked`].
2403#[rustc_intrinsic]
2404#[rustc_nounwind]
2405pub unsafe fn float_to_int_unchecked<Float: Copy, Int: Copy>(value: Float) -> Int;
2406
2407/// Float addition that allows optimizations based on algebraic rules.
2408///
2409/// Stabilized as [`f16::algebraic_add`], [`f32::algebraic_add`], [`f64::algebraic_add`] and [`f128::algebraic_add`].
2410#[rustc_nounwind]
2411#[rustc_intrinsic]
2412pub const fn fadd_algebraic<T: Copy>(a: T, b: T) -> T;
2413
2414/// Float subtraction that allows optimizations based on algebraic rules.
2415///
2416/// Stabilized as [`f16::algebraic_sub`], [`f32::algebraic_sub`], [`f64::algebraic_sub`] and [`f128::algebraic_sub`].
2417#[rustc_nounwind]
2418#[rustc_intrinsic]
2419pub const fn fsub_algebraic<T: Copy>(a: T, b: T) -> T;
2420
2421/// Float multiplication that allows optimizations based on algebraic rules.
2422///
2423/// Stabilized as [`f16::algebraic_mul`], [`f32::algebraic_mul`], [`f64::algebraic_mul`] and [`f128::algebraic_mul`].
2424#[rustc_nounwind]
2425#[rustc_intrinsic]
2426pub const fn fmul_algebraic<T: Copy>(a: T, b: T) -> T;
2427
2428/// Float division that allows optimizations based on algebraic rules.
2429///
2430/// Stabilized as [`f16::algebraic_div`], [`f32::algebraic_div`], [`f64::algebraic_div`] and [`f128::algebraic_div`].
2431#[rustc_nounwind]
2432#[rustc_intrinsic]
2433pub const fn fdiv_algebraic<T: Copy>(a: T, b: T) -> T;
2434
2435/// Float remainder that allows optimizations based on algebraic rules.
2436///
2437/// Stabilized as [`f16::algebraic_rem`], [`f32::algebraic_rem`], [`f64::algebraic_rem`] and [`f128::algebraic_rem`].
2438#[rustc_nounwind]
2439#[rustc_intrinsic]
2440pub const fn frem_algebraic<T: Copy>(a: T, b: T) -> T;
2441
2442/// Returns the number of bits set in an integer type `T`
2443///
2444/// Note that, unlike most intrinsics, this is safe to call;
2445/// it does not require an `unsafe` block.
2446/// Therefore, implementations must not require the user to uphold
2447/// any safety invariants.
2448///
2449/// The stabilized versions of this intrinsic are available on the integer
2450/// primitives via the `count_ones` method. For example,
2451/// [`u32::count_ones`]
2452#[rustc_intrinsic_const_stable_indirect]
2453#[rustc_nounwind]
2454#[rustc_intrinsic]
2455pub const fn ctpop<T: Copy>(x: T) -> u32;
2456
2457/// Returns the number of leading unset bits (zeroes) in an integer type `T`.
2458///
2459/// Note that, unlike most intrinsics, this is safe to call;
2460/// it does not require an `unsafe` block.
2461/// Therefore, implementations must not require the user to uphold
2462/// any safety invariants.
2463///
2464/// The stabilized versions of this intrinsic are available on the integer
2465/// primitives via the `leading_zeros` method. For example,
2466/// [`u32::leading_zeros`]
2467///
2468/// # Examples
2469///
2470/// ```
2471/// #![feature(core_intrinsics)]
2472/// # #![allow(internal_features)]
2473///
2474/// use std::intrinsics::ctlz;
2475///
2476/// let x = 0b0001_1100_u8;
2477/// let num_leading = ctlz(x);
2478/// assert_eq!(num_leading, 3);
2479/// ```
2480///
2481/// An `x` with value `0` will return the bit width of `T`.
2482///
2483/// ```
2484/// #![feature(core_intrinsics)]
2485/// # #![allow(internal_features)]
2486///
2487/// use std::intrinsics::ctlz;
2488///
2489/// let x = 0u16;
2490/// let num_leading = ctlz(x);
2491/// assert_eq!(num_leading, 16);
2492/// ```
2493#[rustc_intrinsic_const_stable_indirect]
2494#[rustc_nounwind]
2495#[rustc_intrinsic]
2496pub const fn ctlz<T: Copy>(x: T) -> u32;
2497
2498/// Like `ctlz`, but extra-unsafe as it returns `undef` when
2499/// given an `x` with value `0`.
2500///
2501/// This intrinsic does not have a stable counterpart.
2502///
2503/// # Examples
2504///
2505/// ```
2506/// #![feature(core_intrinsics)]
2507/// # #![allow(internal_features)]
2508///
2509/// use std::intrinsics::ctlz_nonzero;
2510///
2511/// let x = 0b0001_1100_u8;
2512/// let num_leading = unsafe { ctlz_nonzero(x) };
2513/// assert_eq!(num_leading, 3);
2514/// ```
2515#[rustc_intrinsic_const_stable_indirect]
2516#[rustc_nounwind]
2517#[rustc_intrinsic]
2518pub const unsafe fn ctlz_nonzero<T: Copy>(x: T) -> u32;
2519
2520/// Returns the number of trailing unset bits (zeroes) in an integer type `T`.
2521///
2522/// Note that, unlike most intrinsics, this is safe to call;
2523/// it does not require an `unsafe` block.
2524/// Therefore, implementations must not require the user to uphold
2525/// any safety invariants.
2526///
2527/// The stabilized versions of this intrinsic are available on the integer
2528/// primitives via the `trailing_zeros` method. For example,
2529/// [`u32::trailing_zeros`]
2530///
2531/// # Examples
2532///
2533/// ```
2534/// #![feature(core_intrinsics)]
2535/// # #![allow(internal_features)]
2536///
2537/// use std::intrinsics::cttz;
2538///
2539/// let x = 0b0011_1000_u8;
2540/// let num_trailing = cttz(x);
2541/// assert_eq!(num_trailing, 3);
2542/// ```
2543///
2544/// An `x` with value `0` will return the bit width of `T`:
2545///
2546/// ```
2547/// #![feature(core_intrinsics)]
2548/// # #![allow(internal_features)]
2549///
2550/// use std::intrinsics::cttz;
2551///
2552/// let x = 0u16;
2553/// let num_trailing = cttz(x);
2554/// assert_eq!(num_trailing, 16);
2555/// ```
2556#[rustc_intrinsic_const_stable_indirect]
2557#[rustc_nounwind]
2558#[rustc_intrinsic]
2559pub const fn cttz<T: Copy>(x: T) -> u32;
2560
2561/// Like `cttz`, but extra-unsafe as it returns `undef` when
2562/// given an `x` with value `0`.
2563///
2564/// This intrinsic does not have a stable counterpart.
2565///
2566/// # Examples
2567///
2568/// ```
2569/// #![feature(core_intrinsics)]
2570/// # #![allow(internal_features)]
2571///
2572/// use std::intrinsics::cttz_nonzero;
2573///
2574/// let x = 0b0011_1000_u8;
2575/// let num_trailing = unsafe { cttz_nonzero(x) };
2576/// assert_eq!(num_trailing, 3);
2577/// ```
2578#[rustc_intrinsic_const_stable_indirect]
2579#[rustc_nounwind]
2580#[rustc_intrinsic]
2581pub const unsafe fn cttz_nonzero<T: Copy>(x: T) -> u32;
2582
2583/// Reverses the bytes in an integer type `T`.
2584///
2585/// Note that, unlike most intrinsics, this is safe to call;
2586/// it does not require an `unsafe` block.
2587/// Therefore, implementations must not require the user to uphold
2588/// any safety invariants.
2589///
2590/// The stabilized versions of this intrinsic are available on the integer
2591/// primitives via the `swap_bytes` method. For example,
2592/// [`u32::swap_bytes`]
2593#[rustc_intrinsic_const_stable_indirect]
2594#[rustc_nounwind]
2595#[rustc_intrinsic]
2596pub const fn bswap<T: Copy>(x: T) -> T;
2597
2598/// Reverses the bits in an integer type `T`.
2599///
2600/// Note that, unlike most intrinsics, this is safe to call;
2601/// it does not require an `unsafe` block.
2602/// Therefore, implementations must not require the user to uphold
2603/// any safety invariants.
2604///
2605/// The stabilized versions of this intrinsic are available on the integer
2606/// primitives via the `reverse_bits` method. For example,
2607/// [`u32::reverse_bits`]
2608#[rustc_intrinsic_const_stable_indirect]
2609#[rustc_nounwind]
2610#[rustc_intrinsic]
2611pub const fn bitreverse<T: Copy>(x: T) -> T;
2612
2613/// Does a three-way comparison between the two arguments,
2614/// which must be of character or integer (signed or unsigned) type.
2615///
2616/// This was originally added because it greatly simplified the MIR in `cmp`
2617/// implementations, and then LLVM 20 added a backend intrinsic for it too.
2618///
2619/// The stabilized version of this intrinsic is [`Ord::cmp`].
2620#[rustc_intrinsic_const_stable_indirect]
2621#[rustc_nounwind]
2622#[rustc_intrinsic]
2623pub const fn three_way_compare<T: Copy>(lhs: T, rhss: T) -> crate::cmp::Ordering;
2624
2625/// Combine two values which have no bits in common.
2626///
2627/// This allows the backend to implement it as `a + b` *or* `a | b`,
2628/// depending which is easier to implement on a specific target.
2629///
2630/// # Safety
2631///
2632/// Requires that `(a & b) == 0`, or equivalently that `(a | b) == (a + b)`.
2633///
2634/// Otherwise it's immediate UB.
2635#[rustc_const_unstable(feature = "disjoint_bitor", issue = "135758")]
2636#[rustc_nounwind]
2637#[rustc_intrinsic]
2638#[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
2639#[miri::intrinsic_fallback_is_spec] // the fallbacks all `assume` to tell Miri
2640pub const unsafe fn disjoint_bitor<T: ~const fallback::DisjointBitOr>(a: T, b: T) -> T {
2641 // SAFETY: same preconditions as this function.
2642 unsafe { fallback::DisjointBitOr::disjoint_bitor(a, b) }
2643}
2644
2645/// Performs checked integer addition.
2646///
2647/// Note that, unlike most intrinsics, this is safe to call;
2648/// it does not require an `unsafe` block.
2649/// Therefore, implementations must not require the user to uphold
2650/// any safety invariants.
2651///
2652/// The stabilized versions of this intrinsic are available on the integer
2653/// primitives via the `overflowing_add` method. For example,
2654/// [`u32::overflowing_add`]
2655#[rustc_intrinsic_const_stable_indirect]
2656#[rustc_nounwind]
2657#[rustc_intrinsic]
2658pub const fn add_with_overflow<T: Copy>(x: T, y: T) -> (T, bool);
2659
2660/// Performs checked integer subtraction
2661///
2662/// Note that, unlike most intrinsics, this is safe to call;
2663/// it does not require an `unsafe` block.
2664/// Therefore, implementations must not require the user to uphold
2665/// any safety invariants.
2666///
2667/// The stabilized versions of this intrinsic are available on the integer
2668/// primitives via the `overflowing_sub` method. For example,
2669/// [`u32::overflowing_sub`]
2670#[rustc_intrinsic_const_stable_indirect]
2671#[rustc_nounwind]
2672#[rustc_intrinsic]
2673pub const fn sub_with_overflow<T: Copy>(x: T, y: T) -> (T, bool);
2674
2675/// Performs checked integer multiplication
2676///
2677/// Note that, unlike most intrinsics, this is safe to call;
2678/// it does not require an `unsafe` block.
2679/// Therefore, implementations must not require the user to uphold
2680/// any safety invariants.
2681///
2682/// The stabilized versions of this intrinsic are available on the integer
2683/// primitives via the `overflowing_mul` method. For example,
2684/// [`u32::overflowing_mul`]
2685#[rustc_intrinsic_const_stable_indirect]
2686#[rustc_nounwind]
2687#[rustc_intrinsic]
2688pub const fn mul_with_overflow<T: Copy>(x: T, y: T) -> (T, bool);
2689
2690/// Performs full-width multiplication and addition with a carry:
2691/// `multiplier * multiplicand + addend + carry`.
2692///
2693/// This is possible without any overflow. For `uN`:
2694/// MAX * MAX + MAX + MAX
2695/// => (2ⁿ-1) × (2ⁿ-1) + (2ⁿ-1) + (2ⁿ-1)
2696/// => (2²ⁿ - 2ⁿ⁺¹ + 1) + (2ⁿ⁺¹ - 2)
2697/// => 2²ⁿ - 1
2698///
2699/// For `iN`, the upper bound is MIN * MIN + MAX + MAX => 2²ⁿ⁻² + 2ⁿ - 2,
2700/// and the lower bound is MAX * MIN + MIN + MIN => -2²ⁿ⁻² - 2ⁿ + 2ⁿ⁺¹.
2701///
2702/// This currently supports unsigned integers *only*, no signed ones.
2703/// The stabilized versions of this intrinsic are available on integers.
2704#[unstable(feature = "core_intrinsics", issue = "none")]
2705#[rustc_const_unstable(feature = "const_carrying_mul_add", issue = "85532")]
2706#[rustc_nounwind]
2707#[rustc_intrinsic]
2708#[miri::intrinsic_fallback_is_spec]
2709pub const fn carrying_mul_add<T: ~const fallback::CarryingMulAdd<Unsigned = U>, U>(
2710 multiplier: T,
2711 multiplicand: T,
2712 addend: T,
2713 carry: T,
2714) -> (U, T) {
2715 multiplier.carrying_mul_add(multiplicand, addend, carry)
2716}
2717
2718/// Performs an exact division, resulting in undefined behavior where
2719/// `x % y != 0` or `y == 0` or `x == T::MIN && y == -1`
2720///
2721/// This intrinsic does not have a stable counterpart.
2722#[rustc_intrinsic_const_stable_indirect]
2723#[rustc_nounwind]
2724#[rustc_intrinsic]
2725pub const unsafe fn exact_div<T: Copy>(x: T, y: T) -> T;
2726
2727/// Performs an unchecked division, resulting in undefined behavior
2728/// where `y == 0` or `x == T::MIN && y == -1`
2729///
2730/// Safe wrappers for this intrinsic are available on the integer
2731/// primitives via the `checked_div` method. For example,
2732/// [`u32::checked_div`]
2733#[rustc_intrinsic_const_stable_indirect]
2734#[rustc_nounwind]
2735#[rustc_intrinsic]
2736pub const unsafe fn unchecked_div<T: Copy>(x: T, y: T) -> T;
2737/// Returns the remainder of an unchecked division, resulting in
2738/// undefined behavior when `y == 0` or `x == T::MIN && y == -1`
2739///
2740/// Safe wrappers for this intrinsic are available on the integer
2741/// primitives via the `checked_rem` method. For example,
2742/// [`u32::checked_rem`]
2743#[rustc_intrinsic_const_stable_indirect]
2744#[rustc_nounwind]
2745#[rustc_intrinsic]
2746pub const unsafe fn unchecked_rem<T: Copy>(x: T, y: T) -> T;
2747
2748/// Performs an unchecked left shift, resulting in undefined behavior when
2749/// `y < 0` or `y >= N`, where N is the width of T in bits.
2750///
2751/// Safe wrappers for this intrinsic are available on the integer
2752/// primitives via the `checked_shl` method. For example,
2753/// [`u32::checked_shl`]
2754#[rustc_intrinsic_const_stable_indirect]
2755#[rustc_nounwind]
2756#[rustc_intrinsic]
2757pub const unsafe fn unchecked_shl<T: Copy, U: Copy>(x: T, y: U) -> T;
2758/// Performs an unchecked right shift, resulting in undefined behavior when
2759/// `y < 0` or `y >= N`, where N is the width of T in bits.
2760///
2761/// Safe wrappers for this intrinsic are available on the integer
2762/// primitives via the `checked_shr` method. For example,
2763/// [`u32::checked_shr`]
2764#[rustc_intrinsic_const_stable_indirect]
2765#[rustc_nounwind]
2766#[rustc_intrinsic]
2767pub const unsafe fn unchecked_shr<T: Copy, U: Copy>(x: T, y: U) -> T;
2768
2769/// Returns the result of an unchecked addition, resulting in
2770/// undefined behavior when `x + y > T::MAX` or `x + y < T::MIN`.
2771///
2772/// The stable counterpart of this intrinsic is `unchecked_add` on the various
2773/// integer types, such as [`u16::unchecked_add`] and [`i64::unchecked_add`].
2774#[rustc_intrinsic_const_stable_indirect]
2775#[rustc_nounwind]
2776#[rustc_intrinsic]
2777pub const unsafe fn unchecked_add<T: Copy>(x: T, y: T) -> T;
2778
2779/// Returns the result of an unchecked subtraction, resulting in
2780/// undefined behavior when `x - y > T::MAX` or `x - y < T::MIN`.
2781///
2782/// The stable counterpart of this intrinsic is `unchecked_sub` on the various
2783/// integer types, such as [`u16::unchecked_sub`] and [`i64::unchecked_sub`].
2784#[rustc_intrinsic_const_stable_indirect]
2785#[rustc_nounwind]
2786#[rustc_intrinsic]
2787pub const unsafe fn unchecked_sub<T: Copy>(x: T, y: T) -> T;
2788
2789/// Returns the result of an unchecked multiplication, resulting in
2790/// undefined behavior when `x * y > T::MAX` or `x * y < T::MIN`.
2791///
2792/// The stable counterpart of this intrinsic is `unchecked_mul` on the various
2793/// integer types, such as [`u16::unchecked_mul`] and [`i64::unchecked_mul`].
2794#[rustc_intrinsic_const_stable_indirect]
2795#[rustc_nounwind]
2796#[rustc_intrinsic]
2797pub const unsafe fn unchecked_mul<T: Copy>(x: T, y: T) -> T;
2798
2799/// Performs rotate left.
2800///
2801/// Note that, unlike most intrinsics, this is safe to call;
2802/// it does not require an `unsafe` block.
2803/// Therefore, implementations must not require the user to uphold
2804/// any safety invariants.
2805///
2806/// The stabilized versions of this intrinsic are available on the integer
2807/// primitives via the `rotate_left` method. For example,
2808/// [`u32::rotate_left`]
2809#[rustc_intrinsic_const_stable_indirect]
2810#[rustc_nounwind]
2811#[rustc_intrinsic]
2812pub const fn rotate_left<T: Copy>(x: T, shift: u32) -> T;
2813
2814/// Performs rotate right.
2815///
2816/// Note that, unlike most intrinsics, this is safe to call;
2817/// it does not require an `unsafe` block.
2818/// Therefore, implementations must not require the user to uphold
2819/// any safety invariants.
2820///
2821/// The stabilized versions of this intrinsic are available on the integer
2822/// primitives via the `rotate_right` method. For example,
2823/// [`u32::rotate_right`]
2824#[rustc_intrinsic_const_stable_indirect]
2825#[rustc_nounwind]
2826#[rustc_intrinsic]
2827pub const fn rotate_right<T: Copy>(x: T, shift: u32) -> T;
2828
2829/// Returns (a + b) mod 2<sup>N</sup>, where N is the width of T in bits.
2830///
2831/// Note that, unlike most intrinsics, this is safe to call;
2832/// it does not require an `unsafe` block.
2833/// Therefore, implementations must not require the user to uphold
2834/// any safety invariants.
2835///
2836/// The stabilized versions of this intrinsic are available on the integer
2837/// primitives via the `wrapping_add` method. For example,
2838/// [`u32::wrapping_add`]
2839#[rustc_intrinsic_const_stable_indirect]
2840#[rustc_nounwind]
2841#[rustc_intrinsic]
2842pub const fn wrapping_add<T: Copy>(a: T, b: T) -> T;
2843/// Returns (a - b) mod 2<sup>N</sup>, where N is the width of T in bits.
2844///
2845/// Note that, unlike most intrinsics, this is safe to call;
2846/// it does not require an `unsafe` block.
2847/// Therefore, implementations must not require the user to uphold
2848/// any safety invariants.
2849///
2850/// The stabilized versions of this intrinsic are available on the integer
2851/// primitives via the `wrapping_sub` method. For example,
2852/// [`u32::wrapping_sub`]
2853#[rustc_intrinsic_const_stable_indirect]
2854#[rustc_nounwind]
2855#[rustc_intrinsic]
2856pub const fn wrapping_sub<T: Copy>(a: T, b: T) -> T;
2857/// Returns (a * b) mod 2<sup>N</sup>, where N is the width of T in bits.
2858///
2859/// Note that, unlike most intrinsics, this is safe to call;
2860/// it does not require an `unsafe` block.
2861/// Therefore, implementations must not require the user to uphold
2862/// any safety invariants.
2863///
2864/// The stabilized versions of this intrinsic are available on the integer
2865/// primitives via the `wrapping_mul` method. For example,
2866/// [`u32::wrapping_mul`]
2867#[rustc_intrinsic_const_stable_indirect]
2868#[rustc_nounwind]
2869#[rustc_intrinsic]
2870pub const fn wrapping_mul<T: Copy>(a: T, b: T) -> T;
2871
2872/// Computes `a + b`, saturating at numeric bounds.
2873///
2874/// Note that, unlike most intrinsics, this is safe to call;
2875/// it does not require an `unsafe` block.
2876/// Therefore, implementations must not require the user to uphold
2877/// any safety invariants.
2878///
2879/// The stabilized versions of this intrinsic are available on the integer
2880/// primitives via the `saturating_add` method. For example,
2881/// [`u32::saturating_add`]
2882#[rustc_intrinsic_const_stable_indirect]
2883#[rustc_nounwind]
2884#[rustc_intrinsic]
2885pub const fn saturating_add<T: Copy>(a: T, b: T) -> T;
2886/// Computes `a - b`, saturating at numeric bounds.
2887///
2888/// Note that, unlike most intrinsics, this is safe to call;
2889/// it does not require an `unsafe` block.
2890/// Therefore, implementations must not require the user to uphold
2891/// any safety invariants.
2892///
2893/// The stabilized versions of this intrinsic are available on the integer
2894/// primitives via the `saturating_sub` method. For example,
2895/// [`u32::saturating_sub`]
2896#[rustc_intrinsic_const_stable_indirect]
2897#[rustc_nounwind]
2898#[rustc_intrinsic]
2899pub const fn saturating_sub<T: Copy>(a: T, b: T) -> T;
2900
2901/// This is an implementation detail of [`crate::ptr::read`] and should
2902/// not be used anywhere else. See its comments for why this exists.
2903///
2904/// This intrinsic can *only* be called where the pointer is a local without
2905/// projections (`read_via_copy(ptr)`, not `read_via_copy(*ptr)`) so that it
2906/// trivially obeys runtime-MIR rules about derefs in operands.
2907#[rustc_intrinsic_const_stable_indirect]
2908#[rustc_nounwind]
2909#[rustc_intrinsic]
2910pub const unsafe fn read_via_copy<T>(ptr: *const T) -> T;
2911
2912/// This is an implementation detail of [`crate::ptr::write`] and should
2913/// not be used anywhere else. See its comments for why this exists.
2914///
2915/// This intrinsic can *only* be called where the pointer is a local without
2916/// projections (`write_via_move(ptr, x)`, not `write_via_move(*ptr, x)`) so
2917/// that it trivially obeys runtime-MIR rules about derefs in operands.
2918#[rustc_intrinsic_const_stable_indirect]
2919#[rustc_nounwind]
2920#[rustc_intrinsic]
2921pub const unsafe fn write_via_move<T>(ptr: *mut T, value: T);
2922
2923/// Returns the value of the discriminant for the variant in 'v';
2924/// if `T` has no discriminant, returns `0`.
2925///
2926/// Note that, unlike most intrinsics, this is safe to call;
2927/// it does not require an `unsafe` block.
2928/// Therefore, implementations must not require the user to uphold
2929/// any safety invariants.
2930///
2931/// The stabilized version of this intrinsic is [`core::mem::discriminant`].
2932#[rustc_intrinsic_const_stable_indirect]
2933#[rustc_nounwind]
2934#[rustc_intrinsic]
2935pub const fn discriminant_value<T>(v: &T) -> <T as DiscriminantKind>::Discriminant;
2936
2937/// Rust's "try catch" construct for unwinding. Invokes the function pointer `try_fn` with the
2938/// data pointer `data`, and calls `catch_fn` if unwinding occurs while `try_fn` runs.
2939/// Returns `1` if unwinding occurred and `catch_fn` was called; returns `0` otherwise.
2940///
2941/// `catch_fn` must not unwind.
2942///
2943/// The third argument is a function called if an unwind occurs (both Rust `panic` and foreign
2944/// unwinds). This function takes the data pointer and a pointer to the target- and
2945/// runtime-specific exception object that was caught.
2946///
2947/// Note that in the case of a foreign unwinding operation, the exception object data may not be
2948/// safely usable from Rust, and should not be directly exposed via the standard library. To
2949/// prevent unsafe access, the library implementation may either abort the process or present an
2950/// opaque error type to the user.
2951///
2952/// For more information, see the compiler's source, as well as the documentation for the stable
2953/// version of this intrinsic, `std::panic::catch_unwind`.
2954#[rustc_intrinsic]
2955#[rustc_nounwind]
2956pub unsafe fn catch_unwind(
2957 _try_fn: fn(*mut u8),
2958 _data: *mut u8,
2959 _catch_fn: fn(*mut u8, *mut u8),
2960) -> i32;
2961
2962/// Emits a `nontemporal` store, which gives a hint to the CPU that the data should not be held
2963/// in cache. Except for performance, this is fully equivalent to `ptr.write(val)`.
2964///
2965/// Not all architectures provide such an operation. For instance, x86 does not: while `MOVNT`
2966/// exists, that operation is *not* equivalent to `ptr.write(val)` (`MOVNT` writes can be reordered
2967/// in ways that are not allowed for regular writes).
2968#[rustc_intrinsic]
2969#[rustc_nounwind]
2970pub unsafe fn nontemporal_store<T>(ptr: *mut T, val: T);
2971
2972/// See documentation of `<*const T>::offset_from` for details.
2973#[rustc_intrinsic_const_stable_indirect]
2974#[rustc_nounwind]
2975#[rustc_intrinsic]
2976pub const unsafe fn ptr_offset_from<T>(ptr: *const T, base: *const T) -> isize;
2977
2978/// See documentation of `<*const T>::offset_from_unsigned` for details.
2979#[rustc_nounwind]
2980#[rustc_intrinsic]
2981#[rustc_intrinsic_const_stable_indirect]
2982pub const unsafe fn ptr_offset_from_unsigned<T>(ptr: *const T, base: *const T) -> usize;
2983
2984/// See documentation of `<*const T>::guaranteed_eq` for details.
2985/// Returns `2` if the result is unknown.
2986/// Returns `1` if the pointers are guaranteed equal.
2987/// Returns `0` if the pointers are guaranteed inequal.
2988#[rustc_intrinsic]
2989#[rustc_nounwind]
2990#[rustc_do_not_const_check]
2991#[inline]
2992#[miri::intrinsic_fallback_is_spec]
2993pub const fn ptr_guaranteed_cmp<T>(ptr: *const T, other: *const T) -> u8 {
2994 (ptr == other) as u8
2995}
2996
2997/// Determines whether the raw bytes of the two values are equal.
2998///
2999/// This is particularly handy for arrays, since it allows things like just
3000/// comparing `i96`s instead of forcing `alloca`s for `[6 x i16]`.
3001///
3002/// Above some backend-decided threshold this will emit calls to `memcmp`,
3003/// like slice equality does, instead of causing massive code size.
3004///
3005/// Since this works by comparing the underlying bytes, the actual `T` is
3006/// not particularly important. It will be used for its size and alignment,
3007/// but any validity restrictions will be ignored, not enforced.
3008///
3009/// # Safety
3010///
3011/// It's UB to call this if any of the *bytes* in `*a` or `*b` are uninitialized.
3012/// Note that this is a stricter criterion than just the *values* being
3013/// fully-initialized: if `T` has padding, it's UB to call this intrinsic.
3014///
3015/// At compile-time, it is furthermore UB to call this if any of the bytes
3016/// in `*a` or `*b` have provenance.
3017///
3018/// (The implementation is allowed to branch on the results of comparisons,
3019/// which is UB if any of their inputs are `undef`.)
3020#[rustc_nounwind]
3021#[rustc_intrinsic]
3022pub const unsafe fn raw_eq<T>(a: &T, b: &T) -> bool;
3023
3024/// Lexicographically compare `[left, left + bytes)` and `[right, right + bytes)`
3025/// as unsigned bytes, returning negative if `left` is less, zero if all the
3026/// bytes match, or positive if `left` is greater.
3027///
3028/// This underlies things like `<[u8]>::cmp`, and will usually lower to `memcmp`.
3029///
3030/// # Safety
3031///
3032/// `left` and `right` must each be [valid] for reads of `bytes` bytes.
3033///
3034/// Note that this applies to the whole range, not just until the first byte
3035/// that differs. That allows optimizations that can read in large chunks.
3036///
3037/// [valid]: crate::ptr#safety
3038#[rustc_nounwind]
3039#[rustc_intrinsic]
3040pub const unsafe fn compare_bytes(left: *const u8, right: *const u8, bytes: usize) -> i32;
3041
3042/// See documentation of [`std::hint::black_box`] for details.
3043///
3044/// [`std::hint::black_box`]: crate::hint::black_box
3045#[rustc_nounwind]
3046#[rustc_intrinsic]
3047#[rustc_intrinsic_const_stable_indirect]
3048pub const fn black_box<T>(dummy: T) -> T;
3049
3050/// Selects which function to call depending on the context.
3051///
3052/// If this function is evaluated at compile-time, then a call to this
3053/// intrinsic will be replaced with a call to `called_in_const`. It gets
3054/// replaced with a call to `called_at_rt` otherwise.
3055///
3056/// This function is safe to call, but note the stability concerns below.
3057///
3058/// # Type Requirements
3059///
3060/// The two functions must be both function items. They cannot be function
3061/// pointers or closures. The first function must be a `const fn`.
3062///
3063/// `arg` will be the tupled arguments that will be passed to either one of
3064/// the two functions, therefore, both functions must accept the same type of
3065/// arguments. Both functions must return RET.
3066///
3067/// # Stability concerns
3068///
3069/// Rust has not yet decided that `const fn` are allowed to tell whether
3070/// they run at compile-time or at runtime. Therefore, when using this
3071/// intrinsic anywhere that can be reached from stable, it is crucial that
3072/// the end-to-end behavior of the stable `const fn` is the same for both
3073/// modes of execution. (Here, Undefined Behavior is considered "the same"
3074/// as any other behavior, so if the function exhibits UB at runtime then
3075/// it may do whatever it wants at compile-time.)
3076///
3077/// Here is an example of how this could cause a problem:
3078/// ```no_run
3079/// #![feature(const_eval_select)]
3080/// #![feature(core_intrinsics)]
3081/// # #![allow(internal_features)]
3082/// use std::intrinsics::const_eval_select;
3083///
3084/// // Standard library
3085/// pub const fn inconsistent() -> i32 {
3086/// fn runtime() -> i32 { 1 }
3087/// const fn compiletime() -> i32 { 2 }
3088///
3089/// // ⚠ This code violates the required equivalence of `compiletime`
3090/// // and `runtime`.
3091/// const_eval_select((), compiletime, runtime)
3092/// }
3093///
3094/// // User Crate
3095/// const X: i32 = inconsistent();
3096/// let x = inconsistent();
3097/// assert_eq!(x, X);
3098/// ```
3099///
3100/// Currently such an assertion would always succeed; until Rust decides
3101/// otherwise, that principle should not be violated.
3102#[rustc_const_unstable(feature = "const_eval_select", issue = "124625")]
3103#[rustc_intrinsic]
3104pub const fn const_eval_select<ARG: Tuple, F, G, RET>(
3105 _arg: ARG,
3106 _called_in_const: F,
3107 _called_at_rt: G,
3108) -> RET
3109where
3110 G: FnOnce<ARG, Output = RET>,
3111 F: FnOnce<ARG, Output = RET>;
3112
3113/// A macro to make it easier to invoke const_eval_select. Use as follows:
3114/// ```rust,ignore (just a macro example)
3115/// const_eval_select!(
3116/// @capture { arg1: i32 = some_expr, arg2: T = other_expr } -> U:
3117/// if const #[attributes_for_const_arm] {
3118/// // Compile-time code goes here.
3119/// } else #[attributes_for_runtime_arm] {
3120/// // Run-time code goes here.
3121/// }
3122/// )
3123/// ```
3124/// The `@capture` block declares which surrounding variables / expressions can be
3125/// used inside the `if const`.
3126/// Note that the two arms of this `if` really each become their own function, which is why the
3127/// macro supports setting attributes for those functions. The runtime function is always
3128/// markes as `#[inline]`.
3129///
3130/// See [`const_eval_select()`] for the rules and requirements around that intrinsic.
3131pub(crate) macro const_eval_select {
3132 (
3133 @capture$([$($binders:tt)*])? { $($arg:ident : $ty:ty = $val:expr),* $(,)? } $( -> $ret:ty )? :
3134 if const
3135 $(#[$compiletime_attr:meta])* $compiletime:block
3136 else
3137 $(#[$runtime_attr:meta])* $runtime:block
3138 ) => {
3139 // Use the `noinline` arm, after adding explicit `inline` attributes
3140 $crate::intrinsics::const_eval_select!(
3141 @capture$([$($binders)*])? { $($arg : $ty = $val),* } $(-> $ret)? :
3142 #[noinline]
3143 if const
3144 #[inline] // prevent codegen on this function
3145 $(#[$compiletime_attr])*
3146 $compiletime
3147 else
3148 #[inline] // avoid the overhead of an extra fn call
3149 $(#[$runtime_attr])*
3150 $runtime
3151 )
3152 },
3153 // With a leading #[noinline], we don't add inline attributes
3154 (
3155 @capture$([$($binders:tt)*])? { $($arg:ident : $ty:ty = $val:expr),* $(,)? } $( -> $ret:ty )? :
3156 #[noinline]
3157 if const
3158 $(#[$compiletime_attr:meta])* $compiletime:block
3159 else
3160 $(#[$runtime_attr:meta])* $runtime:block
3161 ) => {{
3162 $(#[$runtime_attr])*
3163 fn runtime$(<$($binders)*>)?($($arg: $ty),*) $( -> $ret )? {
3164 $runtime
3165 }
3166
3167 $(#[$compiletime_attr])*
3168 const fn compiletime$(<$($binders)*>)?($($arg: $ty),*) $( -> $ret )? {
3169 // Don't warn if one of the arguments is unused.
3170 $(let _ = $arg;)*
3171
3172 $compiletime
3173 }
3174
3175 const_eval_select(($($val,)*), compiletime, runtime)
3176 }},
3177 // We support leaving away the `val` expressions for *all* arguments
3178 // (but not for *some* arguments, that's too tricky).
3179 (
3180 @capture$([$($binders:tt)*])? { $($arg:ident : $ty:ty),* $(,)? } $( -> $ret:ty )? :
3181 if const
3182 $(#[$compiletime_attr:meta])* $compiletime:block
3183 else
3184 $(#[$runtime_attr:meta])* $runtime:block
3185 ) => {
3186 $crate::intrinsics::const_eval_select!(
3187 @capture$([$($binders)*])? { $($arg : $ty = $arg),* } $(-> $ret)? :
3188 if const
3189 $(#[$compiletime_attr])* $compiletime
3190 else
3191 $(#[$runtime_attr])* $runtime
3192 )
3193 },
3194}
3195
3196/// Returns whether the argument's value is statically known at
3197/// compile-time.
3198///
3199/// This is useful when there is a way of writing the code that will
3200/// be *faster* when some variables have known values, but *slower*
3201/// in the general case: an `if is_val_statically_known(var)` can be used
3202/// to select between these two variants. The `if` will be optimized away
3203/// and only the desired branch remains.
3204///
3205/// Formally speaking, this function non-deterministically returns `true`
3206/// or `false`, and the caller has to ensure sound behavior for both cases.
3207/// In other words, the following code has *Undefined Behavior*:
3208///
3209/// ```no_run
3210/// #![feature(core_intrinsics)]
3211/// # #![allow(internal_features)]
3212/// use std::hint::unreachable_unchecked;
3213/// use std::intrinsics::is_val_statically_known;
3214///
3215/// if !is_val_statically_known(0) { unsafe { unreachable_unchecked(); } }
3216/// ```
3217///
3218/// This also means that the following code's behavior is unspecified; it
3219/// may panic, or it may not:
3220///
3221/// ```no_run
3222/// #![feature(core_intrinsics)]
3223/// # #![allow(internal_features)]
3224/// use std::intrinsics::is_val_statically_known;
3225///
3226/// assert_eq!(is_val_statically_known(0), is_val_statically_known(0));
3227/// ```
3228///
3229/// Unsafe code may not rely on `is_val_statically_known` returning any
3230/// particular value, ever. However, the compiler will generally make it
3231/// return `true` only if the value of the argument is actually known.
3232///
3233/// # Stability concerns
3234///
3235/// While it is safe to call, this intrinsic may behave differently in
3236/// a `const` context than otherwise. See the [`const_eval_select()`]
3237/// documentation for an explanation of the issues this can cause. Unlike
3238/// `const_eval_select`, this intrinsic isn't guaranteed to behave
3239/// deterministically even in a `const` context.
3240///
3241/// # Type Requirements
3242///
3243/// `T` must be either a `bool`, a `char`, a primitive numeric type (e.g. `f32`,
3244/// but not `NonZeroISize`), or any thin pointer (e.g. `*mut String`).
3245/// Any other argument types *may* cause a compiler error.
3246///
3247/// ## Pointers
3248///
3249/// When the input is a pointer, only the pointer itself is
3250/// ever considered. The pointee has no effect. Currently, these functions
3251/// behave identically:
3252///
3253/// ```
3254/// #![feature(core_intrinsics)]
3255/// # #![allow(internal_features)]
3256/// use std::intrinsics::is_val_statically_known;
3257///
3258/// fn foo(x: &i32) -> bool {
3259/// is_val_statically_known(x)
3260/// }
3261///
3262/// fn bar(x: &i32) -> bool {
3263/// is_val_statically_known(
3264/// (x as *const i32).addr()
3265/// )
3266/// }
3267/// # _ = foo(&5_i32);
3268/// # _ = bar(&5_i32);
3269/// ```
3270#[rustc_const_stable_indirect]
3271#[rustc_nounwind]
3272#[unstable(feature = "core_intrinsics", issue = "none")]
3273#[rustc_intrinsic]
3274pub const fn is_val_statically_known<T: Copy>(_arg: T) -> bool {
3275 false
3276}
3277
3278/// Non-overlapping *typed* swap of a single value.
3279///
3280/// The codegen backends will replace this with a better implementation when
3281/// `T` is a simple type that can be loaded and stored as an immediate.
3282///
3283/// The stabilized form of this intrinsic is [`crate::mem::swap`].
3284///
3285/// # Safety
3286/// Behavior is undefined if any of the following conditions are violated:
3287///
3288/// * Both `x` and `y` must be [valid] for both reads and writes.
3289///
3290/// * Both `x` and `y` must be properly aligned.
3291///
3292/// * The region of memory beginning at `x` must *not* overlap with the region of memory
3293/// beginning at `y`.
3294///
3295/// * The memory pointed by `x` and `y` must both contain values of type `T`.
3296///
3297/// [valid]: crate::ptr#safety
3298#[rustc_nounwind]
3299#[inline]
3300#[rustc_intrinsic]
3301#[rustc_intrinsic_const_stable_indirect]
3302pub const unsafe fn typed_swap_nonoverlapping<T>(x: *mut T, y: *mut T) {
3303 // SAFETY: The caller provided single non-overlapping items behind
3304 // pointers, so swapping them with `count: 1` is fine.
3305 unsafe { ptr::swap_nonoverlapping(x, y, 1) };
3306}
3307
3308/// Returns whether we should perform some UB-checking at runtime. This eventually evaluates to
3309/// `cfg!(ub_checks)`, but behaves different from `cfg!` when mixing crates built with different
3310/// flags: if the crate has UB checks enabled or carries the `#[rustc_preserve_ub_checks]`
3311/// attribute, evaluation is delayed until monomorphization (or until the call gets inlined into
3312/// a crate that does not delay evaluation further); otherwise it can happen any time.
3313///
3314/// The common case here is a user program built with ub_checks linked against the distributed
3315/// sysroot which is built without ub_checks but with `#[rustc_preserve_ub_checks]`.
3316/// For code that gets monomorphized in the user crate (i.e., generic functions and functions with
3317/// `#[inline]`), gating assertions on `ub_checks()` rather than `cfg!(ub_checks)` means that
3318/// assertions are enabled whenever the *user crate* has UB checks enabled. However, if the
3319/// user has UB checks disabled, the checks will still get optimized out. This intrinsic is
3320/// primarily used by [`ub_checks::assert_unsafe_precondition`].
3321#[rustc_intrinsic_const_stable_indirect] // just for UB checks
3322#[inline(always)]
3323#[rustc_intrinsic]
3324pub const fn ub_checks() -> bool {
3325 cfg!(ub_checks)
3326}
3327
3328/// Allocates a block of memory at compile time.
3329/// At runtime, just returns a null pointer.
3330///
3331/// # Safety
3332///
3333/// - The `align` argument must be a power of two.
3334/// - At compile time, a compile error occurs if this constraint is violated.
3335/// - At runtime, it is not checked.
3336#[rustc_const_unstable(feature = "const_heap", issue = "79597")]
3337#[rustc_nounwind]
3338#[rustc_intrinsic]
3339#[miri::intrinsic_fallback_is_spec]
3340pub const unsafe fn const_allocate(_size: usize, _align: usize) -> *mut u8 {
3341 // const eval overrides this function, but runtime code for now just returns null pointers.
3342 // See <https://github.com/rust-lang/rust/issues/93935>.
3343 crate::ptr::null_mut()
3344}
3345
3346/// Deallocates a memory which allocated by `intrinsics::const_allocate` at compile time.
3347/// At runtime, does nothing.
3348///
3349/// # Safety
3350///
3351/// - The `align` argument must be a power of two.
3352/// - At compile time, a compile error occurs if this constraint is violated.
3353/// - At runtime, it is not checked.
3354/// - If the `ptr` is created in an another const, this intrinsic doesn't deallocate it.
3355/// - If the `ptr` is pointing to a local variable, this intrinsic doesn't deallocate it.
3356#[rustc_const_unstable(feature = "const_heap", issue = "79597")]
3357#[unstable(feature = "core_intrinsics", issue = "none")]
3358#[rustc_nounwind]
3359#[rustc_intrinsic]
3360#[miri::intrinsic_fallback_is_spec]
3361pub const unsafe fn const_deallocate(_ptr: *mut u8, _size: usize, _align: usize) {
3362 // Runtime NOP
3363}
3364
3365/// Returns whether we should perform contract-checking at runtime.
3366///
3367/// This is meant to be similar to the ub_checks intrinsic, in terms
3368/// of not prematurely commiting at compile-time to whether contract
3369/// checking is turned on, so that we can specify contracts in libstd
3370/// and let an end user opt into turning them on.
3371#[rustc_const_unstable(feature = "contracts_internals", issue = "128044" /* compiler-team#759 */)]
3372#[unstable(feature = "contracts_internals", issue = "128044" /* compiler-team#759 */)]
3373#[inline(always)]
3374#[rustc_intrinsic]
3375pub const fn contract_checks() -> bool {
3376 // FIXME: should this be `false` or `cfg!(contract_checks)`?
3377
3378 // cfg!(contract_checks)
3379 false
3380}
3381
3382/// Check if the pre-condition `cond` has been met.
3383///
3384/// By default, if `contract_checks` is enabled, this will panic with no unwind if the condition
3385/// returns false.
3386///
3387/// Note that this function is a no-op during constant evaluation.
3388#[unstable(feature = "contracts_internals", issue = "128044")]
3389// Calls to this function get inserted by an AST expansion pass, which uses the equivalent of
3390// `#[allow_internal_unstable]` to allow using `contracts_internals` functions. Const-checking
3391// doesn't honor `#[allow_internal_unstable]`, so for the const feature gate we use the user-facing
3392// `contracts` feature rather than the perma-unstable `contracts_internals`
3393#[rustc_const_unstable(feature = "contracts", issue = "128044")]
3394#[lang = "contract_check_requires"]
3395#[rustc_intrinsic]
3396pub const fn contract_check_requires<C: Fn() -> bool + Copy>(cond: C) {
3397 const_eval_select!(
3398 @capture[C: Fn() -> bool + Copy] { cond: C } :
3399 if const {
3400 // Do nothing
3401 } else {
3402 if contract_checks() && !cond() {
3403 // Emit no unwind panic in case this was a safety requirement.
3404 crate::panicking::panic_nounwind("failed requires check");
3405 }
3406 }
3407 )
3408}
3409
3410/// Check if the post-condition `cond` has been met.
3411///
3412/// By default, if `contract_checks` is enabled, this will panic with no unwind if the condition
3413/// returns false.
3414///
3415/// Note that this function is a no-op during constant evaluation.
3416#[unstable(feature = "contracts_internals", issue = "128044")]
3417// Similar to `contract_check_requires`, we need to use the user-facing
3418// `contracts` feature rather than the perma-unstable `contracts_internals`.
3419// Const-checking doesn't honor allow_internal_unstable logic used by contract expansion.
3420#[rustc_const_unstable(feature = "contracts", issue = "128044")]
3421#[lang = "contract_check_ensures"]
3422#[rustc_intrinsic]
3423pub const fn contract_check_ensures<C: Fn(&Ret) -> bool + Copy, Ret>(cond: C, ret: Ret) -> Ret {
3424 const_eval_select!(
3425 @capture[C: Fn(&Ret) -> bool + Copy, Ret] { cond: C, ret: Ret } -> Ret :
3426 if const {
3427 // Do nothing
3428 ret
3429 } else {
3430 if contract_checks() && !cond(&ret) {
3431 // Emit no unwind panic in case this was a safety requirement.
3432 crate::panicking::panic_nounwind("failed ensures check");
3433 }
3434 ret
3435 }
3436 )
3437}
3438
3439/// The intrinsic will return the size stored in that vtable.
3440///
3441/// # Safety
3442///
3443/// `ptr` must point to a vtable.
3444#[rustc_nounwind]
3445#[unstable(feature = "core_intrinsics", issue = "none")]
3446#[rustc_intrinsic]
3447pub unsafe fn vtable_size(ptr: *const ()) -> usize;
3448
3449/// The intrinsic will return the alignment stored in that vtable.
3450///
3451/// # Safety
3452///
3453/// `ptr` must point to a vtable.
3454#[rustc_nounwind]
3455#[unstable(feature = "core_intrinsics", issue = "none")]
3456#[rustc_intrinsic]
3457pub unsafe fn vtable_align(ptr: *const ()) -> usize;
3458
3459/// The size of a type in bytes.
3460///
3461/// Note that, unlike most intrinsics, this is safe to call;
3462/// it does not require an `unsafe` block.
3463/// Therefore, implementations must not require the user to uphold
3464/// any safety invariants.
3465///
3466/// More specifically, this is the offset in bytes between successive
3467/// items of the same type, including alignment padding.
3468///
3469/// The stabilized version of this intrinsic is [`size_of`].
3470#[rustc_nounwind]
3471#[unstable(feature = "core_intrinsics", issue = "none")]
3472#[rustc_intrinsic_const_stable_indirect]
3473#[rustc_intrinsic]
3474pub const fn size_of<T>() -> usize;
3475
3476/// The minimum alignment of a type.
3477///
3478/// Note that, unlike most intrinsics, this is safe to call;
3479/// it does not require an `unsafe` block.
3480/// Therefore, implementations must not require the user to uphold
3481/// any safety invariants.
3482///
3483/// The stabilized version of this intrinsic is [`align_of`].
3484#[rustc_nounwind]
3485#[unstable(feature = "core_intrinsics", issue = "none")]
3486#[rustc_intrinsic_const_stable_indirect]
3487#[rustc_intrinsic]
3488pub const fn min_align_of<T>() -> usize;
3489
3490/// The preferred alignment of a type.
3491///
3492/// This intrinsic does not have a stable counterpart.
3493/// It's "tracking issue" is [#91971](https://github.com/rust-lang/rust/issues/91971).
3494#[rustc_nounwind]
3495#[unstable(feature = "core_intrinsics", issue = "none")]
3496#[rustc_intrinsic]
3497pub const unsafe fn pref_align_of<T>() -> usize;
3498
3499/// Returns the number of variants of the type `T` cast to a `usize`;
3500/// if `T` has no variants, returns `0`. Uninhabited variants will be counted.
3501///
3502/// Note that, unlike most intrinsics, this is safe to call;
3503/// it does not require an `unsafe` block.
3504/// Therefore, implementations must not require the user to uphold
3505/// any safety invariants.
3506///
3507/// The to-be-stabilized version of this intrinsic is [`crate::mem::variant_count`].
3508#[rustc_nounwind]
3509#[unstable(feature = "core_intrinsics", issue = "none")]
3510#[rustc_intrinsic]
3511pub const fn variant_count<T>() -> usize;
3512
3513/// The size of the referenced value in bytes.
3514///
3515/// The stabilized version of this intrinsic is [`size_of_val`].
3516///
3517/// # Safety
3518///
3519/// See [`crate::mem::size_of_val_raw`] for safety conditions.
3520#[rustc_nounwind]
3521#[unstable(feature = "core_intrinsics", issue = "none")]
3522#[rustc_intrinsic]
3523#[rustc_intrinsic_const_stable_indirect]
3524pub const unsafe fn size_of_val<T: ?Sized>(ptr: *const T) -> usize;
3525
3526/// The required alignment of the referenced value.
3527///
3528/// The stabilized version of this intrinsic is [`align_of_val`].
3529///
3530/// # Safety
3531///
3532/// See [`crate::mem::align_of_val_raw`] for safety conditions.
3533#[rustc_nounwind]
3534#[unstable(feature = "core_intrinsics", issue = "none")]
3535#[rustc_intrinsic]
3536#[rustc_intrinsic_const_stable_indirect]
3537pub const unsafe fn min_align_of_val<T: ?Sized>(ptr: *const T) -> usize;
3538
3539/// Gets a static string slice containing the name of a type.
3540///
3541/// Note that, unlike most intrinsics, this is safe to call;
3542/// it does not require an `unsafe` block.
3543/// Therefore, implementations must not require the user to uphold
3544/// any safety invariants.
3545///
3546/// The stabilized version of this intrinsic is [`core::any::type_name`].
3547#[rustc_nounwind]
3548#[unstable(feature = "core_intrinsics", issue = "none")]
3549#[rustc_intrinsic]
3550pub const fn type_name<T: ?Sized>() -> &'static str;
3551
3552/// Gets an identifier which is globally unique to the specified type. This
3553/// function will return the same value for a type regardless of whichever
3554/// crate it is invoked in.
3555///
3556/// Note that, unlike most intrinsics, this is safe to call;
3557/// it does not require an `unsafe` block.
3558/// Therefore, implementations must not require the user to uphold
3559/// any safety invariants.
3560///
3561/// The stabilized version of this intrinsic is [`core::any::TypeId::of`].
3562#[rustc_nounwind]
3563#[unstable(feature = "core_intrinsics", issue = "none")]
3564#[rustc_intrinsic]
3565pub const fn type_id<T: ?Sized + 'static>() -> u128;
3566
3567/// Lowers in MIR to `Rvalue::Aggregate` with `AggregateKind::RawPtr`.
3568///
3569/// This is used to implement functions like `slice::from_raw_parts_mut` and
3570/// `ptr::from_raw_parts` in a way compatible with the compiler being able to
3571/// change the possible layouts of pointers.
3572#[rustc_nounwind]
3573#[unstable(feature = "core_intrinsics", issue = "none")]
3574#[rustc_intrinsic_const_stable_indirect]
3575#[rustc_intrinsic]
3576pub const fn aggregate_raw_ptr<P: AggregateRawPtr<D, Metadata = M>, D, M>(data: D, meta: M) -> P;
3577
3578#[unstable(feature = "core_intrinsics", issue = "none")]
3579pub trait AggregateRawPtr<D> {
3580 type Metadata: Copy;
3581}
3582impl<P: ?Sized, T: ptr::Thin> AggregateRawPtr<*const T> for *const P {
3583 type Metadata = <P as ptr::Pointee>::Metadata;
3584}
3585impl<P: ?Sized, T: ptr::Thin> AggregateRawPtr<*mut T> for *mut P {
3586 type Metadata = <P as ptr::Pointee>::Metadata;
3587}
3588
3589/// Lowers in MIR to `Rvalue::UnaryOp` with `UnOp::PtrMetadata`.
3590///
3591/// This is used to implement functions like `ptr::metadata`.
3592#[rustc_nounwind]
3593#[unstable(feature = "core_intrinsics", issue = "none")]
3594#[rustc_intrinsic_const_stable_indirect]
3595#[rustc_intrinsic]
3596pub const fn ptr_metadata<P: ptr::Pointee<Metadata = M> + ?Sized, M>(ptr: *const P) -> M;
3597
3598// Some functions are defined here because they accidentally got made
3599// available in this module on stable. See <https://github.com/rust-lang/rust/issues/15702>.
3600// (`transmute` also falls into this category, but it cannot be wrapped due to the
3601// check that `T` and `U` have the same size.)
3602
3603/// Copies `count * size_of::<T>()` bytes from `src` to `dst`. The source
3604/// and destination must *not* overlap.
3605///
3606/// For regions of memory which might overlap, use [`copy`] instead.
3607///
3608/// `copy_nonoverlapping` is semantically equivalent to C's [`memcpy`], but
3609/// with the source and destination arguments swapped,
3610/// and `count` counting the number of `T`s instead of bytes.
3611///
3612/// The copy is "untyped" in the sense that data may be uninitialized or otherwise violate the
3613/// requirements of `T`. The initialization state is preserved exactly.
3614///
3615/// [`memcpy`]: https://en.cppreference.com/w/c/string/byte/memcpy
3616///
3617/// # Safety
3618///
3619/// Behavior is undefined if any of the following conditions are violated:
3620///
3621/// * `src` must be [valid] for reads of `count * size_of::<T>()` bytes.
3622///
3623/// * `dst` must be [valid] for writes of `count * size_of::<T>()` bytes.
3624///
3625/// * Both `src` and `dst` must be properly aligned.
3626///
3627/// * The region of memory beginning at `src` with a size of `count *
3628/// size_of::<T>()` bytes must *not* overlap with the region of memory
3629/// beginning at `dst` with the same size.
3630///
3631/// Like [`read`], `copy_nonoverlapping` creates a bitwise copy of `T`, regardless of
3632/// whether `T` is [`Copy`]. If `T` is not [`Copy`], using *both* the values
3633/// in the region beginning at `*src` and the region beginning at `*dst` can
3634/// [violate memory safety][read-ownership].
3635///
3636/// Note that even if the effectively copied size (`count * size_of::<T>()`) is
3637/// `0`, the pointers must be properly aligned.
3638///
3639/// [`read`]: crate::ptr::read
3640/// [read-ownership]: crate::ptr::read#ownership-of-the-returned-value
3641/// [valid]: crate::ptr#safety
3642///
3643/// # Examples
3644///
3645/// Manually implement [`Vec::append`]:
3646///
3647/// ```
3648/// use std::ptr;
3649///
3650/// /// Moves all the elements of `src` into `dst`, leaving `src` empty.
3651/// fn append<T>(dst: &mut Vec<T>, src: &mut Vec<T>) {
3652/// let src_len = src.len();
3653/// let dst_len = dst.len();
3654///
3655/// // Ensure that `dst` has enough capacity to hold all of `src`.
3656/// dst.reserve(src_len);
3657///
3658/// unsafe {
3659/// // The call to add is always safe because `Vec` will never
3660/// // allocate more than `isize::MAX` bytes.
3661/// let dst_ptr = dst.as_mut_ptr().add(dst_len);
3662/// let src_ptr = src.as_ptr();
3663///
3664/// // Truncate `src` without dropping its contents. We do this first,
3665/// // to avoid problems in case something further down panics.
3666/// src.set_len(0);
3667///
3668/// // The two regions cannot overlap because mutable references do
3669/// // not alias, and two different vectors cannot own the same
3670/// // memory.
3671/// ptr::copy_nonoverlapping(src_ptr, dst_ptr, src_len);
3672///
3673/// // Notify `dst` that it now holds the contents of `src`.
3674/// dst.set_len(dst_len + src_len);
3675/// }
3676/// }
3677///
3678/// let mut a = vec!['r'];
3679/// let mut b = vec!['u', 's', 't'];
3680///
3681/// append(&mut a, &mut b);
3682///
3683/// assert_eq!(a, &['r', 'u', 's', 't']);
3684/// assert!(b.is_empty());
3685/// ```
3686///
3687/// [`Vec::append`]: ../../std/vec/struct.Vec.html#method.append
3688#[doc(alias = "memcpy")]
3689#[stable(feature = "rust1", since = "1.0.0")]
3690#[rustc_allowed_through_unstable_modules = "import this function via `std::ptr` instead"]
3691#[rustc_const_stable(feature = "const_intrinsic_copy", since = "1.83.0")]
3692#[inline(always)]
3693#[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
3694#[rustc_diagnostic_item = "ptr_copy_nonoverlapping"]
3695pub const unsafe fn copy_nonoverlapping<T>(src: *const T, dst: *mut T, count: usize) {
3696 #[rustc_intrinsic_const_stable_indirect]
3697 #[rustc_nounwind]
3698 #[rustc_intrinsic]
3699 const unsafe fn copy_nonoverlapping<T>(src: *const T, dst: *mut T, count: usize);
3700
3701 ub_checks::assert_unsafe_precondition!(
3702 check_language_ub,
3703 "ptr::copy_nonoverlapping requires that both pointer arguments are aligned and non-null \
3704 and the specified memory ranges do not overlap",
3705 (
3706 src: *const () = src as *const (),
3707 dst: *mut () = dst as *mut (),
3708 size: usize = size_of::<T>(),
3709 align: usize = align_of::<T>(),
3710 count: usize = count,
3711 ) => {
3712 let zero_size = count == 0 || size == 0;
3713 ub_checks::maybe_is_aligned_and_not_null(src, align, zero_size)
3714 && ub_checks::maybe_is_aligned_and_not_null(dst, align, zero_size)
3715 && ub_checks::maybe_is_nonoverlapping(src, dst, size, count)
3716 }
3717 );
3718
3719 // SAFETY: the safety contract for `copy_nonoverlapping` must be
3720 // upheld by the caller.
3721 unsafe { copy_nonoverlapping(src, dst, count) }
3722}
3723
3724/// Copies `count * size_of::<T>()` bytes from `src` to `dst`. The source
3725/// and destination may overlap.
3726///
3727/// If the source and destination will *never* overlap,
3728/// [`copy_nonoverlapping`] can be used instead.
3729///
3730/// `copy` is semantically equivalent to C's [`memmove`], but
3731/// with the source and destination arguments swapped,
3732/// and `count` counting the number of `T`s instead of bytes.
3733/// Copying takes place as if the bytes were copied from `src`
3734/// to a temporary array and then copied from the array to `dst`.
3735///
3736/// The copy is "untyped" in the sense that data may be uninitialized or otherwise violate the
3737/// requirements of `T`. The initialization state is preserved exactly.
3738///
3739/// [`memmove`]: https://en.cppreference.com/w/c/string/byte/memmove
3740///
3741/// # Safety
3742///
3743/// Behavior is undefined if any of the following conditions are violated:
3744///
3745/// * `src` must be [valid] for reads of `count * size_of::<T>()` bytes.
3746///
3747/// * `dst` must be [valid] for writes of `count * size_of::<T>()` bytes, and must remain valid even
3748/// when `src` is read for `count * size_of::<T>()` bytes. (This means if the memory ranges
3749/// overlap, the `dst` pointer must not be invalidated by `src` reads.)
3750///
3751/// * Both `src` and `dst` must be properly aligned.
3752///
3753/// Like [`read`], `copy` creates a bitwise copy of `T`, regardless of
3754/// whether `T` is [`Copy`]. If `T` is not [`Copy`], using both the values
3755/// in the region beginning at `*src` and the region beginning at `*dst` can
3756/// [violate memory safety][read-ownership].
3757///
3758/// Note that even if the effectively copied size (`count * size_of::<T>()`) is
3759/// `0`, the pointers must be properly aligned.
3760///
3761/// [`read`]: crate::ptr::read
3762/// [read-ownership]: crate::ptr::read#ownership-of-the-returned-value
3763/// [valid]: crate::ptr#safety
3764///
3765/// # Examples
3766///
3767/// Efficiently create a Rust vector from an unsafe buffer:
3768///
3769/// ```
3770/// use std::ptr;
3771///
3772/// /// # Safety
3773/// ///
3774/// /// * `ptr` must be correctly aligned for its type and non-zero.
3775/// /// * `ptr` must be valid for reads of `elts` contiguous elements of type `T`.
3776/// /// * Those elements must not be used after calling this function unless `T: Copy`.
3777/// # #[allow(dead_code)]
3778/// unsafe fn from_buf_raw<T>(ptr: *const T, elts: usize) -> Vec<T> {
3779/// let mut dst = Vec::with_capacity(elts);
3780///
3781/// // SAFETY: Our precondition ensures the source is aligned and valid,
3782/// // and `Vec::with_capacity` ensures that we have usable space to write them.
3783/// unsafe { ptr::copy(ptr, dst.as_mut_ptr(), elts); }
3784///
3785/// // SAFETY: We created it with this much capacity earlier,
3786/// // and the previous `copy` has initialized these elements.
3787/// unsafe { dst.set_len(elts); }
3788/// dst
3789/// }
3790/// ```
3791#[doc(alias = "memmove")]
3792#[stable(feature = "rust1", since = "1.0.0")]
3793#[rustc_allowed_through_unstable_modules = "import this function via `std::ptr` instead"]
3794#[rustc_const_stable(feature = "const_intrinsic_copy", since = "1.83.0")]
3795#[inline(always)]
3796#[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
3797#[rustc_diagnostic_item = "ptr_copy"]
3798pub const unsafe fn copy<T>(src: *const T, dst: *mut T, count: usize) {
3799 #[rustc_intrinsic_const_stable_indirect]
3800 #[rustc_nounwind]
3801 #[rustc_intrinsic]
3802 const unsafe fn copy<T>(src: *const T, dst: *mut T, count: usize);
3803
3804 // SAFETY: the safety contract for `copy` must be upheld by the caller.
3805 unsafe {
3806 ub_checks::assert_unsafe_precondition!(
3807 check_language_ub,
3808 "ptr::copy requires that both pointer arguments are aligned and non-null",
3809 (
3810 src: *const () = src as *const (),
3811 dst: *mut () = dst as *mut (),
3812 align: usize = align_of::<T>(),
3813 zero_size: bool = T::IS_ZST || count == 0,
3814 ) =>
3815 ub_checks::maybe_is_aligned_and_not_null(src, align, zero_size)
3816 && ub_checks::maybe_is_aligned_and_not_null(dst, align, zero_size)
3817 );
3818 copy(src, dst, count)
3819 }
3820}
3821
3822/// Sets `count * size_of::<T>()` bytes of memory starting at `dst` to
3823/// `val`.
3824///
3825/// `write_bytes` is similar to C's [`memset`], but sets `count *
3826/// size_of::<T>()` bytes to `val`.
3827///
3828/// [`memset`]: https://en.cppreference.com/w/c/string/byte/memset
3829///
3830/// # Safety
3831///
3832/// Behavior is undefined if any of the following conditions are violated:
3833///
3834/// * `dst` must be [valid] for writes of `count * size_of::<T>()` bytes.
3835///
3836/// * `dst` must be properly aligned.
3837///
3838/// Note that even if the effectively copied size (`count * size_of::<T>()`) is
3839/// `0`, the pointer must be properly aligned.
3840///
3841/// Additionally, note that changing `*dst` in this way can easily lead to undefined behavior (UB)
3842/// later if the written bytes are not a valid representation of some `T`. For instance, the
3843/// following is an **incorrect** use of this function:
3844///
3845/// ```rust,no_run
3846/// unsafe {
3847/// let mut value: u8 = 0;
3848/// let ptr: *mut bool = &mut value as *mut u8 as *mut bool;
3849/// let _bool = ptr.read(); // This is fine, `ptr` points to a valid `bool`.
3850/// ptr.write_bytes(42u8, 1); // This function itself does not cause UB...
3851/// let _bool = ptr.read(); // ...but it makes this operation UB! ⚠️
3852/// }
3853/// ```
3854///
3855/// [valid]: crate::ptr#safety
3856///
3857/// # Examples
3858///
3859/// Basic usage:
3860///
3861/// ```
3862/// use std::ptr;
3863///
3864/// let mut vec = vec![0u32; 4];
3865/// unsafe {
3866/// let vec_ptr = vec.as_mut_ptr();
3867/// ptr::write_bytes(vec_ptr, 0xfe, 2);
3868/// }
3869/// assert_eq!(vec, [0xfefefefe, 0xfefefefe, 0, 0]);
3870/// ```
3871#[doc(alias = "memset")]
3872#[stable(feature = "rust1", since = "1.0.0")]
3873#[rustc_allowed_through_unstable_modules = "import this function via `std::ptr` instead"]
3874#[rustc_const_stable(feature = "const_ptr_write", since = "1.83.0")]
3875#[inline(always)]
3876#[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
3877#[rustc_diagnostic_item = "ptr_write_bytes"]
3878pub const unsafe fn write_bytes<T>(dst: *mut T, val: u8, count: usize) {
3879 #[rustc_intrinsic_const_stable_indirect]
3880 #[rustc_nounwind]
3881 #[rustc_intrinsic]
3882 const unsafe fn write_bytes<T>(dst: *mut T, val: u8, count: usize);
3883
3884 // SAFETY: the safety contract for `write_bytes` must be upheld by the caller.
3885 unsafe {
3886 ub_checks::assert_unsafe_precondition!(
3887 check_language_ub,
3888 "ptr::write_bytes requires that the destination pointer is aligned and non-null",
3889 (
3890 addr: *const () = dst as *const (),
3891 align: usize = align_of::<T>(),
3892 zero_size: bool = T::IS_ZST || count == 0,
3893 ) => ub_checks::maybe_is_aligned_and_not_null(addr, align, zero_size)
3894 );
3895 write_bytes(dst, val, count)
3896 }
3897}
3898
3899/// Returns the minimum (IEEE 754-2008 minNum) of two `f16` values.
3900///
3901/// Note that, unlike most intrinsics, this is safe to call;
3902/// it does not require an `unsafe` block.
3903/// Therefore, implementations must not require the user to uphold
3904/// any safety invariants.
3905///
3906/// The stabilized version of this intrinsic is
3907/// [`f16::min`]
3908#[rustc_nounwind]
3909#[rustc_intrinsic]
3910pub const fn minnumf16(x: f16, y: f16) -> f16;
3911
3912/// Returns the minimum (IEEE 754-2008 minNum) of two `f32` values.
3913///
3914/// Note that, unlike most intrinsics, this is safe to call;
3915/// it does not require an `unsafe` block.
3916/// Therefore, implementations must not require the user to uphold
3917/// any safety invariants.
3918///
3919/// The stabilized version of this intrinsic is
3920/// [`f32::min`]
3921#[rustc_nounwind]
3922#[rustc_intrinsic_const_stable_indirect]
3923#[rustc_intrinsic]
3924pub const fn minnumf32(x: f32, y: f32) -> f32;
3925
3926/// Returns the minimum (IEEE 754-2008 minNum) of two `f64` values.
3927///
3928/// Note that, unlike most intrinsics, this is safe to call;
3929/// it does not require an `unsafe` block.
3930/// Therefore, implementations must not require the user to uphold
3931/// any safety invariants.
3932///
3933/// The stabilized version of this intrinsic is
3934/// [`f64::min`]
3935#[rustc_nounwind]
3936#[rustc_intrinsic_const_stable_indirect]
3937#[rustc_intrinsic]
3938pub const fn minnumf64(x: f64, y: f64) -> f64;
3939
3940/// Returns the minimum (IEEE 754-2008 minNum) of two `f128` values.
3941///
3942/// Note that, unlike most intrinsics, this is safe to call;
3943/// it does not require an `unsafe` block.
3944/// Therefore, implementations must not require the user to uphold
3945/// any safety invariants.
3946///
3947/// The stabilized version of this intrinsic is
3948/// [`f128::min`]
3949#[rustc_nounwind]
3950#[rustc_intrinsic]
3951pub const fn minnumf128(x: f128, y: f128) -> f128;
3952
3953/// Returns the minimum (IEEE 754-2019 minimum) of two `f16` values.
3954///
3955/// Note that, unlike most intrinsics, this is safe to call;
3956/// it does not require an `unsafe` block.
3957/// Therefore, implementations must not require the user to uphold
3958/// any safety invariants.
3959#[rustc_nounwind]
3960#[cfg_attr(not(bootstrap), rustc_intrinsic)]
3961pub const fn minimumf16(x: f16, y: f16) -> f16 {
3962 if x < y {
3963 x
3964 } else if y < x {
3965 y
3966 } else if x == y {
3967 if x.is_sign_negative() && y.is_sign_positive() { x } else { y }
3968 } else {
3969 // At least one input is NaN. Use `+` to perform NaN propagation and quieting.
3970 x + y
3971 }
3972}
3973
3974/// Returns the minimum (IEEE 754-2019 minimum) of two `f32` values.
3975///
3976/// Note that, unlike most intrinsics, this is safe to call;
3977/// it does not require an `unsafe` block.
3978/// Therefore, implementations must not require the user to uphold
3979/// any safety invariants.
3980#[rustc_nounwind]
3981#[cfg_attr(not(bootstrap), rustc_intrinsic)]
3982pub const fn minimumf32(x: f32, y: f32) -> f32 {
3983 if x < y {
3984 x
3985 } else if y < x {
3986 y
3987 } else if x == y {
3988 if x.is_sign_negative() && y.is_sign_positive() { x } else { y }
3989 } else {
3990 // At least one input is NaN. Use `+` to perform NaN propagation and quieting.
3991 x + y
3992 }
3993}
3994
3995/// Returns the minimum (IEEE 754-2019 minimum) of two `f64` values.
3996///
3997/// Note that, unlike most intrinsics, this is safe to call;
3998/// it does not require an `unsafe` block.
3999/// Therefore, implementations must not require the user to uphold
4000/// any safety invariants.
4001#[rustc_nounwind]
4002#[cfg_attr(not(bootstrap), rustc_intrinsic)]
4003pub const fn minimumf64(x: f64, y: f64) -> f64 {
4004 if x < y {
4005 x
4006 } else if y < x {
4007 y
4008 } else if x == y {
4009 if x.is_sign_negative() && y.is_sign_positive() { x } else { y }
4010 } else {
4011 // At least one input is NaN. Use `+` to perform NaN propagation and quieting.
4012 x + y
4013 }
4014}
4015
4016/// Returns the minimum (IEEE 754-2019 minimum) of two `f128` values.
4017///
4018/// Note that, unlike most intrinsics, this is safe to call;
4019/// it does not require an `unsafe` block.
4020/// Therefore, implementations must not require the user to uphold
4021/// any safety invariants.
4022#[rustc_nounwind]
4023#[cfg_attr(not(bootstrap), rustc_intrinsic)]
4024pub const fn minimumf128(x: f128, y: f128) -> f128 {
4025 if x < y {
4026 x
4027 } else if y < x {
4028 y
4029 } else if x == y {
4030 if x.is_sign_negative() && y.is_sign_positive() { x } else { y }
4031 } else {
4032 // At least one input is NaN. Use `+` to perform NaN propagation and quieting.
4033 x + y
4034 }
4035}
4036
4037/// Returns the maximum (IEEE 754-2008 maxNum) of two `f16` values.
4038///
4039/// Note that, unlike most intrinsics, this is safe to call;
4040/// it does not require an `unsafe` block.
4041/// Therefore, implementations must not require the user to uphold
4042/// any safety invariants.
4043///
4044/// The stabilized version of this intrinsic is
4045/// [`f16::max`]
4046#[rustc_nounwind]
4047#[rustc_intrinsic]
4048pub const fn maxnumf16(x: f16, y: f16) -> f16;
4049
4050/// Returns the maximum (IEEE 754-2008 maxNum) of two `f32` values.
4051///
4052/// Note that, unlike most intrinsics, this is safe to call;
4053/// it does not require an `unsafe` block.
4054/// Therefore, implementations must not require the user to uphold
4055/// any safety invariants.
4056///
4057/// The stabilized version of this intrinsic is
4058/// [`f32::max`]
4059#[rustc_nounwind]
4060#[rustc_intrinsic_const_stable_indirect]
4061#[rustc_intrinsic]
4062pub const fn maxnumf32(x: f32, y: f32) -> f32;
4063
4064/// Returns the maximum (IEEE 754-2008 maxNum) of two `f64` values.
4065///
4066/// Note that, unlike most intrinsics, this is safe to call;
4067/// it does not require an `unsafe` block.
4068/// Therefore, implementations must not require the user to uphold
4069/// any safety invariants.
4070///
4071/// The stabilized version of this intrinsic is
4072/// [`f64::max`]
4073#[rustc_nounwind]
4074#[rustc_intrinsic_const_stable_indirect]
4075#[rustc_intrinsic]
4076pub const fn maxnumf64(x: f64, y: f64) -> f64;
4077
4078/// Returns the maximum (IEEE 754-2008 maxNum) of two `f128` values.
4079///
4080/// Note that, unlike most intrinsics, this is safe to call;
4081/// it does not require an `unsafe` block.
4082/// Therefore, implementations must not require the user to uphold
4083/// any safety invariants.
4084///
4085/// The stabilized version of this intrinsic is
4086/// [`f128::max`]
4087#[rustc_nounwind]
4088#[rustc_intrinsic]
4089pub const fn maxnumf128(x: f128, y: f128) -> f128;
4090
4091/// Returns the maximum (IEEE 754-2019 maximum) of two `f16` values.
4092///
4093/// Note that, unlike most intrinsics, this is safe to call;
4094/// it does not require an `unsafe` block.
4095/// Therefore, implementations must not require the user to uphold
4096/// any safety invariants.
4097#[rustc_nounwind]
4098#[cfg_attr(not(bootstrap), rustc_intrinsic)]
4099pub const fn maximumf16(x: f16, y: f16) -> f16 {
4100 if x > y {
4101 x
4102 } else if y > x {
4103 y
4104 } else if x == y {
4105 if x.is_sign_positive() && y.is_sign_negative() { x } else { y }
4106 } else {
4107 x + y
4108 }
4109}
4110
4111/// Returns the maximum (IEEE 754-2019 maximum) of two `f32` values.
4112///
4113/// Note that, unlike most intrinsics, this is safe to call;
4114/// it does not require an `unsafe` block.
4115/// Therefore, implementations must not require the user to uphold
4116/// any safety invariants.
4117#[rustc_nounwind]
4118#[cfg_attr(not(bootstrap), rustc_intrinsic)]
4119pub const fn maximumf32(x: f32, y: f32) -> f32 {
4120 if x > y {
4121 x
4122 } else if y > x {
4123 y
4124 } else if x == y {
4125 if x.is_sign_positive() && y.is_sign_negative() { x } else { y }
4126 } else {
4127 x + y
4128 }
4129}
4130
4131/// Returns the maximum (IEEE 754-2019 maximum) of two `f64` values.
4132///
4133/// Note that, unlike most intrinsics, this is safe to call;
4134/// it does not require an `unsafe` block.
4135/// Therefore, implementations must not require the user to uphold
4136/// any safety invariants.
4137#[rustc_nounwind]
4138#[cfg_attr(not(bootstrap), rustc_intrinsic)]
4139pub const fn maximumf64(x: f64, y: f64) -> f64 {
4140 if x > y {
4141 x
4142 } else if y > x {
4143 y
4144 } else if x == y {
4145 if x.is_sign_positive() && y.is_sign_negative() { x } else { y }
4146 } else {
4147 x + y
4148 }
4149}
4150
4151/// Returns the maximum (IEEE 754-2019 maximum) of two `f128` values.
4152///
4153/// Note that, unlike most intrinsics, this is safe to call;
4154/// it does not require an `unsafe` block.
4155/// Therefore, implementations must not require the user to uphold
4156/// any safety invariants.
4157#[rustc_nounwind]
4158#[cfg_attr(not(bootstrap), rustc_intrinsic)]
4159pub const fn maximumf128(x: f128, y: f128) -> f128 {
4160 if x > y {
4161 x
4162 } else if y > x {
4163 y
4164 } else if x == y {
4165 if x.is_sign_positive() && y.is_sign_negative() { x } else { y }
4166 } else {
4167 x + y
4168 }
4169}
4170
4171/// Returns the absolute value of an `f16`.
4172///
4173/// The stabilized version of this intrinsic is
4174/// [`f16::abs`](../../std/primitive.f16.html#method.abs)
4175#[rustc_nounwind]
4176#[rustc_intrinsic]
4177pub const unsafe fn fabsf16(x: f16) -> f16;
4178
4179/// Returns the absolute value of an `f32`.
4180///
4181/// The stabilized version of this intrinsic is
4182/// [`f32::abs`](../../std/primitive.f32.html#method.abs)
4183#[rustc_nounwind]
4184#[rustc_intrinsic_const_stable_indirect]
4185#[rustc_intrinsic]
4186pub const unsafe fn fabsf32(x: f32) -> f32;
4187
4188/// Returns the absolute value of an `f64`.
4189///
4190/// The stabilized version of this intrinsic is
4191/// [`f64::abs`](../../std/primitive.f64.html#method.abs)
4192#[rustc_nounwind]
4193#[rustc_intrinsic_const_stable_indirect]
4194#[rustc_intrinsic]
4195pub const unsafe fn fabsf64(x: f64) -> f64;
4196
4197/// Returns the absolute value of an `f128`.
4198///
4199/// The stabilized version of this intrinsic is
4200/// [`f128::abs`](../../std/primitive.f128.html#method.abs)
4201#[rustc_nounwind]
4202#[rustc_intrinsic]
4203pub const unsafe fn fabsf128(x: f128) -> f128;
4204
4205/// Copies the sign from `y` to `x` for `f16` values.
4206///
4207/// The stabilized version of this intrinsic is
4208/// [`f16::copysign`](../../std/primitive.f16.html#method.copysign)
4209#[rustc_nounwind]
4210#[rustc_intrinsic]
4211pub const unsafe fn copysignf16(x: f16, y: f16) -> f16;
4212
4213/// Copies the sign from `y` to `x` for `f32` values.
4214///
4215/// The stabilized version of this intrinsic is
4216/// [`f32::copysign`](../../std/primitive.f32.html#method.copysign)
4217#[rustc_nounwind]
4218#[rustc_intrinsic_const_stable_indirect]
4219#[rustc_intrinsic]
4220pub const unsafe fn copysignf32(x: f32, y: f32) -> f32;
4221/// Copies the sign from `y` to `x` for `f64` values.
4222///
4223/// The stabilized version of this intrinsic is
4224/// [`f64::copysign`](../../std/primitive.f64.html#method.copysign)
4225#[rustc_nounwind]
4226#[rustc_intrinsic_const_stable_indirect]
4227#[rustc_intrinsic]
4228pub const unsafe fn copysignf64(x: f64, y: f64) -> f64;
4229
4230/// Copies the sign from `y` to `x` for `f128` values.
4231///
4232/// The stabilized version of this intrinsic is
4233/// [`f128::copysign`](../../std/primitive.f128.html#method.copysign)
4234#[rustc_nounwind]
4235#[rustc_intrinsic]
4236pub const unsafe fn copysignf128(x: f128, y: f128) -> f128;
4237
4238/// Inform Miri that a given pointer definitely has a certain alignment.
4239#[cfg(miri)]
4240#[rustc_allow_const_fn_unstable(const_eval_select)]
4241pub(crate) const fn miri_promise_symbolic_alignment(ptr: *const (), align: usize) {
4242 unsafe extern "Rust" {
4243 /// Miri-provided extern function to promise that a given pointer is properly aligned for
4244 /// "symbolic" alignment checks. Will fail if the pointer is not actually aligned or `align` is
4245 /// not a power of two. Has no effect when alignment checks are concrete (which is the default).
4246 fn miri_promise_symbolic_alignment(ptr: *const (), align: usize);
4247 }
4248
4249 const_eval_select!(
4250 @capture { ptr: *const (), align: usize}:
4251 if const {
4252 // Do nothing.
4253 } else {
4254 // SAFETY: this call is always safe.
4255 unsafe {
4256 miri_promise_symbolic_alignment(ptr, align);
4257 }
4258 }
4259 )
4260}