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