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

Compiler intrinsics.

The corresponding definitions are in https://github.com/rust-lang/rust/blob/master/compiler/rustc_codegen_llvm/src/intrinsic.rs. The corresponding const implementations are in https://github.com/rust-lang/rust/blob/master/compiler/rustc_const_eval/src/interpret/intrinsics.rs.

Const intrinsics

Note: any changes to the constness of intrinsics should be discussed with the language team. This includes changes in the stability of the constness.

In order to make an intrinsic usable at compile-time, one needs to copy the implementation from https://github.com/rust-lang/miri/blob/master/src/shims/intrinsics.rs to https://github.com/rust-lang/rust/blob/master/compiler/rustc_const_eval/src/interpret/intrinsics.rs and add a #[rustc_const_unstable(feature = "const_such_and_such", issue = "01234")] to the intrinsic declaration.

If an intrinsic is supposed to be used from a const fn with a rustc_const_stable attribute, the intrinsic’s attribute must be rustc_const_stable, too. Such a change should not be done without T-lang consultation, because it bakes 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 the LLVM documentation on [volatile].

Atomics

The atomic intrinsics provide common atomic operations on machine words, with multiple possible memory orderings. They obey the same semantics as C++11. See the LLVM documentation on [atomics].

A quick refresher on memory ordering:

  • Acquire - a barrier for acquiring a lock. Subsequent reads and writes take place after the barrier.
  • Release - a barrier for releasing a lock. Preceding reads and writes take place before the barrier.
  • Sequentially consistent - sequentially consistent operations are guaranteed to happen in order. This is the standard mode for working with atomic types and is equivalent to Java’s volatile.

Functions

abortExperimental
Aborts the execution of the process.
add_with_overflowExperimental
Performs checked integer addition.
arith_offsetExperimental
Calculates the offset from a pointer, potentially wrapping.
assert_inhabitedExperimental
A guard for unsafe functions that cannot ever be executed if T is uninhabited: This will statically either panic, or do nothing.
A guard for unsafe functions that cannot ever be executed if T has invalid bit patterns: This will statically either panic, or do nothing.
assert_zero_validExperimental
A guard for unsafe functions that cannot ever be executed if T does not permit zero-initialization: This will statically either panic, or do nothing.
assumeExperimental
Informs the optimizer that a condition is always true. If the condition is false, the behavior is undefined.
atomic_and_acqrelExperimental
Bitwise and with the current value, returning the previous value.
atomic_and_acquireExperimental
Bitwise and with the current value, returning the previous value.
atomic_and_relaxedExperimental
Bitwise and with the current value, returning the previous value.
atomic_and_releaseExperimental
Bitwise and with the current value, returning the previous value.
atomic_and_seqcstExperimental
Bitwise and with the current value, returning the previous value.
Stores a value if the current value is the same as the old value.
Stores a value if the current value is the same as the old value.
Stores a value if the current value is the same as the old value.
Stores a value if the current value is the same as the old value.
Stores a value if the current value is the same as the old value.
Stores a value if the current value is the same as the old value.
Stores a value if the current value is the same as the old value.
Stores a value if the current value is the same as the old value.
Stores a value if the current value is the same as the old value.
Stores a value if the current value is the same as the old value.
Stores a value if the current value is the same as the old value.
Stores a value if the current value is the same as the old value.
Stores a value if the current value is the same as the old value.
Stores a value if the current value is the same as the old value.
Stores a value if the current value is the same as the old value.
Stores a value if the current value is the same as the old value.
Stores a value if the current value is the same as the old value.
Stores a value if the current value is the same as the old value.
Stores a value if the current value is the same as the old value.
Stores a value if the current value is the same as the old value.
Stores a value if the current value is the same as the old value.
Stores a value if the current value is the same as the old value.
Stores a value if the current value is the same as the old value.
Stores a value if the current value is the same as the old value.
Stores a value if the current value is the same as the old value.
Stores a value if the current value is the same as the old value.
Stores a value if the current value is the same as the old value.
Stores a value if the current value is the same as the old value.
Stores a value if the current value is the same as the old value.
Stores a value if the current value is the same as the old value.
atomic_fence_acqrelExperimental
An atomic fence.
atomic_fence_acquireExperimental
An atomic fence.
atomic_fence_releaseExperimental
An atomic fence.
atomic_fence_seqcstExperimental
An atomic fence.
atomic_load_acquireExperimental
Loads the current value of the pointer.
atomic_load_relaxedExperimental
Loads the current value of the pointer.
atomic_load_seqcstExperimental
Loads the current value of the pointer.
atomic_load_unorderedExperimental
atomic_max_acqrelExperimental
Maximum with the current value using a signed comparison.
atomic_max_acquireExperimental
Maximum with the current value using a signed comparison.
atomic_max_relaxedExperimental
Maximum with the current value.
atomic_max_releaseExperimental
Maximum with the current value using a signed comparison.
atomic_max_seqcstExperimental
Maximum with the current value using a signed comparison.
atomic_min_acqrelExperimental
Minimum with the current value using a signed comparison.
atomic_min_acquireExperimental
Minimum with the current value using a signed comparison.
atomic_min_relaxedExperimental
Minimum with the current value using a signed comparison.
atomic_min_releaseExperimental
Minimum with the current value using a signed comparison.
atomic_min_seqcstExperimental
Minimum with the current value using a signed comparison.
atomic_nand_acqrelExperimental
Bitwise nand with the current value, returning the previous value.
atomic_nand_acquireExperimental
Bitwise nand with the current value, returning the previous value.
atomic_nand_relaxedExperimental
Bitwise nand with the current value, returning the previous value.
atomic_nand_releaseExperimental
Bitwise nand with the current value, returning the previous value.
atomic_nand_seqcstExperimental
Bitwise nand with the current value, returning the previous value.
atomic_or_acqrelExperimental
Bitwise or with the current value, returning the previous value.
atomic_or_acquireExperimental
Bitwise or with the current value, returning the previous value.
atomic_or_relaxedExperimental
Bitwise or with the current value, returning the previous value.
atomic_or_releaseExperimental
Bitwise or with the current value, returning the previous value.
atomic_or_seqcstExperimental
Bitwise or with the current value, returning the previous value.
A compiler-only memory barrier.
A compiler-only memory barrier.
A compiler-only memory barrier.
A compiler-only memory barrier.
atomic_store_relaxedExperimental
Stores the value at the specified memory location.
atomic_store_releaseExperimental
Stores the value at the specified memory location.
atomic_store_seqcstExperimental
Stores the value at the specified memory location.
atomic_store_unorderedExperimental
atomic_umax_acqrelExperimental
Maximum with the current value using an unsigned comparison.
atomic_umax_acquireExperimental
Maximum with the current value using an unsigned comparison.
atomic_umax_relaxedExperimental
Maximum with the current value using an unsigned comparison.
atomic_umax_releaseExperimental
Maximum with the current value using an unsigned comparison.
atomic_umax_seqcstExperimental
Maximum with the current value using an unsigned comparison.
atomic_umin_acqrelExperimental
Minimum with the current value using an unsigned comparison.
atomic_umin_acquireExperimental
Minimum with the current value using an unsigned comparison.
atomic_umin_relaxedExperimental
Minimum with the current value using an unsigned comparison.
atomic_umin_releaseExperimental
Minimum with the current value using an unsigned comparison.
atomic_umin_seqcstExperimental
Minimum with the current value using an unsigned comparison.
atomic_xadd_acqrelExperimental
Adds to the current value, returning the previous value.
atomic_xadd_acquireExperimental
Adds to the current value, returning the previous value.
atomic_xadd_relaxedExperimental
Adds to the current value, returning the previous value.
atomic_xadd_releaseExperimental
Adds to the current value, returning the previous value.
atomic_xadd_seqcstExperimental
Adds to the current value, returning the previous value.
atomic_xchg_acqrelExperimental
Stores the value at the specified memory location, returning the old value.
atomic_xchg_acquireExperimental
Stores the value at the specified memory location, returning the old value.
atomic_xchg_relaxedExperimental
Stores the value at the specified memory location, returning the old value.
atomic_xchg_releaseExperimental
Stores the value at the specified memory location, returning the old value.
atomic_xchg_seqcstExperimental
Stores the value at the specified memory location, returning the old value.
atomic_xor_acqrelExperimental
Bitwise xor with the current value, returning the previous value.
atomic_xor_acquireExperimental
Bitwise xor with the current value, returning the previous value.
atomic_xor_relaxedExperimental
Bitwise xor with the current value, returning the previous value.
atomic_xor_releaseExperimental
Bitwise xor with the current value, returning the previous value.
atomic_xor_seqcstExperimental
Bitwise xor with the current value, returning the previous value.
atomic_xsub_acqrelExperimental
Subtract from the current value, returning the previous value.
atomic_xsub_acquireExperimental
Subtract from the current value, returning the previous value.
atomic_xsub_relaxedExperimental
Subtract from the current value, returning the previous value.
atomic_xsub_releaseExperimental
Subtract from the current value, returning the previous value.
atomic_xsub_seqcstExperimental
Subtract from the current value, returning the previous value.
bitreverseExperimental
Reverses the bits in an integer type T.
black_boxExperimental
See documentation of std::hint::black_box for details.
breakpointExperimental
Executes a breakpoint trap, for inspection by a debugger.
bswapExperimental
Reverses the bytes in an integer type T.
caller_locationExperimental
Gets a reference to a static Location indicating where it was called.
ceilf32Experimental
Returns the smallest integer greater than or equal to an f32.
ceilf64Experimental
Returns the smallest integer greater than or equal to an f64.
const_allocateExperimental
Allocates a block of memory at compile time. At runtime, just returns a null pointer.
const_deallocateExperimental
Deallocates a memory which allocated by intrinsics::const_allocate at compile time. At runtime, does nothing.
const_eval_selectExperimental
Selects which function to call depending on the context.
copysignf32Experimental
Copies the sign from y to x for f32 values.
copysignf64Experimental
Copies the sign from y to x for f64 values.
cosf32Experimental
Returns the cosine of an f32.
cosf64Experimental
Returns the cosine of an f64.
ctlzExperimental
Returns the number of leading unset bits (zeroes) in an integer type T.
ctlz_nonzeroExperimental
Like ctlz, but extra-unsafe as it returns undef when given an x with value 0.
ctpopExperimental
Returns the number of bits set in an integer type T
cttzExperimental
Returns the number of trailing unset bits (zeroes) in an integer type T.
cttz_nonzeroExperimental
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_divExperimental
Performs an exact division, resulting in undefined behavior where x % y != 0 or y == 0 or x == T::MIN && y == -1
exp2f32Experimental
Returns 2 raised to the power of an f32.
exp2f64Experimental
Returns 2 raised to the power of an f64.
expf32Experimental
Returns the exponential of an f32.
expf64Experimental
Returns the exponential of an f64.
fabsf32Experimental
Returns the absolute value of an f32.
fabsf64Experimental
Returns the absolute value of an f64.
fadd_fastExperimental
Float addition that allows optimizations based on algebraic rules. May assume inputs are finite.
fdiv_fastExperimental
Float division that allows optimizations based on algebraic rules. May assume inputs are finite.
float_to_int_uncheckedExperimental
Convert with LLVM’s fptoui/fptosi, which may return undef for values out of range (https://github.com/rust-lang/rust/issues/10184)
floorf32Experimental
Returns the largest integer less than or equal to an f32.
floorf64Experimental
Returns the largest integer less than or equal to an f64.
fmaf32Experimental
Returns a * b + c for f32 values.
fmaf64Experimental
Returns a * b + c for f64 values.
fmul_fastExperimental
Float multiplication that allows optimizations based on algebraic rules. May assume inputs are finite.
forgetExperimental
Moves a value out of scope without running drop glue.
frem_fastExperimental
Float remainder that allows optimizations based on algebraic rules. May assume inputs are finite.
fsub_fastExperimental
Float subtraction that allows optimizations based on algebraic rules. May assume inputs are finite.
likelyExperimental
Hints to the compiler that branch condition is likely to be true. Returns the value passed to it.
log2f32Experimental
Returns the base 2 logarithm of an f32.
log2f64Experimental
Returns the base 2 logarithm of an f64.
log10f32Experimental
Returns the base 10 logarithm of an f32.
log10f64Experimental
Returns the base 10 logarithm of an f64.
logf32Experimental
Returns the natural logarithm of an f32.
logf64Experimental
Returns the natural logarithm of an f64.
maxnumf32Experimental
Returns the maximum of two f32 values.
maxnumf64Experimental
Returns the maximum of two f64 values.
min_align_ofExperimental
The minimum alignment of a type.
min_align_of_valExperimental
The required alignment of the referenced value.
minnumf32Experimental
Returns the minimum of two f32 values.
minnumf64Experimental
Returns the minimum of two f64 values.
mul_with_overflowExperimental
Performs checked integer multiplication
nearbyintf32Experimental
Returns the nearest integer to an f32.
nearbyintf64Experimental
Returns the nearest integer to an f64.
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.
nontemporal_storeExperimental
Emits a !nontemporal store according to LLVM (see their docs). Probably will never become stable.
offsetExperimental
Calculates the offset from a pointer.
powf32Experimental
Raises an f32 to an f32 power.
powf64Experimental
Raises an f64 to an f64 power.
powif32Experimental
Raises an f32 to an integer power.
powif64Experimental
Raises an f64 to an integer power.
pref_align_ofExperimental
The preferred alignment of a type.
prefetch_read_dataExperimental
The prefetch intrinsic is a hint to the code generator to insert a prefetch instruction if supported; otherwise, it is a no-op. Prefetches have no effect on the behavior of the program but can change its performance characteristics.
The prefetch intrinsic is a hint to the code generator to insert a prefetch instruction if supported; otherwise, it is a no-op. Prefetches have no effect on the behavior of the program but can change its performance characteristics.
prefetch_write_dataExperimental
The prefetch intrinsic is a hint to the code generator to insert a prefetch instruction if supported; otherwise, it is a no-op. Prefetches have no effect on the behavior of the program but can change its performance characteristics.
The prefetch intrinsic is a hint to the code generator to insert a prefetch instruction if supported; otherwise, it is a no-op. Prefetches have no effect on the behavior of the program but can change its performance characteristics.
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_maskExperimental
Masks out bits of the pointer according to a mask.
ptr_offset_fromExperimental
See documentation of <*const T>::offset_from for details.
See documentation of <*const T>::sub_ptr for details.
raw_eqExperimental
Determines whether the raw bytes of the two values are equal.
rintf32Experimental
Returns the nearest integer to an f32. May raise an inexact floating-point exception if the argument is not an integer.
rintf64Experimental
Returns the nearest integer to an f64. May raise an inexact floating-point exception if the argument is not an integer.
rotate_leftExperimental
Performs rotate left.
rotate_rightExperimental
Performs rotate right.
roundf32Experimental
Returns the nearest integer to an f32. Rounds half-way cases away from zero.
roundf64Experimental
Returns the nearest integer to an f64. Rounds half-way cases away from zero.
rustc_peekExperimental
Magic intrinsic that derives its meaning from attributes attached to the function.
saturating_addExperimental
Computes a + b, saturating at numeric bounds.
saturating_subExperimental
Computes a - b, saturating at numeric bounds.
sinf32Experimental
Returns the sine of an f32.
sinf64Experimental
Returns the sine of an f64.
size_ofExperimental
The size of a type in bytes.
size_of_valExperimental
The size of the referenced value in bytes.
sqrtf32Experimental
Returns the square root of an f32
sqrtf64Experimental
Returns the square root of an f64
sub_with_overflowExperimental
Performs checked integer subtraction
truncf32Experimental
Returns the integer part of an f32.
truncf64Experimental
Returns the integer part of an f64.
tryExperimental
Rust’s “try catch” construct which invokes the function pointer try_fn with the data pointer data.
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_nameExperimental
Gets a static string slice containing the name of a type.
Performs a volatile load from the src pointer The pointer is not required to be aligned.
Performs a volatile store to the dst pointer. The pointer is not required to be aligned.
unchecked_addExperimental
Returns the result of an unchecked addition, resulting in undefined behavior when x + y > T::MAX or x + y < T::MIN.
unchecked_divExperimental
Performs an unchecked division, resulting in undefined behavior where y == 0 or x == T::MIN && y == -1
unchecked_mulExperimental
Returns the result of an unchecked multiplication, resulting in undefined behavior when x * y > T::MAX or x * y < T::MIN.
unchecked_remExperimental
Returns the remainder of an unchecked division, resulting in undefined behavior when y == 0 or x == T::MIN && y == -1
unchecked_shlExperimental
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_shrExperimental
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_subExperimental
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.
unreachableExperimental
Informs the optimizer that this point in the code is not reachable, enabling further optimizations.
variant_countExperimental
Returns the number of variants of the type T cast to a usize; if T has no variants, returns 0. Uninhabited variants will be counted.
volatile_copy_memoryExperimental
Equivalent to the appropriate llvm.memmove.p0i8.0i8.* intrinsic, with a size of count * size_of::<T>() and an alignment of min_align_of::<T>()
Equivalent to the appropriate llvm.memcpy.p0i8.0i8.* intrinsic, with a size of count * size_of::<T>() and an alignment of min_align_of::<T>()
volatile_loadExperimental
Performs a volatile load from the src pointer.
volatile_set_memoryExperimental
Equivalent to the appropriate llvm.memset.p0i8.* intrinsic, with a size of count * size_of::<T>() and an alignment of min_align_of::<T>().
volatile_storeExperimental
Performs a volatile store to the dst pointer.
vtable_alignExperimental
ptr must point to a vtable. The intrinsic will return the alignment stored in that vtable.
vtable_sizeExperimental
ptr must point to a vtable. The intrinsic will return the size stored in that vtable.
wrapping_addExperimental
Returns (a + b) mod 2N, where N is the width of T in bits.
wrapping_mulExperimental
Returns (a * b) mod 2N, where N is the width of T in bits.
wrapping_subExperimental
Returns (a - b) mod 2N, where N is the width of T in bits.
copy
Copies count * size_of::<T>() bytes from src to dst. The source and destination may overlap.
Copies count * size_of::<T>() bytes from src to dst. The source and destination must not overlap.
drop_in_placeDeprecated
Reinterprets the bits of a value of one type as another type.
Sets count * size_of::<T>() bytes of memory starting at dst to val.