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