mod.rs - source
Skip to main content core/intrinsics/ mod.rs 1 //! Compiler intrinsics. 2 //! 3 //! The functions in this module are implementation details of `core` and should 4 //! not be used outside of the standard library. We generally provide access to 5 //! intrinsics via stable wrapper functions. Use these instead. 6 //! 7 //! These are the imports making intrinsics available to Rust code. The actual implementations live in the compiler.
8 //! Some of these intrinsics are lowered to MIR in <https://github.com/rust-lang/rust/blob/HEAD/compiler/rustc_mir_transform/src/lower_intrinsics.rs>. 9 //! The remaining intrinsics are implemented for the LLVM backend in <https://github.com/rust-lang/rust/blob/HEAD/compiler/rustc_codegen_ssa/src/mir/intrinsic.rs> 10 //! and <https://github.com/rust-lang/rust/blob/HEAD/compiler/rustc_codegen_llvm/src/intrinsic.rs>, 11 //! and for const evaluation in <https://github.com/rust-lang/rust/blob/HEAD/compiler/rustc_const_eval/src/interpret/intrinsics.rs>.
12 //! 13 //! Intrinsics don't need a body. However, they optionally can have a body, which we call the 14 //! "fallback body". This will be used by codegen backends that do not have a dedicated 15 //! implementation of the intrinsic, making it easier to add new intrinsics for specific operations 16 //! without having to implement them in each codegen backend. The fallback body obviously has to be 17 //! a valid implementation of the documented specification of the intrinsic.
In some cases, the 18 //! fallback body will be *equivalent* to the specification. Note that this is a strong requirement: 19 //! if the spec says "UB if input `x` is even", then a valid implementation can just ignore this and 20 //! do whatever it wants in that case; an *equivalent* implementation needs to actually check this 21 //! condition and trigger UB in that case (e.g. by using `hint::assert_unchecked()`). Similar, if 22 //! the spec says "returns `x` or `y` non-deterministically", then an *equivalent* implementation 23 //! must actually do non-deterministic choice and return either value (e.g. by invoking some other 24 //! language operation that has the same non-determinism).
Intrinsics with such a fallback body that 25 //! is equivalent to the spec may be marked with `#[miri::intrinsic_fallback_is_spec]`; the fallback 26 //! body will then also be used by Miri for UB checking. When in doubt, do not use this attribute or 27 //! ask the Miri maintainers for advice. 28 //! 29 //! Intrinsics are, in general, language extensions. Therefore, t-lang should be involved whenever a 30 //! new intrinsic is exposed to stable code.
However, if an intrinsic is marked 31 //! `#[miri::intrinsic_fallback_is_spec]` with a fallback body that only uses stable features (or if 32 //! such a fallback body could be written, but for one reason or another the actual fallback body is 33 //! different), and if it also does not make other promises that go beyond observable program 34 //! behavior (such as steering the optimizer in a particular direction), then an intrinsic may be 35 //! used without t-lang involvement.
36 //! 37 //! # Const intrinsics 38 //! 39 //! In order to make an intrinsic unstable usable at compile-time, copy the implementation from 40 //! <https://github.com/rust-lang/miri/blob/master/src/intrinsics> to 41 //! <https://github.com/rust-lang/rust/blob/HEAD/compiler/rustc_const_eval/src/interpret/intrinsics.rs> 42 //! and make the intrinsic declaration below a `const fn`. This should be done in coordination with 43 //! wg-const-eval.
44 //! 45 //! If an intrinsic is supposed to be used from a `const fn` with a `rustc_const_stable` attribute, 46 //! `#[rustc_intrinsic_const_stable_indirect]` needs to be added to the intrinsic. Such a change 47 //! requires T-lang approval, because it may bake a feature into the language that cannot be 48 //! replicated in user code without compiler support. The same exception as above applies for 49 //! `#[miri::intrinsic_fallback_is_spec]` intrinsics.
50 //! 51 //! # Volatiles 52 //! 53 //! The volatile intrinsics provide operations intended to act on I/O 54 //! memory, which are guaranteed to not be reordered by the compiler 55 //! across other volatile intrinsics. See [`read_volatile`][ptr::read_volatile] 56 //! and [`write_volatile`][ptr::write_volatile]. 57 //! 58 //! # Atomics 59 //! 60 //! The atomic intrinsics provide common atomic operations on machine 61 //! words, with multiple possible memory orderings.
See the 62 //! [atomic types][atomic] docs for details. 63 //! 64 //! # Unwinding 65 //! 66 //! Rust intrinsics may, in general, unwind. If an intrinsic can never unwind, add the 67 //! `#[rustc_nounwind]` attribute so that the compiler can make use of this fact. 68 //! 69 //! However, even for intrinsics that may unwind, rustc assumes that a Rust intrinsics will never 70 //! initiate a foreign (non-Rust) unwind, and thus for panic=abort we can always assume that these 71 //! intrinsics cannot unwind.
72 73 #![unstable( 74 feature = "core_intrinsics" , 75 reason = "intrinsics are unlikely to ever be stabilized, instead \ 76 they should be used through stabilized interfaces \ 77 in the rest of the standard library" , 78 issue = "none" 79 )] 80 81 use crate ::ffi::{ VaArgSafe , VaList }; 82 use crate ::marker::{ ConstParamTy , DiscriminantKind , PointeeSized , Tuple }; 83 use crate ::num::imp::libm ; 84 use crate ::{ mem , ptr }; 85 86 mod bounds ; 87 pub mod fallback ; 88 pub mod gpu ; 89 mod macros ; 90 pub mod mir ; 91 pub mod simd ; 92 93 use macros::intrinsic_dispatch_on_type ; 94 95 // These imports are used for simplifying intra-doc links 96 #[allow(unused_imports)] 97 #[cfg(all(target_has_atomic = "8" , target_has_atomic = "32" , target_has_atomic = "ptr" ))] 98 use crate ::sync::atomic::{ self , AtomicBool , AtomicI32 , AtomicIsize , AtomicU32 , Ordering }; 99 100 /// A type for atomic ordering parameters for intrinsics.
This is a separate type from 101 /// `atomic::Ordering` so that we can make it `ConstParamTy` and fix the values used here without a 102 /// risk of leaking that to stable code. 103 #[allow(missing_docs)] 104 #[derive( Debug , ConstParamTy , PartialEq , Eq )] 105 pub enum AtomicOrdering { 106 // These values must match the compiler's `AtomicOrdering` defined in 107 // `rustc_middle/src/ty/consts/int.rs`! 108 Relaxed = 0 , 109 Release = 1 , 110 Acquire = 2 , 111 AcqRel = 3 , 112 SeqCst = 4 , 113 } 114 115 // N.B., these intrinsics take raw pointers because they mutate aliased 116 // memory, which is not valid for either `&` or `&mut`.
117 118 /// Stores a value if the current value is the same as the `old` value. 119 /// `T` must be an integer or pointer type. 120 /// 121 /// The stabilized version of this intrinsic is available on the 122 /// [`atomic`] types via the `compare_exchange` method. 123 /// For example, [`AtomicBool::compare_exchange`]. 124 #[rustc_intrinsic] 125 #[rustc_nounwind] 126 pub const unsafe fn atomic_cxchg < 127 T: Copy , 128 const ORD_SUCC: AtomicOrdering , 129 const ORD_FAIL: AtomicOrdering , 130 >( 131 dst: *mut T, 132 old: T, 133 src: T, 134 ) -> (T, bool ); 135 136 /// Stores a value if the current value is the same as the `old` value.
137 /// `T` must be an integer or pointer type. The comparison may spuriously fail. 138 /// 139 /// The stabilized version of this intrinsic is available on the 140 /// [`atomic`] types via the `compare_exchange_weak` method. 141 /// For example, [`AtomicBool::compare_exchange_weak`]. 142 #[rustc_intrinsic] 143 #[rustc_nounwind] 144 pub const unsafe fn atomic_cxchgweak < 145 T: Copy , 146 const ORD_SUCC: AtomicOrdering , 147 const ORD_FAIL: AtomicOrdering , 148 >( 149 _dst: *mut T, 150 _old: T, 151 _src: T, 152 ) -> (T, bool ); 153 154 /// Loads the current value of the pointer.
155 /// `T` must be an integer or pointer type. 156 /// 157 /// # Safety 158 /// 159 /// * If `VOLATILE` is `true`, this is equivalent to [Atomic::load_volatile]. 160 /// Refer to the documentation of t
The rest of this page is on the live site.