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 [`core::hint::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 arguments,
2632/// which must be of character or integer (signed or unsigned) type.
2633///
2634/// This was originally added because it greatly simplified the MIR in `cmp`
2635/// implementations, and then LLVM 20 added a backend intrinsic for it too.
2636///
2637/// The stabilized version of this intrinsic is [`Ord::cmp`].
2638#[rustc_intrinsic_const_stable_indirect]
2639#[rustc_nounwind]
2640#[rustc_intrinsic]
2641pub const fn three_way_compare<T: Copy>(lhs: T, rhss: T) -> crate::cmp::Ordering;
2642
2643/// Combine two values which have no bits in common.
2644///
2645/// This allows the backend to implement it as `a + b` *or* `a | b`,
2646/// depending which is easier to implement on a specific target.
2647///
2648/// # Safety
2649///
2650/// Requires that `(a & b) == 0`, or equivalently that `(a | b) == (a + b)`.
2651///
2652/// Otherwise it's immediate UB.
2653#[rustc_const_unstable(feature = "disjoint_bitor", issue = "135758")]
2654#[rustc_nounwind]
2655#[rustc_intrinsic]
2656#[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
2657#[miri::intrinsic_fallback_is_spec] // the fallbacks all `assume` to tell Miri
2658pub const unsafe fn disjoint_bitor<T: ~const fallback::DisjointBitOr>(a: T, b: T) -> T {
2659    // SAFETY: same preconditions as this function.
2660    unsafe { fallback::DisjointBitOr::disjoint_bitor(a, b) }
2661}
2662
2663/// Performs checked integer addition.
2664///
2665/// Note that, unlike most intrinsics, this is safe to call;
2666/// it does not require an `unsafe` block.
2667/// Therefore, implementations must not require the user to uphold
2668/// any safety invariants.
2669///
2670/// The stabilized versions of this intrinsic are available on the integer
2671/// primitives via the `overflowing_add` method. For example,
2672/// [`u32::overflowing_add`]
2673#[rustc_intrinsic_const_stable_indirect]
2674#[rustc_nounwind]
2675#[rustc_intrinsic]
2676pub const fn add_with_overflow<T: Copy>(x: T, y: T) -> (T, bool);
2677
2678/// Performs checked integer subtraction
2679///
2680/// Note that, unlike most intrinsics, this is safe to call;
2681/// it does not require an `unsafe` block.
2682/// Therefore, implementations must not require the user to uphold
2683/// any safety invariants.
2684///
2685/// The stabilized versions of this intrinsic are available on the integer
2686/// primitives via the `overflowing_sub` method. For example,
2687/// [`u32::overflowing_sub`]
2688#[rustc_intrinsic_const_stable_indirect]
2689#[rustc_nounwind]
2690#[rustc_intrinsic]
2691pub const fn sub_with_overflow<T: Copy>(x: T, y: T) -> (T, bool);
2692
2693/// Performs checked integer multiplication
2694///
2695/// Note that, unlike most intrinsics, this is safe to call;
2696/// it does not require an `unsafe` block.
2697/// Therefore, implementations must not require the user to uphold
2698/// any safety invariants.
2699///
2700/// The stabilized versions of this intrinsic are available on the integer
2701/// primitives via the `overflowing_mul` method. For example,
2702/// [`u32::overflowing_mul`]
2703#[rustc_intrinsic_const_stable_indirect]
2704#[rustc_nounwind]
2705#[rustc_intrinsic]
2706pub const fn mul_with_overflow<T: Copy>(x: T, y: T) -> (T, bool);
2707
2708/// Performs full-width multiplication and addition with a carry:
2709/// `multiplier * multiplicand + addend + carry`.
2710///
2711/// This is possible without any overflow.  For `uN`:
2712///    MAX * MAX + MAX + MAX
2713/// => (2ⁿ-1) × (2ⁿ-1) + (2ⁿ-1) + (2ⁿ-1)
2714/// => (2²ⁿ - 2ⁿ⁺¹ + 1) + (2ⁿ⁺¹ - 2)
2715/// => 2²ⁿ - 1
2716///
2717/// For `iN`, the upper bound is MIN * MIN + MAX + MAX => 2²ⁿ⁻² + 2ⁿ - 2,
2718/// and the lower bound is MAX * MIN + MIN + MIN => -2²ⁿ⁻² - 2ⁿ + 2ⁿ⁺¹.
2719///
2720/// This currently supports unsigned integers *only*, no signed ones.
2721/// The stabilized versions of this intrinsic are available on integers.
2722#[unstable(feature = "core_intrinsics", issue = "none")]
2723#[rustc_const_unstable(feature = "const_carrying_mul_add", issue = "85532")]
2724#[rustc_nounwind]
2725#[rustc_intrinsic]
2726#[miri::intrinsic_fallback_is_spec]
2727pub const fn carrying_mul_add<T: ~const fallback::CarryingMulAdd<Unsigned = U>, U>(
2728    multiplier: T,
2729    multiplicand: T,
2730    addend: T,
2731    carry: T,
2732) -> (U, T) {
2733    multiplier.carrying_mul_add(multiplicand, addend, carry)
2734}
2735
2736/// Performs an exact division, resulting in undefined behavior where
2737/// `x % y != 0` or `y == 0` or `x == T::MIN && y == -1`
2738///
2739/// This intrinsic does not have a stable counterpart.
2740#[rustc_intrinsic_const_stable_indirect]
2741#[rustc_nounwind]
2742#[rustc_intrinsic]
2743pub const unsafe fn exact_div<T: Copy>(x: T, y: T) -> T;
2744
2745/// Performs an unchecked division, resulting in undefined behavior
2746/// where `y == 0` or `x == T::MIN && y == -1`
2747///
2748/// Safe wrappers for this intrinsic are available on the integer
2749/// primitives via the `checked_div` method. For example,
2750/// [`u32::checked_div`]
2751#[rustc_intrinsic_const_stable_indirect]
2752#[rustc_nounwind]
2753#[rustc_intrinsic]
2754pub const unsafe fn unchecked_div<T: Copy>(x: T, y: T) -> T;
2755/// Returns the remainder of an unchecked division, resulting in
2756/// undefined behavior when `y == 0` or `x == T::MIN && y == -1`
2757///
2758/// Safe wrappers for this intrinsic are available on the integer
2759/// primitives via the `checked_rem` method. For example,
2760/// [`u32::checked_rem`]
2761#[rustc_intrinsic_const_stable_indirect]
2762#[rustc_nounwind]
2763#[rustc_intrinsic]
2764pub const unsafe fn unchecked_rem<T: Copy>(x: T, y: T) -> T;
2765
2766/// Performs an unchecked left shift, resulting in undefined behavior when
2767/// `y < 0` or `y >= N`, where N is the width of T in bits.
2768///
2769/// Safe wrappers for this intrinsic are available on the integer
2770/// primitives via the `checked_shl` method. For example,
2771/// [`u32::checked_shl`]
2772#[rustc_intrinsic_const_stable_indirect]
2773#[rustc_nounwind]
2774#[rustc_intrinsic]
2775pub const unsafe fn unchecked_shl<T: Copy, U: Copy>(x: T, y: U) -> T;
2776/// Performs an unchecked right shift, resulting in undefined behavior when
2777/// `y < 0` or `y >= N`, where N is the width of T in bits.
2778///
2779/// Safe wrappers for this intrinsic are available on the integer
2780/// primitives via the `checked_shr` method. For example,
2781/// [`u32::checked_shr`]
2782#[rustc_intrinsic_const_stable_indirect]
2783#[rustc_nounwind]
2784#[rustc_intrinsic]
2785pub const unsafe fn unchecked_shr<T: Copy, U: Copy>(x: T, y: U) -> T;
2786
2787/// Returns the result of an unchecked addition, resulting in
2788/// undefined behavior when `x + y > T::MAX` or `x + y < T::MIN`.
2789///
2790/// The stable counterpart of this intrinsic is `unchecked_add` on the various
2791/// integer types, such as [`u16::unchecked_add`] and [`i64::unchecked_add`].
2792#[rustc_intrinsic_const_stable_indirect]
2793#[rustc_nounwind]
2794#[rustc_intrinsic]
2795pub const unsafe fn unchecked_add<T: Copy>(x: T, y: T) -> T;
2796
2797/// Returns the result of an unchecked subtraction, resulting in
2798/// undefined behavior when `x - y > T::MAX` or `x - y < T::MIN`.
2799///
2800/// The stable counterpart of this intrinsic is `unchecked_sub` on the various
2801/// integer types, such as [`u16::unchecked_sub`] and [`i64::unchecked_sub`].
2802#[rustc_intrinsic_const_stable_indirect]
2803#[rustc_nounwind]
2804#[rustc_intrinsic]
2805pub const unsafe fn unchecked_sub<T: Copy>(x: T, y: T) -> T;
2806
2807/// Returns the result of an unchecked multiplication, resulting in
2808/// undefined behavior when `x * y > T::MAX` or `x * y < T::MIN`.
2809///
2810/// The stable counterpart of this intrinsic is `unchecked_mul` on the various
2811/// integer types, such as [`u16::unchecked_mul`] and [`i64::unchecked_mul`].
2812#[rustc_intrinsic_const_stable_indirect]
2813#[rustc_nounwind]
2814#[rustc_intrinsic]
2815pub const unsafe fn unchecked_mul<T: Copy>(x: T, y: T) -> T;
2816
2817/// Performs rotate left.
2818///
2819/// Note that, unlike most intrinsics, this is safe to call;
2820/// it does not require an `unsafe` block.
2821/// Therefore, implementations must not require the user to uphold
2822/// any safety invariants.
2823///
2824/// The stabilized versions of this intrinsic are available on the integer
2825/// primitives via the `rotate_left` method. For example,
2826/// [`u32::rotate_left`]
2827#[rustc_intrinsic_const_stable_indirect]
2828#[rustc_nounwind]
2829#[rustc_intrinsic]
2830pub const fn rotate_left<T: Copy>(x: T, shift: u32) -> T;
2831
2832/// Performs rotate right.
2833///
2834/// Note that, unlike most intrinsics, this is safe to call;
2835/// it does not require an `unsafe` block.
2836/// Therefore, implementations must not require the user to uphold
2837/// any safety invariants.
2838///
2839/// The stabilized versions of this intrinsic are available on the integer
2840/// primitives via the `rotate_right` method. For example,
2841/// [`u32::rotate_right`]
2842#[rustc_intrinsic_const_stable_indirect]
2843#[rustc_nounwind]
2844#[rustc_intrinsic]
2845pub const fn rotate_right<T: Copy>(x: T, shift: u32) -> T;
2846
2847/// Returns (a + b) mod 2<sup>N</sup>, where N is the width of T in bits.
2848///
2849/// Note that, unlike most intrinsics, this is safe to call;
2850/// it does not require an `unsafe` block.
2851/// Therefore, implementations must not require the user to uphold
2852/// any safety invariants.
2853///
2854/// The stabilized versions of this intrinsic are available on the integer
2855/// primitives via the `wrapping_add` method. For example,
2856/// [`u32::wrapping_add`]
2857#[rustc_intrinsic_const_stable_indirect]
2858#[rustc_nounwind]
2859#[rustc_intrinsic]
2860pub const fn wrapping_add<T: Copy>(a: T, b: T) -> T;
2861/// Returns (a - b) mod 2<sup>N</sup>, where N is the width of T in bits.
2862///
2863/// Note that, unlike most intrinsics, this is safe to call;
2864/// it does not require an `unsafe` block.
2865/// Therefore, implementations must not require the user to uphold
2866/// any safety invariants.
2867///
2868/// The stabilized versions of this intrinsic are available on the integer
2869/// primitives via the `wrapping_sub` method. For example,
2870/// [`u32::wrapping_sub`]
2871#[rustc_intrinsic_const_stable_indirect]
2872#[rustc_nounwind]
2873#[rustc_intrinsic]
2874pub const fn wrapping_sub<T: Copy>(a: T, b: T) -> T;
2875/// Returns (a * b) mod 2<sup>N</sup>, where N is the width of T in bits.
2876///
2877/// Note that, unlike most intrinsics, this is safe to call;
2878/// it does not require an `unsafe` block.
2879/// Therefore, implementations must not require the user to uphold
2880/// any safety invariants.
2881///
2882/// The stabilized versions of this intrinsic are available on the integer
2883/// primitives via the `wrapping_mul` method. For example,
2884/// [`u32::wrapping_mul`]
2885#[rustc_intrinsic_const_stable_indirect]
2886#[rustc_nounwind]
2887#[rustc_intrinsic]
2888pub const fn wrapping_mul<T: Copy>(a: T, b: T) -> T;
2889
2890/// Computes `a + b`, saturating at numeric bounds.
2891///
2892/// Note that, unlike most intrinsics, this is safe to call;
2893/// it does not require an `unsafe` block.
2894/// Therefore, implementations must not require the user to uphold
2895/// any safety invariants.
2896///
2897/// The stabilized versions of this intrinsic are available on the integer
2898/// primitives via the `saturating_add` method. For example,
2899/// [`u32::saturating_add`]
2900#[rustc_intrinsic_const_stable_indirect]
2901#[rustc_nounwind]
2902#[rustc_intrinsic]
2903pub const fn saturating_add<T: Copy>(a: T, b: T) -> T;
2904/// Computes `a - b`, saturating at numeric bounds.
2905///
2906/// Note that, unlike most intrinsics, this is safe to call;
2907/// it does not require an `unsafe` block.
2908/// Therefore, implementations must not require the user to uphold
2909/// any safety invariants.
2910///
2911/// The stabilized versions of this intrinsic are available on the integer
2912/// primitives via the `saturating_sub` method. For example,
2913/// [`u32::saturating_sub`]
2914#[rustc_intrinsic_const_stable_indirect]
2915#[rustc_nounwind]
2916#[rustc_intrinsic]
2917pub const fn saturating_sub<T: Copy>(a: T, b: T) -> T;
2918
2919/// This is an implementation detail of [`crate::ptr::read`] and should
2920/// not be used anywhere else.  See its comments for why this exists.
2921///
2922/// This intrinsic can *only* be called where the pointer is a local without
2923/// projections (`read_via_copy(ptr)`, not `read_via_copy(*ptr)`) so that it
2924/// trivially obeys runtime-MIR rules about derefs in operands.
2925#[rustc_intrinsic_const_stable_indirect]
2926#[rustc_nounwind]
2927#[rustc_intrinsic]
2928pub const unsafe fn read_via_copy<T>(ptr: *const T) -> T;
2929
2930/// This is an implementation detail of [`crate::ptr::write`] and should
2931/// not be used anywhere else.  See its comments for why this exists.
2932///
2933/// This intrinsic can *only* be called where the pointer is a local without
2934/// projections (`write_via_move(ptr, x)`, not `write_via_move(*ptr, x)`) so
2935/// that it trivially obeys runtime-MIR rules about derefs in operands.
2936#[rustc_intrinsic_const_stable_indirect]
2937#[rustc_nounwind]
2938#[rustc_intrinsic]
2939pub const unsafe fn write_via_move<T>(ptr: *mut T, value: T);
2940
2941/// Returns the value of the discriminant for the variant in 'v';
2942/// if `T` has no discriminant, returns `0`.
2943///
2944/// Note that, unlike most intrinsics, this is safe to call;
2945/// it does not require an `unsafe` block.
2946/// Therefore, implementations must not require the user to uphold
2947/// any safety invariants.
2948///
2949/// The stabilized version of this intrinsic is [`core::mem::discriminant`].
2950#[rustc_intrinsic_const_stable_indirect]
2951#[rustc_nounwind]
2952#[rustc_intrinsic]
2953pub const fn discriminant_value<T>(v: &T) -> <T as DiscriminantKind>::Discriminant;
2954
2955/// Rust's "try catch" construct for unwinding. Invokes the function pointer `try_fn` with the
2956/// data pointer `data`, and calls `catch_fn` if unwinding occurs while `try_fn` runs.
2957/// Returns `1` if unwinding occurred and `catch_fn` was called; returns `0` otherwise.
2958///
2959/// `catch_fn` must not unwind.
2960///
2961/// The third argument is a function called if an unwind occurs (both Rust `panic` and foreign
2962/// unwinds). This function takes the data pointer and a pointer to the target- and
2963/// runtime-specific exception object that was caught.
2964///
2965/// Note that in the case of a foreign unwinding operation, the exception object data may not be
2966/// safely usable from Rust, and should not be directly exposed via the standard library. To
2967/// prevent unsafe access, the library implementation may either abort the process or present an
2968/// opaque error type to the user.
2969///
2970/// For more information, see the compiler's source, as well as the documentation for the stable
2971/// version of this intrinsic, `std::panic::catch_unwind`.
2972#[rustc_intrinsic]
2973#[rustc_nounwind]
2974pub unsafe fn catch_unwind(
2975    _try_fn: fn(*mut u8),
2976    _data: *mut u8,
2977    _catch_fn: fn(*mut u8, *mut u8),
2978) -> i32;
2979
2980/// Emits a `nontemporal` store, which gives a hint to the CPU that the data should not be held
2981/// in cache. Except for performance, this is fully equivalent to `ptr.write(val)`.
2982///
2983/// Not all architectures provide such an operation. For instance, x86 does not: while `MOVNT`
2984/// exists, that operation is *not* equivalent to `ptr.write(val)` (`MOVNT` writes can be reordered
2985/// in ways that are not allowed for regular writes).
2986#[rustc_intrinsic]
2987#[rustc_nounwind]
2988pub unsafe fn nontemporal_store<T>(ptr: *mut T, val: T);
2989
2990/// See documentation of `<*const T>::offset_from` for details.
2991#[rustc_intrinsic_const_stable_indirect]
2992#[rustc_nounwind]
2993#[rustc_intrinsic]
2994pub const unsafe fn ptr_offset_from<T>(ptr: *const T, base: *const T) -> isize;
2995
2996/// See documentation of `<*const T>::sub_ptr` for details.
2997#[rustc_nounwind]
2998#[rustc_intrinsic]
2999#[rustc_intrinsic_const_stable_indirect]
3000pub const unsafe fn ptr_offset_from_unsigned<T>(ptr: *const T, base: *const T) -> usize;
3001
3002/// See documentation of `<*const T>::guaranteed_eq` for details.
3003/// Returns `2` if the result is unknown.
3004/// Returns `1` if the pointers are guaranteed equal.
3005/// Returns `0` if the pointers are guaranteed inequal.
3006#[rustc_intrinsic]
3007#[rustc_nounwind]
3008#[rustc_do_not_const_check]
3009#[inline]
3010#[miri::intrinsic_fallback_is_spec]
3011pub const fn ptr_guaranteed_cmp<T>(ptr: *const T, other: *const T) -> u8 {
3012    (ptr == other) as u8
3013}
3014
3015/// Determines whether the raw bytes of the two values are equal.
3016///
3017/// This is particularly handy for arrays, since it allows things like just
3018/// comparing `i96`s instead of forcing `alloca`s for `[6 x i16]`.
3019///
3020/// Above some backend-decided threshold this will emit calls to `memcmp`,
3021/// like slice equality does, instead of causing massive code size.
3022///
3023/// Since this works by comparing the underlying bytes, the actual `T` is
3024/// not particularly important.  It will be used for its size and alignment,
3025/// but any validity restrictions will be ignored, not enforced.
3026///
3027/// # Safety
3028///
3029/// It's UB to call this if any of the *bytes* in `*a` or `*b` are uninitialized.
3030/// Note that this is a stricter criterion than just the *values* being
3031/// fully-initialized: if `T` has padding, it's UB to call this intrinsic.
3032///
3033/// At compile-time, it is furthermore UB to call this if any of the bytes
3034/// in `*a` or `*b` have provenance.
3035///
3036/// (The implementation is allowed to branch on the results of comparisons,
3037/// which is UB if any of their inputs are `undef`.)
3038#[rustc_nounwind]
3039#[rustc_intrinsic]
3040pub const unsafe fn raw_eq<T>(a: &T, b: &T) -> bool;
3041
3042/// Lexicographically compare `[left, left + bytes)` and `[right, right + bytes)`
3043/// as unsigned bytes, returning negative if `left` is less, zero if all the
3044/// bytes match, or positive if `left` is greater.
3045///
3046/// This underlies things like `<[u8]>::cmp`, and will usually lower to `memcmp`.
3047///
3048/// # Safety
3049///
3050/// `left` and `right` must each be [valid] for reads of `bytes` bytes.
3051///
3052/// Note that this applies to the whole range, not just until the first byte
3053/// that differs.  That allows optimizations that can read in large chunks.
3054///
3055/// [valid]: crate::ptr#safety
3056#[rustc_nounwind]
3057#[rustc_intrinsic]
3058pub const unsafe fn compare_bytes(left: *const u8, right: *const u8, bytes: usize) -> i32;
3059
3060/// See documentation of [`std::hint::black_box`] for details.
3061///
3062/// [`std::hint::black_box`]: crate::hint::black_box
3063#[rustc_nounwind]
3064#[rustc_intrinsic]
3065#[rustc_intrinsic_const_stable_indirect]
3066pub const fn black_box<T>(dummy: T) -> T;
3067
3068/// Selects which function to call depending on the context.
3069///
3070/// If this function is evaluated at compile-time, then a call to this
3071/// intrinsic will be replaced with a call to `called_in_const`. It gets
3072/// replaced with a call to `called_at_rt` otherwise.
3073///
3074/// This function is safe to call, but note the stability concerns below.
3075///
3076/// # Type Requirements
3077///
3078/// The two functions must be both function items. They cannot be function
3079/// pointers or closures. The first function must be a `const fn`.
3080///
3081/// `arg` will be the tupled arguments that will be passed to either one of
3082/// the two functions, therefore, both functions must accept the same type of
3083/// arguments. Both functions must return RET.
3084///
3085/// # Stability concerns
3086///
3087/// Rust has not yet decided that `const fn` are allowed to tell whether
3088/// they run at compile-time or at runtime. Therefore, when using this
3089/// intrinsic anywhere that can be reached from stable, it is crucial that
3090/// the end-to-end behavior of the stable `const fn` is the same for both
3091/// modes of execution. (Here, Undefined Behavior is considered "the same"
3092/// as any other behavior, so if the function exhibits UB at runtime then
3093/// it may do whatever it wants at compile-time.)
3094///
3095/// Here is an example of how this could cause a problem:
3096/// ```no_run
3097/// #![feature(const_eval_select)]
3098/// #![feature(core_intrinsics)]
3099/// # #![allow(internal_features)]
3100/// use std::intrinsics::const_eval_select;
3101///
3102/// // Standard library
3103/// pub const fn inconsistent() -> i32 {
3104///     fn runtime() -> i32 { 1 }
3105///     const fn compiletime() -> i32 { 2 }
3106///
3107///     // ⚠ This code violates the required equivalence of `compiletime`
3108///     // and `runtime`.
3109///     const_eval_select((), compiletime, runtime)
3110/// }
3111///
3112/// // User Crate
3113/// const X: i32 = inconsistent();
3114/// let x = inconsistent();
3115/// assert_eq!(x, X);
3116/// ```
3117///
3118/// Currently such an assertion would always succeed; until Rust decides
3119/// otherwise, that principle should not be violated.
3120#[rustc_const_unstable(feature = "const_eval_select", issue = "124625")]
3121#[rustc_intrinsic]
3122pub const fn const_eval_select<ARG: Tuple, F, G, RET>(
3123    _arg: ARG,
3124    _called_in_const: F,
3125    _called_at_rt: G,
3126) -> RET
3127where
3128    G: FnOnce<ARG, Output = RET>,
3129    F: FnOnce<ARG, Output = RET>;
3130
3131/// A macro to make it easier to invoke const_eval_select. Use as follows:
3132/// ```rust,ignore (just a macro example)
3133/// const_eval_select!(
3134///     @capture { arg1: i32 = some_expr, arg2: T = other_expr } -> U:
3135///     if const #[attributes_for_const_arm] {
3136///         // Compile-time code goes here.
3137///     } else #[attributes_for_runtime_arm] {
3138///         // Run-time code goes here.
3139///     }
3140/// )
3141/// ```
3142/// The `@capture` block declares which surrounding variables / expressions can be
3143/// used inside the `if const`.
3144/// Note that the two arms of this `if` really each become their own function, which is why the
3145/// macro supports setting attributes for those functions. The runtime function is always
3146/// markes as `#[inline]`.
3147///
3148/// See [`const_eval_select()`] for the rules and requirements around that intrinsic.
3149pub(crate) macro const_eval_select {
3150    (
3151        @capture$([$($binders:tt)*])? { $($arg:ident : $ty:ty = $val:expr),* $(,)? } $( -> $ret:ty )? :
3152        if const
3153            $(#[$compiletime_attr:meta])* $compiletime:block
3154        else
3155            $(#[$runtime_attr:meta])* $runtime:block
3156    ) => {
3157        // Use the `noinline` arm, after adding explicit `inline` attributes
3158        $crate::intrinsics::const_eval_select!(
3159            @capture$([$($binders)*])? { $($arg : $ty = $val),* } $(-> $ret)? :
3160            #[noinline]
3161            if const
3162                #[inline] // prevent codegen on this function
3163                $(#[$compiletime_attr])*
3164                $compiletime
3165            else
3166                #[inline] // avoid the overhead of an extra fn call
3167                $(#[$runtime_attr])*
3168                $runtime
3169        )
3170    },
3171    // With a leading #[noinline], we don't add inline attributes
3172    (
3173        @capture$([$($binders:tt)*])? { $($arg:ident : $ty:ty = $val:expr),* $(,)? } $( -> $ret:ty )? :
3174        #[noinline]
3175        if const
3176            $(#[$compiletime_attr:meta])* $compiletime:block
3177        else
3178            $(#[$runtime_attr:meta])* $runtime:block
3179    ) => {{
3180        $(#[$runtime_attr])*
3181        fn runtime$(<$($binders)*>)?($($arg: $ty),*) $( -> $ret )? {
3182            $runtime
3183        }
3184
3185        $(#[$compiletime_attr])*
3186        const fn compiletime$(<$($binders)*>)?($($arg: $ty),*) $( -> $ret )? {
3187            // Don't warn if one of the arguments is unused.
3188            $(let _ = $arg;)*
3189
3190            $compiletime
3191        }
3192
3193        const_eval_select(($($val,)*), compiletime, runtime)
3194    }},
3195    // We support leaving away the `val` expressions for *all* arguments
3196    // (but not for *some* arguments, that's too tricky).
3197    (
3198        @capture$([$($binders:tt)*])? { $($arg:ident : $ty:ty),* $(,)? } $( -> $ret:ty )? :
3199        if const
3200            $(#[$compiletime_attr:meta])* $compiletime:block
3201        else
3202            $(#[$runtime_attr:meta])* $runtime:block
3203    ) => {
3204        $crate::intrinsics::const_eval_select!(
3205            @capture$([$($binders)*])? { $($arg : $ty = $arg),* } $(-> $ret)? :
3206            if const
3207                $(#[$compiletime_attr])* $compiletime
3208            else
3209                $(#[$runtime_attr])* $runtime
3210        )
3211    },
3212}
3213
3214/// Returns whether the argument's value is statically known at
3215/// compile-time.
3216///
3217/// This is useful when there is a way of writing the code that will
3218/// be *faster* when some variables have known values, but *slower*
3219/// in the general case: an `if is_val_statically_known(var)` can be used
3220/// to select between these two variants. The `if` will be optimized away
3221/// and only the desired branch remains.
3222///
3223/// Formally speaking, this function non-deterministically returns `true`
3224/// or `false`, and the caller has to ensure sound behavior for both cases.
3225/// In other words, the following code has *Undefined Behavior*:
3226///
3227/// ```no_run
3228/// #![feature(core_intrinsics)]
3229/// # #![allow(internal_features)]
3230/// use std::hint::unreachable_unchecked;
3231/// use std::intrinsics::is_val_statically_known;
3232///
3233/// if !is_val_statically_known(0) { unsafe { unreachable_unchecked(); } }
3234/// ```
3235///
3236/// This also means that the following code's behavior is unspecified; it
3237/// may panic, or it may not:
3238///
3239/// ```no_run
3240/// #![feature(core_intrinsics)]
3241/// # #![allow(internal_features)]
3242/// use std::intrinsics::is_val_statically_known;
3243///
3244/// assert_eq!(is_val_statically_known(0), is_val_statically_known(0));
3245/// ```
3246///
3247/// Unsafe code may not rely on `is_val_statically_known` returning any
3248/// particular value, ever. However, the compiler will generally make it
3249/// return `true` only if the value of the argument is actually known.
3250///
3251/// # Stability concerns
3252///
3253/// While it is safe to call, this intrinsic may behave differently in
3254/// a `const` context than otherwise. See the [`const_eval_select()`]
3255/// documentation for an explanation of the issues this can cause. Unlike
3256/// `const_eval_select`, this intrinsic isn't guaranteed to behave
3257/// deterministically even in a `const` context.
3258///
3259/// # Type Requirements
3260///
3261/// `T` must be either a `bool`, a `char`, a primitive numeric type (e.g. `f32`,
3262/// but not `NonZeroISize`), or any thin pointer (e.g. `*mut String`).
3263/// Any other argument types *may* cause a compiler error.
3264///
3265/// ## Pointers
3266///
3267/// When the input is a pointer, only the pointer itself is
3268/// ever considered. The pointee has no effect. Currently, these functions
3269/// behave identically:
3270///
3271/// ```
3272/// #![feature(core_intrinsics)]
3273/// # #![allow(internal_features)]
3274/// use std::intrinsics::is_val_statically_known;
3275///
3276/// fn foo(x: &i32) -> bool {
3277///     is_val_statically_known(x)
3278/// }
3279///
3280/// fn bar(x: &i32) -> bool {
3281///     is_val_statically_known(
3282///         (x as *const i32).addr()
3283///     )
3284/// }
3285/// # _ = foo(&5_i32);
3286/// # _ = bar(&5_i32);
3287/// ```
3288#[rustc_const_stable_indirect]
3289#[rustc_nounwind]
3290#[unstable(feature = "core_intrinsics", issue = "none")]
3291#[rustc_intrinsic]
3292pub const fn is_val_statically_known<T: Copy>(_arg: T) -> bool {
3293    false
3294}
3295
3296/// Non-overlapping *typed* swap of a single value.
3297///
3298/// The codegen backends will replace this with a better implementation when
3299/// `T` is a simple type that can be loaded and stored as an immediate.
3300///
3301/// The stabilized form of this intrinsic is [`crate::mem::swap`].
3302///
3303/// # Safety
3304/// Behavior is undefined if any of the following conditions are violated:
3305///
3306/// * Both `x` and `y` must be [valid] for both reads and writes.
3307///
3308/// * Both `x` and `y` must be properly aligned.
3309///
3310/// * The region of memory beginning at `x` must *not* overlap with the region of memory
3311///   beginning at `y`.
3312///
3313/// * The memory pointed by `x` and `y` must both contain values of type `T`.
3314///
3315/// [valid]: crate::ptr#safety
3316#[rustc_nounwind]
3317#[inline]
3318#[rustc_intrinsic]
3319#[rustc_intrinsic_const_stable_indirect]
3320#[rustc_allow_const_fn_unstable(const_swap_nonoverlapping)] // this is anyway not called since CTFE implements the intrinsic
3321pub const unsafe fn typed_swap_nonoverlapping<T>(x: *mut T, y: *mut T) {
3322    // SAFETY: The caller provided single non-overlapping items behind
3323    // pointers, so swapping them with `count: 1` is fine.
3324    unsafe { ptr::swap_nonoverlapping(x, y, 1) };
3325}
3326
3327/// Returns whether we should perform some UB-checking at runtime. This eventually evaluates to
3328/// `cfg!(ub_checks)`, but behaves different from `cfg!` when mixing crates built with different
3329/// flags: if the crate has UB checks enabled or carries the `#[rustc_preserve_ub_checks]`
3330/// attribute, evaluation is delayed until monomorphization (or until the call gets inlined into
3331/// a crate that does not delay evaluation further); otherwise it can happen any time.
3332///
3333/// The common case here is a user program built with ub_checks linked against the distributed
3334/// sysroot which is built without ub_checks but with `#[rustc_preserve_ub_checks]`.
3335/// For code that gets monomorphized in the user crate (i.e., generic functions and functions with
3336/// `#[inline]`), gating assertions on `ub_checks()` rather than `cfg!(ub_checks)` means that
3337/// assertions are enabled whenever the *user crate* has UB checks enabled. However, if the
3338/// user has UB checks disabled, the checks will still get optimized out. This intrinsic is
3339/// primarily used by [`ub_checks::assert_unsafe_precondition`].
3340#[rustc_intrinsic_const_stable_indirect] // just for UB checks
3341#[inline(always)]
3342#[rustc_intrinsic]
3343pub const fn ub_checks() -> bool {
3344    cfg!(ub_checks)
3345}
3346
3347/// Allocates a block of memory at compile time.
3348/// At runtime, just returns a null pointer.
3349///
3350/// # Safety
3351///
3352/// - The `align` argument must be a power of two.
3353///    - At compile time, a compile error occurs if this constraint is violated.
3354///    - At runtime, it is not checked.
3355#[rustc_const_unstable(feature = "const_heap", issue = "79597")]
3356#[rustc_nounwind]
3357#[rustc_intrinsic]
3358#[miri::intrinsic_fallback_is_spec]
3359pub const unsafe fn const_allocate(_size: usize, _align: usize) -> *mut u8 {
3360    // const eval overrides this function, but runtime code for now just returns null pointers.
3361    // See <https://github.com/rust-lang/rust/issues/93935>.
3362    crate::ptr::null_mut()
3363}
3364
3365/// Deallocates a memory which allocated by `intrinsics::const_allocate` at compile time.
3366/// At runtime, does nothing.
3367///
3368/// # Safety
3369///
3370/// - The `align` argument must be a power of two.
3371///    - At compile time, a compile error occurs if this constraint is violated.
3372///    - At runtime, it is not checked.
3373/// - If the `ptr` is created in an another const, this intrinsic doesn't deallocate it.
3374/// - If the `ptr` is pointing to a local variable, this intrinsic doesn't deallocate it.
3375#[rustc_const_unstable(feature = "const_heap", issue = "79597")]
3376#[unstable(feature = "core_intrinsics", issue = "none")]
3377#[rustc_nounwind]
3378#[rustc_intrinsic]
3379#[miri::intrinsic_fallback_is_spec]
3380pub const unsafe fn const_deallocate(_ptr: *mut u8, _size: usize, _align: usize) {
3381    // Runtime NOP
3382}
3383
3384/// Returns whether we should perform contract-checking at runtime.
3385///
3386/// This is meant to be similar to the ub_checks intrinsic, in terms
3387/// of not prematurely commiting at compile-time to whether contract
3388/// checking is turned on, so that we can specify contracts in libstd
3389/// and let an end user opt into turning them on.
3390#[rustc_const_unstable(feature = "contracts_internals", issue = "128044" /* compiler-team#759 */)]
3391#[unstable(feature = "contracts_internals", issue = "128044" /* compiler-team#759 */)]
3392#[inline(always)]
3393#[rustc_intrinsic]
3394pub const fn contract_checks() -> bool {
3395    // FIXME: should this be `false` or `cfg!(contract_checks)`?
3396
3397    // cfg!(contract_checks)
3398    false
3399}
3400
3401/// Check if the pre-condition `cond` has been met.
3402///
3403/// By default, if `contract_checks` is enabled, this will panic with no unwind if the condition
3404/// returns false.
3405///
3406/// Note that this function is a no-op during constant evaluation.
3407#[unstable(feature = "contracts_internals", issue = "128044")]
3408// Calls to this function get inserted by an AST expansion pass, which uses the equivalent of
3409// `#[allow_internal_unstable]` to allow using `contracts_internals` functions. Const-checking
3410// doesn't honor `#[allow_internal_unstable]`, so for the const feature gate we use the user-facing
3411// `contracts` feature rather than the perma-unstable `contracts_internals`
3412#[rustc_const_unstable(feature = "contracts", issue = "128044")]
3413#[lang = "contract_check_requires"]
3414#[rustc_intrinsic]
3415pub const fn contract_check_requires<C: Fn() -> bool + Copy>(cond: C) {
3416    const_eval_select!(
3417        @capture[C: Fn() -> bool + Copy] { cond: C } :
3418        if const {
3419                // Do nothing
3420        } else {
3421            if contract_checks() && !cond() {
3422                // Emit no unwind panic in case this was a safety requirement.
3423                crate::panicking::panic_nounwind("failed requires check");
3424            }
3425        }
3426    )
3427}
3428
3429/// Check if the post-condition `cond` has been met.
3430///
3431/// By default, if `contract_checks` is enabled, this will panic with no unwind if the condition
3432/// returns false.
3433///
3434/// Note that this function is a no-op during constant evaluation.
3435#[cfg(not(bootstrap))]
3436#[unstable(feature = "contracts_internals", issue = "128044")]
3437// Similar to `contract_check_requires`, we need to use the user-facing
3438// `contracts` feature rather than the perma-unstable `contracts_internals`.
3439// Const-checking doesn't honor allow_internal_unstable logic used by contract expansion.
3440#[rustc_const_unstable(feature = "contracts", issue = "128044")]
3441#[lang = "contract_check_ensures"]
3442#[rustc_intrinsic]
3443pub const fn contract_check_ensures<C: Fn(&Ret) -> bool + Copy, Ret>(cond: C, ret: Ret) -> Ret {
3444    const_eval_select!(
3445        @capture[C: Fn(&Ret) -> bool + Copy, Ret] { cond: C, ret: Ret } -> Ret :
3446        if const {
3447            // Do nothing
3448            ret
3449        } else {
3450            if contract_checks() && !cond(&ret) {
3451                // Emit no unwind panic in case this was a safety requirement.
3452                crate::panicking::panic_nounwind("failed ensures check");
3453            }
3454            ret
3455        }
3456    )
3457}
3458
3459/// This is the old version of contract_check_ensures kept here for bootstrap only.
3460#[cfg(bootstrap)]
3461#[unstable(feature = "contracts_internals", issue = "128044" /* compiler-team#759 */)]
3462#[rustc_intrinsic]
3463pub fn contract_check_ensures<'a, Ret, C: Fn(&'a Ret) -> bool>(ret: &'a Ret, cond: C) {
3464    if contract_checks() && !cond(ret) {
3465        crate::panicking::panic_nounwind("failed ensures check");
3466    }
3467}
3468
3469/// The intrinsic will return the size stored in that vtable.
3470///
3471/// # Safety
3472///
3473/// `ptr` must point to a vtable.
3474#[rustc_nounwind]
3475#[unstable(feature = "core_intrinsics", issue = "none")]
3476#[rustc_intrinsic]
3477pub unsafe fn vtable_size(ptr: *const ()) -> usize;
3478
3479/// The intrinsic will return the alignment stored in that vtable.
3480///
3481/// # Safety
3482///
3483/// `ptr` must point to a vtable.
3484#[rustc_nounwind]
3485#[unstable(feature = "core_intrinsics", issue = "none")]
3486#[rustc_intrinsic]
3487pub unsafe fn vtable_align(ptr: *const ()) -> usize;
3488
3489/// The size of a type in bytes.
3490///
3491/// Note that, unlike most intrinsics, this is safe to call;
3492/// it does not require an `unsafe` block.
3493/// Therefore, implementations must not require the user to uphold
3494/// any safety invariants.
3495///
3496/// More specifically, this is the offset in bytes between successive
3497/// items of the same type, including alignment padding.
3498///
3499/// The stabilized version of this intrinsic is [`size_of`].
3500#[rustc_nounwind]
3501#[unstable(feature = "core_intrinsics", issue = "none")]
3502#[rustc_intrinsic_const_stable_indirect]
3503#[rustc_intrinsic]
3504pub const fn size_of<T>() -> usize;
3505
3506/// The minimum alignment of a type.
3507///
3508/// Note that, unlike most intrinsics, this is safe to call;
3509/// it does not require an `unsafe` block.
3510/// Therefore, implementations must not require the user to uphold
3511/// any safety invariants.
3512///
3513/// The stabilized version of this intrinsic is [`align_of`].
3514#[rustc_nounwind]
3515#[unstable(feature = "core_intrinsics", issue = "none")]
3516#[rustc_intrinsic_const_stable_indirect]
3517#[rustc_intrinsic]
3518pub const fn min_align_of<T>() -> usize;
3519
3520/// The preferred alignment of a type.
3521///
3522/// This intrinsic does not have a stable counterpart.
3523/// It's "tracking issue" is [#91971](https://github.com/rust-lang/rust/issues/91971).
3524#[rustc_nounwind]
3525#[unstable(feature = "core_intrinsics", issue = "none")]
3526#[rustc_intrinsic]
3527pub const unsafe fn pref_align_of<T>() -> usize;
3528
3529/// Returns the number of variants of the type `T` cast to a `usize`;
3530/// if `T` has no variants, returns `0`. Uninhabited variants will be counted.
3531///
3532/// Note that, unlike most intrinsics, this is safe to call;
3533/// it does not require an `unsafe` block.
3534/// Therefore, implementations must not require the user to uphold
3535/// any safety invariants.
3536///
3537/// The to-be-stabilized version of this intrinsic is [`crate::mem::variant_count`].
3538#[rustc_nounwind]
3539#[unstable(feature = "core_intrinsics", issue = "none")]
3540#[rustc_intrinsic]
3541pub const fn variant_count<T>() -> usize;
3542
3543/// The size of the referenced value in bytes.
3544///
3545/// The stabilized version of this intrinsic is [`size_of_val`].
3546///
3547/// # Safety
3548///
3549/// See [`crate::mem::size_of_val_raw`] for safety conditions.
3550#[rustc_nounwind]
3551#[unstable(feature = "core_intrinsics", issue = "none")]
3552#[rustc_intrinsic]
3553#[rustc_intrinsic_const_stable_indirect]
3554pub const unsafe fn size_of_val<T: ?Sized>(ptr: *const T) -> usize;
3555
3556/// The required alignment of the referenced value.
3557///
3558/// The stabilized version of this intrinsic is [`align_of_val`].
3559///
3560/// # Safety
3561///
3562/// See [`crate::mem::align_of_val_raw`] for safety conditions.
3563#[rustc_nounwind]
3564#[unstable(feature = "core_intrinsics", issue = "none")]
3565#[rustc_intrinsic]
3566#[rustc_intrinsic_const_stable_indirect]
3567pub const unsafe fn min_align_of_val<T: ?Sized>(ptr: *const T) -> usize;
3568
3569/// Gets a static string slice containing the name of a type.
3570///
3571/// Note that, unlike most intrinsics, this is safe to call;
3572/// it does not require an `unsafe` block.
3573/// Therefore, implementations must not require the user to uphold
3574/// any safety invariants.
3575///
3576/// The stabilized version of this intrinsic is [`core::any::type_name`].
3577#[rustc_nounwind]
3578#[unstable(feature = "core_intrinsics", issue = "none")]
3579#[rustc_intrinsic]
3580pub const fn type_name<T: ?Sized>() -> &'static str;
3581
3582/// Gets an identifier which is globally unique to the specified type. This
3583/// function will return the same value for a type regardless of whichever
3584/// crate it is invoked in.
3585///
3586/// Note that, unlike most intrinsics, this is safe to call;
3587/// it does not require an `unsafe` block.
3588/// Therefore, implementations must not require the user to uphold
3589/// any safety invariants.
3590///
3591/// The stabilized version of this intrinsic is [`core::any::TypeId::of`].
3592#[rustc_nounwind]
3593#[unstable(feature = "core_intrinsics", issue = "none")]
3594#[rustc_intrinsic]
3595pub const fn type_id<T: ?Sized + 'static>() -> u128;
3596
3597/// Lowers in MIR to `Rvalue::Aggregate` with `AggregateKind::RawPtr`.
3598///
3599/// This is used to implement functions like `slice::from_raw_parts_mut` and
3600/// `ptr::from_raw_parts` in a way compatible with the compiler being able to
3601/// change the possible layouts of pointers.
3602#[rustc_nounwind]
3603#[unstable(feature = "core_intrinsics", issue = "none")]
3604#[rustc_intrinsic_const_stable_indirect]
3605#[rustc_intrinsic]
3606pub const fn aggregate_raw_ptr<P: AggregateRawPtr<D, Metadata = M>, D, M>(data: D, meta: M) -> P;
3607
3608#[unstable(feature = "core_intrinsics", issue = "none")]
3609pub trait AggregateRawPtr<D> {
3610    type Metadata: Copy;
3611}
3612impl<P: ?Sized, T: ptr::Thin> AggregateRawPtr<*const T> for *const P {
3613    type Metadata = <P as ptr::Pointee>::Metadata;
3614}
3615impl<P: ?Sized, T: ptr::Thin> AggregateRawPtr<*mut T> for *mut P {
3616    type Metadata = <P as ptr::Pointee>::Metadata;
3617}
3618
3619/// Lowers in MIR to `Rvalue::UnaryOp` with `UnOp::PtrMetadata`.
3620///
3621/// This is used to implement functions like `ptr::metadata`.
3622#[rustc_nounwind]
3623#[unstable(feature = "core_intrinsics", issue = "none")]
3624#[rustc_intrinsic_const_stable_indirect]
3625#[rustc_intrinsic]
3626pub const fn ptr_metadata<P: ptr::Pointee<Metadata = M> + ?Sized, M>(ptr: *const P) -> M;
3627
3628// Some functions are defined here because they accidentally got made
3629// available in this module on stable. See <https://github.com/rust-lang/rust/issues/15702>.
3630// (`transmute` also falls into this category, but it cannot be wrapped due to the
3631// check that `T` and `U` have the same size.)
3632
3633/// Copies `count * size_of::<T>()` bytes from `src` to `dst`. The source
3634/// and destination must *not* overlap.
3635///
3636/// For regions of memory which might overlap, use [`copy`] instead.
3637///
3638/// `copy_nonoverlapping` is semantically equivalent to C's [`memcpy`], but
3639/// with the source and destination arguments swapped,
3640/// and `count` counting the number of `T`s instead of bytes.
3641///
3642/// The copy is "untyped" in the sense that data may be uninitialized or otherwise violate the
3643/// requirements of `T`. The initialization state is preserved exactly.
3644///
3645/// [`memcpy`]: https://en.cppreference.com/w/c/string/byte/memcpy
3646///
3647/// # Safety
3648///
3649/// Behavior is undefined if any of the following conditions are violated:
3650///
3651/// * `src` must be [valid] for reads of `count * size_of::<T>()` bytes.
3652///
3653/// * `dst` must be [valid] for writes of `count * size_of::<T>()` bytes.
3654///
3655/// * Both `src` and `dst` must be properly aligned.
3656///
3657/// * The region of memory beginning at `src` with a size of `count *
3658///   size_of::<T>()` bytes must *not* overlap with the region of memory
3659///   beginning at `dst` with the same size.
3660///
3661/// Like [`read`], `copy_nonoverlapping` creates a bitwise copy of `T`, regardless of
3662/// whether `T` is [`Copy`]. If `T` is not [`Copy`], using *both* the values
3663/// in the region beginning at `*src` and the region beginning at `*dst` can
3664/// [violate memory safety][read-ownership].
3665///
3666/// Note that even if the effectively copied size (`count * size_of::<T>()`) is
3667/// `0`, the pointers must be properly aligned.
3668///
3669/// [`read`]: crate::ptr::read
3670/// [read-ownership]: crate::ptr::read#ownership-of-the-returned-value
3671/// [valid]: crate::ptr#safety
3672///
3673/// # Examples
3674///
3675/// Manually implement [`Vec::append`]:
3676///
3677/// ```
3678/// use std::ptr;
3679///
3680/// /// Moves all the elements of `src` into `dst`, leaving `src` empty.
3681/// fn append<T>(dst: &mut Vec<T>, src: &mut Vec<T>) {
3682///     let src_len = src.len();
3683///     let dst_len = dst.len();
3684///
3685///     // Ensure that `dst` has enough capacity to hold all of `src`.
3686///     dst.reserve(src_len);
3687///
3688///     unsafe {
3689///         // The call to add is always safe because `Vec` will never
3690///         // allocate more than `isize::MAX` bytes.
3691///         let dst_ptr = dst.as_mut_ptr().add(dst_len);
3692///         let src_ptr = src.as_ptr();
3693///
3694///         // Truncate `src` without dropping its contents. We do this first,
3695///         // to avoid problems in case something further down panics.
3696///         src.set_len(0);
3697///
3698///         // The two regions cannot overlap because mutable references do
3699///         // not alias, and two different vectors cannot own the same
3700///         // memory.
3701///         ptr::copy_nonoverlapping(src_ptr, dst_ptr, src_len);
3702///
3703///         // Notify `dst` that it now holds the contents of `src`.
3704///         dst.set_len(dst_len + src_len);
3705///     }
3706/// }
3707///
3708/// let mut a = vec!['r'];
3709/// let mut b = vec!['u', 's', 't'];
3710///
3711/// append(&mut a, &mut b);
3712///
3713/// assert_eq!(a, &['r', 'u', 's', 't']);
3714/// assert!(b.is_empty());
3715/// ```
3716///
3717/// [`Vec::append`]: ../../std/vec/struct.Vec.html#method.append
3718#[doc(alias = "memcpy")]
3719#[stable(feature = "rust1", since = "1.0.0")]
3720#[rustc_allowed_through_unstable_modules = "import this function via `std::ptr` instead"]
3721#[rustc_const_stable(feature = "const_intrinsic_copy", since = "1.83.0")]
3722#[inline(always)]
3723#[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
3724#[rustc_diagnostic_item = "ptr_copy_nonoverlapping"]
3725pub const unsafe fn copy_nonoverlapping<T>(src: *const T, dst: *mut T, count: usize) {
3726    #[rustc_intrinsic_const_stable_indirect]
3727    #[rustc_nounwind]
3728    #[rustc_intrinsic]
3729    const unsafe fn copy_nonoverlapping<T>(src: *const T, dst: *mut T, count: usize);
3730
3731    ub_checks::assert_unsafe_precondition!(
3732        check_language_ub,
3733        "ptr::copy_nonoverlapping requires that both pointer arguments are aligned and non-null \
3734        and the specified memory ranges do not overlap",
3735        (
3736            src: *const () = src as *const (),
3737            dst: *mut () = dst as *mut (),
3738            size: usize = size_of::<T>(),
3739            align: usize = align_of::<T>(),
3740            count: usize = count,
3741        ) => {
3742            let zero_size = count == 0 || size == 0;
3743            ub_checks::maybe_is_aligned_and_not_null(src, align, zero_size)
3744                && ub_checks::maybe_is_aligned_and_not_null(dst, align, zero_size)
3745                && ub_checks::maybe_is_nonoverlapping(src, dst, size, count)
3746        }
3747    );
3748
3749    // SAFETY: the safety contract for `copy_nonoverlapping` must be
3750    // upheld by the caller.
3751    unsafe { copy_nonoverlapping(src, dst, count) }
3752}
3753
3754/// Copies `count * size_of::<T>()` bytes from `src` to `dst`. The source
3755/// and destination may overlap.
3756///
3757/// If the source and destination will *never* overlap,
3758/// [`copy_nonoverlapping`] can be used instead.
3759///
3760/// `copy` is semantically equivalent to C's [`memmove`], but
3761/// with the source and destination arguments swapped,
3762/// and `count` counting the number of `T`s instead of bytes.
3763/// Copying takes place as if the bytes were copied from `src`
3764/// to a temporary array and then copied from the array to `dst`.
3765///
3766/// The copy is "untyped" in the sense that data may be uninitialized or otherwise violate the
3767/// requirements of `T`. The initialization state is preserved exactly.
3768///
3769/// [`memmove`]: https://en.cppreference.com/w/c/string/byte/memmove
3770///
3771/// # Safety
3772///
3773/// Behavior is undefined if any of the following conditions are violated:
3774///
3775/// * `src` must be [valid] for reads of `count * size_of::<T>()` bytes.
3776///
3777/// * `dst` must be [valid] for writes of `count * size_of::<T>()` bytes, and must remain valid even
3778///   when `src` is read for `count * size_of::<T>()` bytes. (This means if the memory ranges
3779///   overlap, the `dst` pointer must not be invalidated by `src` reads.)
3780///
3781/// * Both `src` and `dst` must be properly aligned.
3782///
3783/// Like [`read`], `copy` creates a bitwise copy of `T`, regardless of
3784/// whether `T` is [`Copy`]. If `T` is not [`Copy`], using both the values
3785/// in the region beginning at `*src` and the region beginning at `*dst` can
3786/// [violate memory safety][read-ownership].
3787///
3788/// Note that even if the effectively copied size (`count * size_of::<T>()`) is
3789/// `0`, the pointers must be properly aligned.
3790///
3791/// [`read`]: crate::ptr::read
3792/// [read-ownership]: crate::ptr::read#ownership-of-the-returned-value
3793/// [valid]: crate::ptr#safety
3794///
3795/// # Examples
3796///
3797/// Efficiently create a Rust vector from an unsafe buffer:
3798///
3799/// ```
3800/// use std::ptr;
3801///
3802/// /// # Safety
3803/// ///
3804/// /// * `ptr` must be correctly aligned for its type and non-zero.
3805/// /// * `ptr` must be valid for reads of `elts` contiguous elements of type `T`.
3806/// /// * Those elements must not be used after calling this function unless `T: Copy`.
3807/// # #[allow(dead_code)]
3808/// unsafe fn from_buf_raw<T>(ptr: *const T, elts: usize) -> Vec<T> {
3809///     let mut dst = Vec::with_capacity(elts);
3810///
3811///     // SAFETY: Our precondition ensures the source is aligned and valid,
3812///     // and `Vec::with_capacity` ensures that we have usable space to write them.
3813///     unsafe { ptr::copy(ptr, dst.as_mut_ptr(), elts); }
3814///
3815///     // SAFETY: We created it with this much capacity earlier,
3816///     // and the previous `copy` has initialized these elements.
3817///     unsafe { dst.set_len(elts); }
3818///     dst
3819/// }
3820/// ```
3821#[doc(alias = "memmove")]
3822#[stable(feature = "rust1", since = "1.0.0")]
3823#[rustc_allowed_through_unstable_modules = "import this function via `std::ptr` instead"]
3824#[rustc_const_stable(feature = "const_intrinsic_copy", since = "1.83.0")]
3825#[inline(always)]
3826#[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
3827#[rustc_diagnostic_item = "ptr_copy"]
3828pub const unsafe fn copy<T>(src: *const T, dst: *mut T, count: usize) {
3829    #[rustc_intrinsic_const_stable_indirect]
3830    #[rustc_nounwind]
3831    #[rustc_intrinsic]
3832    const unsafe fn copy<T>(src: *const T, dst: *mut T, count: usize);
3833
3834    // SAFETY: the safety contract for `copy` must be upheld by the caller.
3835    unsafe {
3836        ub_checks::assert_unsafe_precondition!(
3837            check_language_ub,
3838            "ptr::copy requires that both pointer arguments are aligned and non-null",
3839            (
3840                src: *const () = src as *const (),
3841                dst: *mut () = dst as *mut (),
3842                align: usize = align_of::<T>(),
3843                zero_size: bool = T::IS_ZST || count == 0,
3844            ) =>
3845            ub_checks::maybe_is_aligned_and_not_null(src, align, zero_size)
3846                && ub_checks::maybe_is_aligned_and_not_null(dst, align, zero_size)
3847        );
3848        copy(src, dst, count)
3849    }
3850}
3851
3852/// Sets `count * size_of::<T>()` bytes of memory starting at `dst` to
3853/// `val`.
3854///
3855/// `write_bytes` is similar to C's [`memset`], but sets `count *
3856/// size_of::<T>()` bytes to `val`.
3857///
3858/// [`memset`]: https://en.cppreference.com/w/c/string/byte/memset
3859///
3860/// # Safety
3861///
3862/// Behavior is undefined if any of the following conditions are violated:
3863///
3864/// * `dst` must be [valid] for writes of `count * size_of::<T>()` bytes.
3865///
3866/// * `dst` must be properly aligned.
3867///
3868/// Note that even if the effectively copied size (`count * size_of::<T>()`) is
3869/// `0`, the pointer must be properly aligned.
3870///
3871/// Additionally, note that changing `*dst` in this way can easily lead to undefined behavior (UB)
3872/// later if the written bytes are not a valid representation of some `T`. For instance, the
3873/// following is an **incorrect** use of this function:
3874///
3875/// ```rust,no_run
3876/// unsafe {
3877///     let mut value: u8 = 0;
3878///     let ptr: *mut bool = &mut value as *mut u8 as *mut bool;
3879///     let _bool = ptr.read(); // This is fine, `ptr` points to a valid `bool`.
3880///     ptr.write_bytes(42u8, 1); // This function itself does not cause UB...
3881///     let _bool = ptr.read(); // ...but it makes this operation UB! ⚠️
3882/// }
3883/// ```
3884///
3885/// [valid]: crate::ptr#safety
3886///
3887/// # Examples
3888///
3889/// Basic usage:
3890///
3891/// ```
3892/// use std::ptr;
3893///
3894/// let mut vec = vec![0u32; 4];
3895/// unsafe {
3896///     let vec_ptr = vec.as_mut_ptr();
3897///     ptr::write_bytes(vec_ptr, 0xfe, 2);
3898/// }
3899/// assert_eq!(vec, [0xfefefefe, 0xfefefefe, 0, 0]);
3900/// ```
3901#[doc(alias = "memset")]
3902#[stable(feature = "rust1", since = "1.0.0")]
3903#[rustc_allowed_through_unstable_modules = "import this function via `std::ptr` instead"]
3904#[rustc_const_stable(feature = "const_ptr_write", since = "1.83.0")]
3905#[inline(always)]
3906#[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
3907#[rustc_diagnostic_item = "ptr_write_bytes"]
3908pub const unsafe fn write_bytes<T>(dst: *mut T, val: u8, count: usize) {
3909    #[rustc_intrinsic_const_stable_indirect]
3910    #[rustc_nounwind]
3911    #[rustc_intrinsic]
3912    const unsafe fn write_bytes<T>(dst: *mut T, val: u8, count: usize);
3913
3914    // SAFETY: the safety contract for `write_bytes` must be upheld by the caller.
3915    unsafe {
3916        ub_checks::assert_unsafe_precondition!(
3917            check_language_ub,
3918            "ptr::write_bytes requires that the destination pointer is aligned and non-null",
3919            (
3920                addr: *const () = dst as *const (),
3921                align: usize = align_of::<T>(),
3922                zero_size: bool = T::IS_ZST || count == 0,
3923            ) => ub_checks::maybe_is_aligned_and_not_null(addr, align, zero_size)
3924        );
3925        write_bytes(dst, val, count)
3926    }
3927}
3928
3929/// Returns the minimum of two `f16` values.
3930///
3931/// Note that, unlike most intrinsics, this is safe to call;
3932/// it does not require an `unsafe` block.
3933/// Therefore, implementations must not require the user to uphold
3934/// any safety invariants.
3935///
3936/// The stabilized version of this intrinsic is
3937/// [`f16::min`]
3938#[rustc_nounwind]
3939#[rustc_intrinsic]
3940pub const fn minnumf16(x: f16, y: f16) -> f16;
3941
3942/// Returns the minimum of two `f32` values.
3943///
3944/// Note that, unlike most intrinsics, this is safe to call;
3945/// it does not require an `unsafe` block.
3946/// Therefore, implementations must not require the user to uphold
3947/// any safety invariants.
3948///
3949/// The stabilized version of this intrinsic is
3950/// [`f32::min`]
3951#[rustc_nounwind]
3952#[rustc_intrinsic_const_stable_indirect]
3953#[rustc_intrinsic]
3954pub const fn minnumf32(x: f32, y: f32) -> f32;
3955
3956/// Returns the minimum of two `f64` values.
3957///
3958/// Note that, unlike most intrinsics, this is safe to call;
3959/// it does not require an `unsafe` block.
3960/// Therefore, implementations must not require the user to uphold
3961/// any safety invariants.
3962///
3963/// The stabilized version of this intrinsic is
3964/// [`f64::min`]
3965#[rustc_nounwind]
3966#[rustc_intrinsic_const_stable_indirect]
3967#[rustc_intrinsic]
3968pub const fn minnumf64(x: f64, y: f64) -> f64;
3969
3970/// Returns the minimum of two `f128` values.
3971///
3972/// Note that, unlike most intrinsics, this is safe to call;
3973/// it does not require an `unsafe` block.
3974/// Therefore, implementations must not require the user to uphold
3975/// any safety invariants.
3976///
3977/// The stabilized version of this intrinsic is
3978/// [`f128::min`]
3979#[rustc_nounwind]
3980#[rustc_intrinsic]
3981pub const fn minnumf128(x: f128, y: f128) -> f128;
3982
3983/// Returns the maximum of two `f16` values.
3984///
3985/// Note that, unlike most intrinsics, this is safe to call;
3986/// it does not require an `unsafe` block.
3987/// Therefore, implementations must not require the user to uphold
3988/// any safety invariants.
3989///
3990/// The stabilized version of this intrinsic is
3991/// [`f16::max`]
3992#[rustc_nounwind]
3993#[rustc_intrinsic]
3994pub const fn maxnumf16(x: f16, y: f16) -> f16;
3995
3996/// Returns the maximum of two `f32` values.
3997///
3998/// Note that, unlike most intrinsics, this is safe to call;
3999/// it does not require an `unsafe` block.
4000/// Therefore, implementations must not require the user to uphold
4001/// any safety invariants.
4002///
4003/// The stabilized version of this intrinsic is
4004/// [`f32::max`]
4005#[rustc_nounwind]
4006#[rustc_intrinsic_const_stable_indirect]
4007#[rustc_intrinsic]
4008pub const fn maxnumf32(x: f32, y: f32) -> f32;
4009
4010/// Returns the maximum of two `f64` values.
4011///
4012/// Note that, unlike most intrinsics, this is safe to call;
4013/// it does not require an `unsafe` block.
4014/// Therefore, implementations must not require the user to uphold
4015/// any safety invariants.
4016///
4017/// The stabilized version of this intrinsic is
4018/// [`f64::max`]
4019#[rustc_nounwind]
4020#[rustc_intrinsic_const_stable_indirect]
4021#[rustc_intrinsic]
4022pub const fn maxnumf64(x: f64, y: f64) -> f64;
4023
4024/// Returns the maximum of two `f128` values.
4025///
4026/// Note that, unlike most intrinsics, this is safe to call;
4027/// it does not require an `unsafe` block.
4028/// Therefore, implementations must not require the user to uphold
4029/// any safety invariants.
4030///
4031/// The stabilized version of this intrinsic is
4032/// [`f128::max`]
4033#[rustc_nounwind]
4034#[rustc_intrinsic]
4035pub const fn maxnumf128(x: f128, y: f128) -> f128;
4036
4037/// Returns the absolute value of an `f16`.
4038///
4039/// The stabilized version of this intrinsic is
4040/// [`f16::abs`](../../std/primitive.f16.html#method.abs)
4041#[rustc_nounwind]
4042#[rustc_intrinsic]
4043pub const unsafe fn fabsf16(x: f16) -> f16;
4044
4045/// Returns the absolute value of an `f32`.
4046///
4047/// The stabilized version of this intrinsic is
4048/// [`f32::abs`](../../std/primitive.f32.html#method.abs)
4049#[rustc_nounwind]
4050#[rustc_intrinsic_const_stable_indirect]
4051#[rustc_intrinsic]
4052pub const unsafe fn fabsf32(x: f32) -> f32;
4053
4054/// Returns the absolute value of an `f64`.
4055///
4056/// The stabilized version of this intrinsic is
4057/// [`f64::abs`](../../std/primitive.f64.html#method.abs)
4058#[rustc_nounwind]
4059#[rustc_intrinsic_const_stable_indirect]
4060#[rustc_intrinsic]
4061pub const unsafe fn fabsf64(x: f64) -> f64;
4062
4063/// Returns the absolute value of an `f128`.
4064///
4065/// The stabilized version of this intrinsic is
4066/// [`f128::abs`](../../std/primitive.f128.html#method.abs)
4067#[rustc_nounwind]
4068#[rustc_intrinsic]
4069pub const unsafe fn fabsf128(x: f128) -> f128;
4070
4071/// Copies the sign from `y` to `x` for `f16` values.
4072///
4073/// The stabilized version of this intrinsic is
4074/// [`f16::copysign`](../../std/primitive.f16.html#method.copysign)
4075#[rustc_nounwind]
4076#[rustc_intrinsic]
4077pub const unsafe fn copysignf16(x: f16, y: f16) -> f16;
4078
4079/// Copies the sign from `y` to `x` for `f32` values.
4080///
4081/// The stabilized version of this intrinsic is
4082/// [`f32::copysign`](../../std/primitive.f32.html#method.copysign)
4083#[rustc_nounwind]
4084#[rustc_intrinsic_const_stable_indirect]
4085#[rustc_intrinsic]
4086pub const unsafe fn copysignf32(x: f32, y: f32) -> f32;
4087/// Copies the sign from `y` to `x` for `f64` values.
4088///
4089/// The stabilized version of this intrinsic is
4090/// [`f64::copysign`](../../std/primitive.f64.html#method.copysign)
4091#[rustc_nounwind]
4092#[rustc_intrinsic_const_stable_indirect]
4093#[rustc_intrinsic]
4094pub const unsafe fn copysignf64(x: f64, y: f64) -> f64;
4095
4096/// Copies the sign from `y` to `x` for `f128` values.
4097///
4098/// The stabilized version of this intrinsic is
4099/// [`f128::copysign`](../../std/primitive.f128.html#method.copysign)
4100#[rustc_nounwind]
4101#[rustc_intrinsic]
4102pub const unsafe fn copysignf128(x: f128, y: f128) -> f128;
4103
4104/// Inform Miri that a given pointer definitely has a certain alignment.
4105#[cfg(miri)]
4106#[rustc_allow_const_fn_unstable(const_eval_select)]
4107pub(crate) const fn miri_promise_symbolic_alignment(ptr: *const (), align: usize) {
4108    unsafe extern "Rust" {
4109        /// Miri-provided extern function to promise that a given pointer is properly aligned for
4110        /// "symbolic" alignment checks. Will fail if the pointer is not actually aligned or `align` is
4111        /// not a power of two. Has no effect when alignment checks are concrete (which is the default).
4112        fn miri_promise_symbolic_alignment(ptr: *const (), align: usize);
4113    }
4114
4115    const_eval_select!(
4116        @capture { ptr: *const (), align: usize}:
4117        if const {
4118            // Do nothing.
4119        } else {
4120            // SAFETY: this call is always safe.
4121            unsafe {
4122                miri_promise_symbolic_alignment(ptr, align);
4123            }
4124        }
4125    )
4126}