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

© 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