Module std::intrinsics

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

Modules§

  • mirExperimental
    Rustc internal tooling for hand-writing MIR.
  • simdExperimental
    SIMD compiler intrinsics.

Functions§

  • 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.
  • 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 std::mem::uninitialized. 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
    Do NOT use this intrinsic; “unordered” operations do not exist in our memory model! In terms of the Rust Abstract Machine, this operation is equivalent to src.read(), i.e., it performs a non-atomic read.
  • 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
    Do NOT use this intrinsic; “unordered” operations do not exist in our memory model! In terms of the Rust Abstract Machine, this operation is equivalent to dst.write(val), i.e., it performs a non-atomic write.
  • 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.
  • compare_bytesExperimental
    Lexicographically compare [left, left + bytes) and [right, right + bytes) as unsigned bytes, returning negative if left is less, zero if all the bytes match, or positive if right is greater.
  • 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.
  • Returns whether the argument’s value is statically known at compile-time.
  • 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. Changing the rounding mode is not possible in Rust, so this rounds half-way cases to the number with an even least significant digit.
  • nearbyintf64Experimental
    Returns the nearest integer to an f64. Changing the rounding mode is not possible in Rust, so this rounds half-way cases to the number with an even least significant digit.
  • 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.
  • read_via_copyExperimental
    This is an implementation detail of crate::ptr::read and should not be used anywhere else. See its comments for why this exists.
  • rintf32Experimental
    Returns the nearest integer to an f32. Changing the rounding mode is not possible in Rust, so this rounds half-way cases to the number with an even least significant digit.
  • rintf64Experimental
    Returns the nearest integer to an f64. Changing the rounding mode is not possible in Rust, so this rounds half-way cases to the number with an even least significant digit.
  • rotate_leftExperimental
    Performs rotate left.
  • rotate_rightExperimental
    Performs rotate right.
  • roundevenf32Experimental
    Returns the nearest integer to an f32. Rounds half-way cases to the number with an even least significant digit.
  • roundevenf64Experimental
    Returns the nearest integer to an f64. Rounds half-way cases to the number with an even least significant digit.
  • 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
  • transmute_uncheckedExperimental
    Like transmute, but even less checked at compile-time: rather than giving an error for size_of::<Src>() != size_of::<Dst>(), it’s Undefined Behaviour at runtime.
  • 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.
  • write_via_moveExperimental
    This is an implementation detail of crate::ptr::write and should not be used anywhere else. See its comments for why this exists.