std::intrinsics - Rust
Description: API documentation for the Rust `intrinsics` mod in crate `std`.
Keywords: rust, rustlang, rust-lang, intrinsics

# [−][src]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 consulation, 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.
log10f32⚠ | Experimental Returns the base 10 logarithm of an `f32`.
log10f64⚠ | Experimental Returns the base 10 logarithm of an `f64`.
log2f32⚠ | Experimental Returns the base 2 logarithm of an `f32`.
log2f64⚠ | Experimental Returns the base 2 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.
miri_start_panic⚠ | Experimental Internal hook used by Miri to implement unwinding. ICEs when encountered during non-Miri codegen.
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 prefered 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_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.
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 2N, where N is the width of T in bits.
wrapping_mul | Experimental Returns (a * b) mod 2N, where N is the width of T in bits.
wrapping_sub | Experimental Returns (a - b) mod 2N, where N is the width of T in bits.