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