🔬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.

Bitwise and with the current value, returning the previous value.

Bitwise and with the current value, returning the previous value.

Bitwise and with the current value, returning the previous value.

Bitwise and with the current value, returning the previous value.

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.

An atomic fence.

An atomic fence.

An atomic fence.

An atomic fence.

Loads the current value of the pointer.

Loads the current value of the pointer.

Loads the current value of the pointer.

Maximum with the current value using a signed comparison.

Maximum with the current value using a signed comparison.

Maximum with the current value.

Maximum with the current value using a signed comparison.

Maximum with the current value using a signed comparison.

Minimum with the current value using a signed comparison.

Minimum with the current value using a signed comparison.

Minimum with the current value using a signed comparison.

Minimum with the current value using a signed comparison.

Minimum with the current value using a signed comparison.

Bitwise nand with the current value, returning the previous value.

Bitwise nand with the current value, returning the previous value.

Bitwise nand with the current value, returning the previous value.

Bitwise nand with the current value, returning the previous value.

Bitwise nand with the current value, returning the previous value.

Bitwise or with the current value, returning the previous value.

Bitwise or with the current value, returning the previous value.

Bitwise or with the current value, returning the previous value.

Bitwise or with the current value, returning the previous value.

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.

Stores the value at the specified memory location.

Stores the value at the specified memory location.

Stores the value at the specified memory location.

Maximum with the current value using an unsigned comparison.

Maximum with the current value using an unsigned comparison.

Maximum with the current value using an unsigned comparison.

Maximum with the current value using an unsigned comparison.

Maximum with the current value using an unsigned comparison.

Minimum with the current value using an unsigned comparison.

Minimum with the current value using an unsigned comparison.

Minimum with the current value using an unsigned comparison.

Minimum with the current value using an unsigned comparison.

Minimum with the current value using an unsigned comparison.

Adds to the current value, returning the previous value.

Adds to the current value, returning the previous value.

Adds to the current value, returning the previous value.

Adds to the current value, returning the previous value.

Adds to the current value, returning the previous value.

Stores the value at the specified memory location, returning the old value.

Stores the value at the specified memory location, returning the old value.

Stores the value at the specified memory location, returning the old value.

Stores the value at the specified memory location, returning the old value.

Stores the value at the specified memory location, returning the old value.

Bitwise xor with the current value, returning the previous value.

Bitwise xor with the current value, returning the previous value.

Bitwise xor with the current value, returning the previous value.

Bitwise xor with the current value, returning the previous value.

Bitwise xor with the current value, returning the previous value.

Subtract from the current value, returning the previous value.

Subtract from the current value, returning the previous value.

Subtract from the current value, returning the previous value.

Subtract from the current value, returning the previous value.

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.

Deallocates a memory which allocated by intrinsics::const_allocate at compile time. At runtime, does nothing.

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.

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.

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.

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.

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.

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_eqExperimental

See documentation of <*const T>::guaranteed_eq for details.

ptr_guaranteed_neExperimental

See documentation of <*const T>::guaranteed_ne for details.

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.

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.

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.

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.

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.