Module intrinsics

🔬This is a nightly-only experimental API. (core_intrinsics)

Expand description

Compiler intrinsics.

The functions in this module are implementation details of core and should not be used outside of the standard library. We generally provide access to intrinsics via stable wrapper functions. Use these instead.

These are the imports making intrinsics available to Rust code. The actual implementations live in the compiler. 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. 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 and https://github.com/rust-lang/rust/blob/HEAD/compiler/rustc_codegen_llvm/src/intrinsic.rs, and for const evaluation in https://github.com/rust-lang/rust/blob/HEAD/compiler/rustc_const_eval/src/interpret/intrinsics.rs.

§Const intrinsics

In order to make an intrinsic unstable usable at compile-time, copy the implementation from https://github.com/rust-lang/miri/blob/master/src/intrinsics to https://github.com/rust-lang/rust/blob/HEAD/compiler/rustc_const_eval/src/interpret/intrinsics.rs and make the intrinsic declaration below a const fn. This should be done in coordination with wg-const-eval.

If an intrinsic is supposed to be used from a const fn with a rustc_const_stable attribute, #[rustc_intrinsic_const_stable_indirect] needs to be added to the intrinsic. Such a change requires T-lang approval, because it may bake a feature into the language that cannot be replicated in user code without compiler support.

§Volatiles

The volatile intrinsics provide operations intended to act on I/O memory, which are guaranteed to not be reordered by the compiler across other volatile intrinsics. See read_volatile and write_volatile.

§Atomics

The atomic intrinsics provide common atomic operations on machine words, with multiple possible memory orderings. See the [atomic types][atomic] docs for details.

§Unwinding

Rust intrinsics may, in general, unwind. If an intrinsic can never unwind, add the #[rustc_nounwind] attribute so that the compiler can make use of this fact.

However, even for intrinsics that may unwind, rustc assumes that a Rust intrinsics will never initiate a foreign (non-Rust) unwind, and thus for panic=abort we can always assume that these intrinsics cannot unwind.

Enums§

AtomicOrderingExperimental: A type for atomic ordering parameters for intrinsics. This is a separate type from atomic::Ordering so that we can make it ConstParamTy and fix the values used here without a risk of leaking that to stable code.

Functions§

copy^⚠Deprecated: This is an accidentally-stable alias to ptr::copy; use that instead.
copy_nonoverlapping^⚠Deprecated: This is an accidentally-stable alias to ptr::copy_nonoverlapping; use that instead.
transmute^⚠Deprecated: Reinterprets the bits of a value of one type as another type.
write_bytes^⚠Deprecated: This is an accidentally-stable alias to ptr::write_bytes; use that instead.
abortExperimental: Aborts the execution of the process.
add_with_overflowExperimental: Performs checked integer addition.
aggregate_raw_ptrExperimental: Lowers in MIR to Rvalue::Aggregate with AggregateKind::RawPtr.
align_ofExperimental: The minimum alignment of a type.
align_of_val^⚠Experimental: The required alignment of the referenced value.
assert_inhabitedExperimental: A guard for unsafe functions that cannot ever be executed if T is uninhabited: This will statically either panic, or do nothing. It does not guarantee to ever panic, and should only be called if an assertion failure will imply language UB in the following code.
assume^⚠Experimental: Informs the optimizer that a condition is always true. If the condition is false, the behavior is undefined.
atomic_and^⚠Experimental: Bitwise and with the current value, returning the previous value. T must be an integer or pointer type. U must be the same as T if that is an integer type, or usize if T is a pointer type.
atomic_cxchg^⚠Experimental: Stores a value if the current value is the same as the old value. T must be an integer or pointer type.
atomic_cxchgweak^⚠Experimental: Stores a value if the current value is the same as the old value. T must be an integer or pointer type. The comparison may spuriously fail.
atomic_load^⚠Experimental: Loads the current value of the pointer. T must be an integer or pointer type.
atomic_nand^⚠Experimental: Bitwise nand with the current value, returning the previous value. T must be an integer or pointer type. U must be the same as T if that is an integer type, or usize if T is a pointer type.
atomic_or^⚠Experimental: Bitwise or with the current value, returning the previous value. T must be an integer or pointer type. U must be the same as T if that is an integer type, or usize if T is a pointer type.
atomic_store^⚠Experimental: Stores the value at the specified memory location. T must be an integer or pointer type.
atomic_umax^⚠Experimental: Maximum with the current value using an unsigned comparison. T must be an unsigned integer type.
atomic_umin^⚠Experimental: Minimum with the current value using an unsigned comparison. T must be an unsigned integer type.
atomic_xadd^⚠Experimental: Adds to the current value, returning the previous value. T must be an integer or pointer type. U must be the same as T if that is an integer type, or usize if T is a pointer type.
atomic_xchg^⚠Experimental: Stores the value at the specified memory location, returning the old value. T must be an integer or pointer type.
atomic_xor^⚠Experimental: Bitwise xor with the current value, returning the previous value. T must be an integer or pointer type. U must be the same as T if that is an integer type, or usize if T is a pointer type.
atomic_xsub^⚠Experimental: Subtract from the current value, returning the previous value. T must be an integer or pointer type. U must be the same as T if that is an integer type, or usize if T is a pointer type.
autodiffExperimental: Generates the LLVM body for the automatic differentiation of f using Enzyme, with df as the derivative function and args as its arguments.
cold_pathExperimental: Hints to the compiler that current code path is cold.
const_eval_selectExperimental: Selects which function to call depending on the context.
const_make_global^⚠Experimental
ctpopExperimental: Returns the number of bits set in an integer type T
cttz_nonzero^⚠Experimental: Like cttz, but extra-unsafe as it returns undef when given an x with value 0.
discriminant_valueExperimental: Returns the value of the discriminant for the variant in ‘v’; if T has no discriminant, returns 0.
exact_div^⚠Experimental: Performs an exact division, resulting in undefined behavior where x % y != 0 or y == 0 or x == T::MIN && y == -1
mul_with_overflowExperimental: Performs checked integer multiplication
needs_dropExperimental: Returns true if the actual type given as T requires drop glue; returns false if the actual type provided for T implements Copy.
offset^⚠Experimental: Calculates the offset from a pointer.
ptr_guaranteed_cmpExperimental: See documentation of <*const T>::guaranteed_eq for details. Returns 2 if the result is unknown. Returns 1 if the pointers are guaranteed equal. Returns 0 if the pointers are guaranteed inequal.
ptr_metadataExperimental: Lowers in MIR to Rvalue::UnaryOp with UnOp::PtrMetadata.
read_via_copy^⚠Experimental: This is an implementation detail of crate::ptr::read and should not be used anywhere else. See its comments for why this exists.
size_ofExperimental: The size of a type in bytes.
size_of_val^⚠Experimental: The size of the referenced value in bytes.
slice_get_unchecked^⚠Experimental: Projects to the index-th element of slice_ptr, as the same kind of pointer as the slice was provided – so &mut [T] → &mut T, &[T] → &T, *mut [T] → *mut T, or *const [T] → *const T – without a bounds check.
sub_with_overflowExperimental: Performs checked integer subtraction
three_way_compareExperimental: Does a three-way comparison between the two arguments, which must be of character or integer (signed or unsigned) type.
transmute_unchecked^⚠Experimental: Like transmute, but even less checked at compile-time: rather than giving an error for size_of::<Src>() != size_of::<Dst>(), it’s Undefined Behavior at runtime.
type_idExperimental: Gets an identifier which is globally unique to the specified type. This function will return the same value for a type regardless of whichever crate it is invoked in.
type_id_eqExperimental: Tests (at compile-time) if two crate::any::TypeId instances identify the same type. This is necessary because at const-eval time the actual discriminating data is opaque and cannot be inspected directly.
type_nameExperimental: Gets a static string slice containing the name of a type.
ub_checksExperimental: Returns whether we should perform some UB-checking at runtime. This eventually evaluates to cfg!(ub_checks), but behaves different from cfg! when mixing crates built with different flags: if the crate has UB checks enabled or carries the #[rustc_preserve_ub_checks] attribute, evaluation is delayed until monomorphization (or until the call gets inlined into a crate that does not delay evaluation further); otherwise it can happen any time.
unchecked_add^⚠Experimental: Returns the result of an unchecked addition, resulting in undefined behavior when x + y > T::MAX or x + y < T::MIN.
unchecked_rem^⚠Experimental: Returns the remainder of an unchecked division, resulting in undefined behavior when y == 0 or x == T::MIN && y == -1
unchecked_shl^⚠Experimental: Performs an unchecked left shift, resulting in undefined behavior when y < 0 or y >= N, where N is the width of T in bits.
unchecked_shr^⚠Experimental: Performs an unchecked right shift, resulting in undefined behavior when y < 0 or y >= N, where N is the width of T in bits.
unchecked_sub^⚠Experimental: Returns the result of an unchecked subtraction, resulting in undefined behavior when x - y > T::MAX or x - y < T::MIN.
unlikelyExperimental: Hints to the compiler that branch condition is likely to be false. Returns the value passed to it.
unreachable^⚠Experimental: Informs the optimizer that this point in the code is not reachable, enabling further optimizations.
volatile_load^⚠Experimental: Performs a volatile load from the src pointer.
volatile_store^⚠Experimental: Performs a volatile store to the dst pointer.
wrapping_addExperimental: Returns (a + b) mod 2^N, where N is the width of T in bits.
wrapping_mulExperimental: Returns (a * b) mod 2^N, where N is the width of T in bits.
wrapping_subExperimental: Returns (a - b) mod 2^N, where N is the width of T in bits.
write_via_move^⚠Experimental: This is an implementation detail of crate::ptr::write and should not be used anywhere else. See its comments for why this exists.