W3cubDocs

/Rust

Module std::intrinsics

🔬 This is a nightly-only experimental API. (core_intrinsics)intrinsics are unlikely to ever be stabilized, instead they should be used through stabilized interfaces in the rest of the standard library

Compiler intrinsics.

The corresponding definitions are in librustc_codegen_llvm/intrinsic.rs. The corresponding const implementations are in librustc_mir/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 librustc_mir/interpret/intrinsics.rs and add a #[rustc_const_unstable(feature = "foo", issue = "01234")] to the intrinsic.

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

copy ^⚠	Copies `count * size_of::<T>()` bytes from `src` to `dst`. The source and destination may overlap.
copy_nonoverlapping ^⚠	Copies `count * size_of::<T>()` bytes from `src` to `dst`. The source and destination must not overlap.
drop_in_place ^⚠	Executes the destructor (if any) of the pointed-to value.
transmute ^⚠	Reinterprets the bits of a value of one type as another type.
write_bytes ^⚠	Sets `count * size_of::<T>()` bytes of memory starting at `dst` to `val`.
abort	Experimental Aborts the execution of the process.
add_with_overflow	Experimental Performs checked integer addition.
arith_offset ^⚠	Experimental Calculates the offset from a pointer, potentially wrapping.
assert_inhabited ^⚠	Experimental A guard for unsafe functions that cannot ever be executed if `T` is uninhabited: This will statically either panic, or do nothing.
assert_uninit_valid ^⚠	Experimental 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_valid ^⚠	Experimental 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.
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.
atomic_and_acq ^⚠	Experimental Bitwise and with the current value, returning the previous value.
atomic_and_acqrel ^⚠	Experimental Bitwise and with the current value, returning the previous value.
atomic_and_rel ^⚠	Experimental Bitwise and with the current value, returning the previous value.
atomic_and_relaxed ^⚠	Experimental Bitwise and with the current value, returning the previous value.
atomic_cxchg ^⚠	Experimental Stores a value if the current value is the same as the `old` value.
atomic_cxchg_acq ^⚠	Experimental Stores a value if the current value is the same as the `old` value.
atomic_cxchg_acq_failrelaxed ^⚠	Experimental Stores a value if the current value is the same as the `old` value.
atomic_cxchg_acqrel ^⚠	Experimental Stores a value if the current value is the same as the `old` value.
atomic_cxchg_acqrel_failrelaxed ^⚠	Experimental Stores a value if the current value is the same as the `old` value.
atomic_cxchg_failacq ^⚠	Experimental Stores a value if the current value is the same as the `old` value.
atomic_cxchg_failrelaxed ^⚠	Experimental Stores a value if the current value is the same as the `old` value.
atomic_cxchg_rel ^⚠	Experimental Stores a value if the current value is the same as the `old` value.
atomic_cxchg_relaxed ^⚠	Experimental Stores a value if the current value is the same as the `old` value.
atomic_cxchgweak ^⚠	Experimental Stores a value if the current value is the same as the `old` value.
atomic_cxchgweak_acq ^⚠	Experimental Stores a value if the current value is the same as the `old` value.
atomic_cxchgweak_acq_failrelaxed ^⚠	Experimental Stores a value if the current value is the same as the `old` value.
atomic_cxchgweak_acqrel ^⚠	Experimental Stores a value if the current value is the same as the `old` value.
atomic_cxchgweak_acqrel_failrelaxed ^⚠	Experimental Stores a value if the current value is the same as the `old` value.
atomic_cxchgweak_failacq ^⚠	Experimental Stores a value if the current value is the same as the `old` value.
atomic_cxchgweak_failrelaxed ^⚠	Experimental Stores a value if the current value is the same as the `old` value.
atomic_cxchgweak_rel ^⚠	Experimental Stores a value if the current value is the same as the `old` value.
atomic_cxchgweak_relaxed ^⚠	Experimental Stores a value if the current value is the same as the `old` value.
atomic_fence ^⚠	Experimental An atomic fence.
atomic_fence_acq ^⚠	Experimental An atomic fence.
atomic_fence_acqrel ^⚠	Experimental An atomic fence.
atomic_fence_rel ^⚠	Experimental An atomic fence.
atomic_load ^⚠	Experimental Loads the current value of the pointer.
atomic_load_acq ^⚠	Experimental Loads the current value of the pointer.
atomic_load_relaxed ^⚠	Experimental Loads the current value of the pointer.
atomic_load_unordered ^⚠	Experimental
atomic_max ^⚠	Experimental Maximum with the current value using a signed comparison.
atomic_max_acq ^⚠	Experimental Maximum with the current value using a signed comparison.
atomic_max_acqrel ^⚠	Experimental Maximum with the current value using a signed comparison.
atomic_max_rel ^⚠	Experimental Maximum with the current value using a signed comparison.
atomic_max_relaxed ^⚠	Experimental Maximum with the current value.
atomic_min ^⚠	Experimental Minimum with the current value using a signed comparison.
atomic_min_acq ^⚠	Experimental Minimum with the current value using a signed comparison.
atomic_min_acqrel ^⚠	Experimental Minimum with the current value using a signed comparison.
atomic_min_rel ^⚠	Experimental Minimum with the current value using a signed comparison.
atomic_min_relaxed ^⚠	Experimental Minimum with the current value using a signed comparison.
atomic_nand ^⚠	Experimental Bitwise nand with the current value, returning the previous value.
atomic_nand_acq ^⚠	Experimental Bitwise nand with the current value, returning the previous value.
atomic_nand_acqrel ^⚠	Experimental Bitwise nand with the current value, returning the previous value.
atomic_nand_rel ^⚠	Experimental Bitwise nand with the current value, returning the previous value.
atomic_nand_relaxed ^⚠	Experimental Bitwise nand with the current value, returning the previous value.
atomic_or ^⚠	Experimental Bitwise or with the current value, returning the previous value.
atomic_or_acq ^⚠	Experimental Bitwise or with the current value, returning the previous value.
atomic_or_acqrel ^⚠	Experimental Bitwise or with the current value, returning the previous value.
atomic_or_rel ^⚠	Experimental Bitwise or with the current value, returning the previous value.
atomic_or_relaxed ^⚠	Experimental Bitwise or with the current value, returning the previous value.
atomic_singlethreadfence ^⚠	Experimental A compiler-only memory barrier.
atomic_singlethreadfence_acq ^⚠	Experimental A compiler-only memory barrier.
atomic_singlethreadfence_acqrel ^⚠	Experimental A compiler-only memory barrier.
atomic_singlethreadfence_rel ^⚠	Experimental A compiler-only memory barrier.
atomic_store ^⚠	Experimental Stores the value at the specified memory location.
atomic_store_rel ^⚠	Experimental Stores the value at the specified memory location.
atomic_store_relaxed ^⚠	Experimental Stores the value at the specified memory location.
atomic_store_unordered ^⚠	Experimental
atomic_umax ^⚠	Experimental Maximum with the current value using an unsigned comparison.
atomic_umax_acq ^⚠	Experimental Maximum with the current value using an unsigned comparison.
atomic_umax_acqrel ^⚠	Experimental Maximum with the current value using an unsigned comparison.
atomic_umax_rel ^⚠	Experimental Maximum with the current value using an unsigned comparison.
atomic_umax_relaxed ^⚠	Experimental Maximum with the current value using an unsigned comparison.
atomic_umin ^⚠	Experimental Minimum with the current value using an unsigned comparison.
atomic_umin_acq ^⚠	Experimental Minimum with the current value using an unsigned comparison.
atomic_umin_acqrel ^⚠	Experimental Minimum with the current value using an unsigned comparison.
atomic_umin_rel ^⚠	Experimental Minimum with the current value using an unsigned comparison.
atomic_umin_relaxed ^⚠	Experimental Minimum with the current value using an unsigned comparison.
atomic_xadd ^⚠	Experimental Adds to the current value, returning the previous value.
atomic_xadd_acq ^⚠	Experimental Adds to the current value, returning the previous value.
atomic_xadd_acqrel ^⚠	Experimental Adds to the current value, returning the previous value.
atomic_xadd_rel ^⚠	Experimental Adds to the current value, returning the previous value.
atomic_xadd_relaxed ^⚠	Experimental Adds to the current value, returning the previous value.
atomic_xchg ^⚠	Experimental Stores the value at the specified memory location, returning the old value.
atomic_xchg_acq ^⚠	Experimental Stores the value at the specified memory location, returning the old value.
atomic_xchg_acqrel ^⚠	Experimental Stores the value at the specified memory location, returning the old value.
atomic_xchg_rel ^⚠	Experimental Stores the value at the specified memory location, returning the old value.
atomic_xchg_relaxed ^⚠	Experimental Stores the value at the specified memory location, returning the old value.
atomic_xor ^⚠	Experimental Bitwise xor with the current value, returning the previous value.
atomic_xor_acq ^⚠	Experimental Bitwise xor with the current value, returning the previous value.
atomic_xor_acqrel ^⚠	Experimental Bitwise xor with the current value, returning the previous value.
atomic_xor_rel ^⚠	Experimental Bitwise xor with the current value, returning the previous value.
atomic_xor_relaxed ^⚠	Experimental Bitwise xor with the current value, returning the previous value.
atomic_xsub ^⚠	Experimental Subtract from the current value, returning the previous value.
atomic_xsub_acq ^⚠	Experimental Subtract from the current value, returning the previous value.
atomic_xsub_acqrel ^⚠	Experimental Subtract from the current value, returning the previous value.
atomic_xsub_rel ^⚠	Experimental Subtract from the current value, returning the previous value.
atomic_xsub_relaxed ^⚠	Experimental Subtract from the current value, returning the previous value.
bitreverse	Experimental Reverses the bits in an integer type `T`.
breakpoint ^⚠	Experimental Executes a breakpoint trap, for inspection by a debugger.
bswap	Experimental Reverses the bytes in an integer type `T`.
caller_location	Experimental Gets a reference to a static `Location` indicating where it was called.
ceilf32 ^⚠	Experimental Returns the smallest integer greater than or equal to an `f32`.
ceilf64 ^⚠	Experimental Returns the smallest integer greater than or equal to an `f64`.
copysignf32 ^⚠	Experimental Copies the sign from `y` to `x` for `f32` values.
copysignf64 ^⚠	Experimental Copies the sign from `y` to `x` for `f64` values.
cosf32 ^⚠	Experimental Returns the cosine of an `f32`.
cosf64 ^⚠	Experimental Returns the cosine of an `f64`.
ctlz	Experimental Returns the number of leading unset bits (zeroes) in an integer type `T`.
ctlz_nonzero ^⚠	Experimental Like `ctlz`, but extra-unsafe as it returns `undef` when given an `x` with value `0`.
ctpop	Experimental Returns the number of bits set in an integer type `T`
cttz	Experimental Returns the number of trailing unset bits (zeroes) 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_value	Experimental Returns the value of the discriminant for the variant in 'v', cast to a `u64`; 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`
exp2f32 ^⚠	Experimental Returns 2 raised to the power of an `f32`.
exp2f64 ^⚠	Experimental Returns 2 raised to the power of an `f64`.
expf32 ^⚠	Experimental Returns the exponential of an `f32`.
expf64 ^⚠	Experimental Returns the exponential of an `f64`.
fabsf32 ^⚠	Experimental Returns the absolute value of an `f32`.
fabsf64 ^⚠	Experimental Returns the absolute value of an `f64`.
fadd_fast ^⚠	Experimental Float addition that allows optimizations based on algebraic rules. May assume inputs are finite.
fdiv_fast ^⚠	Experimental Float division that allows optimizations based on algebraic rules. May assume inputs are finite.
float_to_int_unchecked ^⚠	Experimental Convert with LLVM’s fptoui/fptosi, which may return undef for values out of range (https://github.com/rust-lang/rust/issues/10184)
floorf32 ^⚠	Experimental Returns the largest integer less than or equal to an `f32`.
floorf64 ^⚠	Experimental Returns the largest integer less than or equal to an `f64`.
fmaf32 ^⚠	Experimental Returns `a * b + c` for `f32` values.
fmaf64 ^⚠	Experimental Returns `a * b + c` for `f64` values.
fmul_fast ^⚠	Experimental Float multiplication that allows optimizations based on algebraic rules. May assume inputs are finite.
forget ^⚠	Experimental Moves a value out of scope without running drop glue.
frem_fast ^⚠	Experimental Float remainder that allows optimizations based on algebraic rules. May assume inputs are finite.
fsub_fast ^⚠	Experimental Float subtraction that allows optimizations based on algebraic rules. May assume inputs are finite.
likely	Experimental Hints to the compiler that branch condition is likely to be true. Returns the value passed to it.
log2f32 ^⚠	Experimental Returns the base 2 logarithm of an `f32`.
log2f64 ^⚠	Experimental Returns the base 2 logarithm of an `f64`.
log10f32 ^⚠	Experimental Returns the base 10 logarithm of an `f32`.
log10f64 ^⚠	Experimental Returns the base 10 logarithm of an `f64`.
logf32 ^⚠	Experimental Returns the natural logarithm of an `f32`.
logf64 ^⚠	Experimental Returns the natural logarithm of an `f64`.
maxnumf32	Experimental Returns the maximum of two `f32` values.
maxnumf64	Experimental Returns the maximum of two `f64` values.
min_align_of	Experimental The minimum alignment of a type.
min_align_of_val	Experimental The required alignment of the referenced value.
minnumf32	Experimental Returns the minimum of two `f32` values.
minnumf64	Experimental Returns the minimum of two `f64` values.
move_val_init ^⚠	Experimental Moves a value to an uninitialized memory location.
mul_with_overflow	Experimental Performs checked integer multiplication
nearbyintf32 ^⚠	Experimental Returns the nearest integer to an `f32`.
nearbyintf64 ^⚠	Experimental Returns the nearest integer to an `f64`.
needs_drop	Experimental Returns `true` if the actual type given as `T` requires drop glue; returns `false` if the actual type provided for `T` implements `Copy`.
nontemporal_store ^⚠	Experimental Emits a `!nontemporal` store according to LLVM (see their docs). Probably will never become stable.
offset ^⚠	Experimental Calculates the offset from a pointer.
powf32 ^⚠	Experimental Raises an `f32` to an `f32` power.
powf64 ^⚠	Experimental Raises an `f64` to an `f64` power.
powif32 ^⚠	Experimental Raises an `f32` to an integer power.
powif64 ^⚠	Experimental Raises an `f64` to an integer power.
pref_align_of ^⚠	Experimental The preferred alignment of a type.
prefetch_read_data ^⚠	Experimental 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_read_instruction ^⚠	Experimental 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_data ^⚠	Experimental 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_instruction ^⚠	Experimental 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_eq	Experimental See documentation of `<*const T>::guaranteed_eq` for details.
ptr_guaranteed_ne	Experimental See documentation of `<*const T>::guaranteed_ne` for details.
ptr_offset_from ^⚠	Experimental See documentation of `<*const T>::offset_from` for details.
rintf32 ^⚠	Experimental Returns the nearest integer to an `f32`. May raise an inexact floating-point exception if the argument is not an integer.
rintf64 ^⚠	Experimental Returns the nearest integer to an `f64`. May raise an inexact floating-point exception if the argument is not an integer.
rotate_left	Experimental Performs rotate left.
rotate_right	Experimental Performs rotate right.
roundf32 ^⚠	Experimental Returns the nearest integer to an `f32`. Rounds half-way cases away from zero.
roundf64 ^⚠	Experimental Returns the nearest integer to an `f64`. Rounds half-way cases away from zero.
rustc_peek	Experimental Magic intrinsic that derives its meaning from attributes attached to the function.
saturating_add	Experimental Computes `a + b`, while saturating at numeric bounds.
saturating_sub	Experimental Computes `a - b`, while saturating at numeric bounds.
sinf32 ^⚠	Experimental Returns the sine of an `f32`.
sinf64 ^⚠	Experimental Returns the sine of an `f64`.
size_of	Experimental The size of a type in bytes.
size_of_val	Experimental The size of the referenced value in bytes.
sqrtf32 ^⚠	Experimental Returns the square root of an `f32`
sqrtf64 ^⚠	Experimental Returns the square root of an `f64`
sub_with_overflow	Experimental Performs checked integer subtraction
truncf32 ^⚠	Experimental Returns the integer part of an `f32`.
truncf64 ^⚠	Experimental Returns the integer part of an `f64`.
try ^⚠	Experimental Rust's "try catch" construct which invokes the function pointer `try_fn` with the data pointer `data`.
type_id	Experimental 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_name	Experimental Gets a static string slice containing the name of a type.
unaligned_volatile_load ^⚠	Experimental Performs a volatile load from the `src` pointer The pointer is not required to be aligned.
unaligned_volatile_store ^⚠	Experimental Performs a volatile store to the `dst` pointer. The pointer is not required to be aligned.
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_div ^⚠	Experimental Performs an unchecked division, resulting in undefined behavior where y = 0 or x = `T::MIN` and y = -1
unchecked_mul ^⚠	Experimental Returns the result of an unchecked multiplication, 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 where y = 0 or x = `T::MIN` and 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`.
unlikely	Experimental Hints to the compiler that branch condition is likely to be false. Returns the value passed to it.
unreachable ^⚠	Experimental Tells LLVM that this point in the code is not reachable, enabling further optimizations.
variant_count	Experimental 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_memory ^⚠	Experimental 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>()`
volatile_copy_nonoverlapping_memory ^⚠	Experimental 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_load ^⚠	Experimental Performs a volatile load from the `src` pointer.
volatile_set_memory ^⚠	Experimental 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_store ^⚠	Experimental Performs a volatile store to the `dst` pointer.
wrapping_add	Experimental Returns (a + b) mod 2^N, where N is the width of T in bits.
wrapping_mul	Experimental Returns (a * b) mod 2^N, where N is the width of T in bits.
wrapping_sub	Experimental Returns (a - b) mod 2^N, where N is the width of T in bits.

© 2010 The Rust Project Developers
Licensed under the Apache License, Version 2.0 or the MIT license, at your option.
https://doc.rust-lang.org/std/intrinsics/index.html