[−][src]Module core::intrinsics
🔬 This is a nightlyonly 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 compiletime, one needs to copy the implementation
from https://github.com/rustlang/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 Tlang 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
.
Reexports
pub use crate::ptr::drop_in_place; 
Functions
copy^{⚠}  Copies 
copy_nonoverlapping^{⚠}  Copies 
transmute^{⚠}  Reinterprets the bits of a value of one type as another type. 
write_bytes^{⚠}  Sets 
abort^{⚠}  Experimental Aborts the execution of the process. 
add_with_overflow^{⚠}  Experimental Performs checked integer addition.
The stabilized versions of this intrinsic are available on the integer
primitives via the 
arith_offset^{⚠}  Experimental Calculates the offset from a pointer, potentially wrapping. 
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.
The stabilized version of this intrinsic is available on the

atomic_and_acq^{⚠}  Experimental Bitwise and with the current value, returning the previous value.
The stabilized version of this intrinsic is available on the

atomic_and_acqrel^{⚠}  Experimental Bitwise and with the current value, returning the previous value.
The stabilized version of this intrinsic is available on the

atomic_and_rel^{⚠}  Experimental Bitwise and with the current value, returning the previous value.
The stabilized version of this intrinsic is available on the

atomic_and_relaxed^{⚠}  Experimental Bitwise and with the current value, returning the previous value.
The stabilized version of this intrinsic is available on the

atomic_cxchg^{⚠}  Experimental Stores a value if the current value is the same as the 
atomic_cxchg_acq^{⚠}  Experimental Stores a value if the current value is the same as the 
atomic_cxchg_acq_failrelaxed^{⚠}  Experimental Stores a value if the current value is the same as the 
atomic_cxchg_acqrel^{⚠}  Experimental Stores a value if the current value is the same as the 
atomic_cxchg_acqrel_failrelaxed^{⚠}  Experimental Stores a value if the current value is the same as the 
atomic_cxchg_failacq^{⚠}  Experimental Stores a value if the current value is the same as the 
atomic_cxchg_failrelaxed^{⚠}  Experimental Stores a value if the current value is the same as the 
atomic_cxchg_rel^{⚠}  Experimental Stores a value if the current value is the same as the 
atomic_cxchg_relaxed^{⚠}  Experimental Stores a value if the current value is the same as the 
atomic_cxchgweak^{⚠}  Experimental Stores a value if the current value is the same as the 
atomic_cxchgweak_acq^{⚠}  Experimental Stores a value if the current value is the same as the 
atomic_cxchgweak_acq_failrelaxed^{⚠}  Experimental Stores a value if the current value is the same as the 
atomic_cxchgweak_acqrel^{⚠}  Experimental Stores a value if the current value is the same as the 
atomic_cxchgweak_acqrel_failrelaxed^{⚠}  Experimental Stores a value if the current value is the same as the 
atomic_cxchgweak_failacq^{⚠}  Experimental Stores a value if the current value is the same as the 
atomic_cxchgweak_failrelaxed^{⚠}  Experimental Stores a value if the current value is the same as the 
atomic_cxchgweak_rel^{⚠}  Experimental Stores a value if the current value is the same as the 
atomic_cxchgweak_relaxed^{⚠}  Experimental Stores a value if the current value is the same as the 
atomic_fence^{⚠}  Experimental 
atomic_fence_acq^{⚠}  Experimental 
atomic_fence_acqrel^{⚠}  Experimental 
atomic_fence_rel^{⚠}  Experimental 
atomic_load^{⚠}  Experimental Loads the current value of the pointer.
The stabilized version of this intrinsic is available on the

atomic_load_acq^{⚠}  Experimental Loads the current value of the pointer.
The stabilized version of this intrinsic is available on the

atomic_load_relaxed^{⚠}  Experimental Loads the current value of the pointer.
The stabilized version of this intrinsic is available on the

atomic_load_unordered^{⚠}  Experimental 
atomic_max^{⚠}  Experimental 
atomic_max_acq^{⚠}  Experimental 
atomic_max_acqrel^{⚠}  Experimental 
atomic_max_rel^{⚠}  Experimental 
atomic_max_relaxed^{⚠}  Experimental 
atomic_min^{⚠}  Experimental 
atomic_min_acq^{⚠}  Experimental 
atomic_min_acqrel^{⚠}  Experimental 
atomic_min_rel^{⚠}  Experimental 
atomic_min_relaxed^{⚠}  Experimental 
atomic_nand^{⚠}  Experimental Bitwise nand with the current value, returning the previous value.
The stabilized version of this intrinsic is available on the

atomic_nand_acq^{⚠}  Experimental Bitwise nand with the current value, returning the previous value.
The stabilized version of this intrinsic is available on the

atomic_nand_acqrel^{⚠}  Experimental Bitwise nand with the current value, returning the previous value.
The stabilized version of this intrinsic is available on the

atomic_nand_rel^{⚠}  Experimental Bitwise nand with the current value, returning the previous value.
The stabilized version of this intrinsic is available on the

atomic_nand_relaxed^{⚠}  Experimental Bitwise nand with the current value, returning the previous value.
The stabilized version of this intrinsic is available on the

atomic_or^{⚠}  Experimental Bitwise or with the current value, returning the previous value.
The stabilized version of this intrinsic is available on the

atomic_or_acq^{⚠}  Experimental Bitwise or with the current value, returning the previous value.
The stabilized version of this intrinsic is available on the

atomic_or_acqrel^{⚠}  Experimental Bitwise or with the current value, returning the previous value.
The stabilized version of this intrinsic is available on the

atomic_or_rel^{⚠}  Experimental Bitwise or with the current value, returning the previous value.
The stabilized version of this intrinsic is available on the

atomic_or_relaxed^{⚠}  Experimental Bitwise or with the current value, returning the previous value.
The stabilized version of this intrinsic is available on the

atomic_singlethreadfence^{⚠}  Experimental A compileronly memory barrier. 
atomic_singlethreadfence_acq^{⚠}  Experimental 
atomic_singlethreadfence_acqrel^{⚠}  Experimental 
atomic_singlethreadfence_rel^{⚠}  Experimental 
atomic_store^{⚠}  Experimental Stores the value at the specified memory location.
The stabilized version of this intrinsic is available on the

atomic_store_rel^{⚠}  Experimental Stores the value at the specified memory location.
The stabilized version of this intrinsic is available on the

atomic_store_relaxed^{⚠}  Experimental Stores the value at the specified memory location.
The stabilized version of this intrinsic is available on the

atomic_store_unordered^{⚠}  Experimental 
atomic_umax^{⚠}  Experimental 
atomic_umax_acq^{⚠}  Experimental 
atomic_umax_acqrel^{⚠}  Experimental 
atomic_umax_rel^{⚠}  Experimental 
atomic_umax_relaxed^{⚠}  Experimental 
atomic_umin^{⚠}  Experimental 
atomic_umin_acq^{⚠}  Experimental 
atomic_umin_acqrel^{⚠}  Experimental 
atomic_umin_rel^{⚠}  Experimental 
atomic_umin_relaxed^{⚠}  Experimental 
atomic_xadd^{⚠}  Experimental Adds to the current value, returning the previous value.
The stabilized version of this intrinsic is available on the

atomic_xadd_acq^{⚠}  Experimental Adds to the current value, returning the previous value.
The stabilized version of this intrinsic is available on the

atomic_xadd_acqrel^{⚠}  Experimental Adds to the current value, returning the previous value.
The stabilized version of this intrinsic is available on the

atomic_xadd_rel^{⚠}  Experimental Adds to the current value, returning the previous value.
The stabilized version of this intrinsic is available on the

atomic_xadd_relaxed^{⚠}  Experimental Adds to the current value, returning the previous value.
The stabilized version of this intrinsic is available on the

atomic_xchg^{⚠}  Experimental Stores the value at the specified memory location, returning the old value.
The stabilized version of this intrinsic is available on the

atomic_xchg_acq^{⚠}  Experimental Stores the value at the specified memory location, returning the old value.
The stabilized version of this intrinsic is available on the

atomic_xchg_acqrel^{⚠}  Experimental Stores the value at the specified memory location, returning the old value.
The stabilized version of this intrinsic is available on the

atomic_xchg_rel^{⚠}  Experimental Stores the value at the specified memory location, returning the old value.
The stabilized version of this intrinsic is available on the

atomic_xchg_relaxed^{⚠}  Experimental Stores the value at the specified memory location, returning the old value.
The stabilized version of this intrinsic is available on the

atomic_xor^{⚠}  Experimental Bitwise xor with the current value, returning the previous value.
The stabilized version of this intrinsic is available on the

atomic_xor_acq^{⚠}  Experimental Bitwise xor with the current value, returning the previous value.
The stabilized version of this intrinsic is available on the

atomic_xor_acqrel^{⚠}  Experimental Bitwise xor with the current value, returning the previous value.
The stabilized version of this intrinsic is available on the

atomic_xor_rel^{⚠}  Experimental Bitwise xor with the current value, returning the previous value.
The stabilized version of this intrinsic is available on the

atomic_xor_relaxed^{⚠}  Experimental Bitwise xor with the current value, returning the previous value.
The stabilized version of this intrinsic is available on the

atomic_xsub^{⚠}  Experimental Subtract from the current value, returning the previous value.
The stabilized version of this intrinsic is available on the

atomic_xsub_acq^{⚠}  Experimental Subtract from the current value, returning the previous value.
The stabilized version of this intrinsic is available on the

atomic_xsub_acqrel^{⚠}  Experimental Subtract from the current value, returning the previous value.
The stabilized version of this intrinsic is available on the

atomic_xsub_rel^{⚠}  Experimental Subtract from the current value, returning the previous value.
The stabilized version of this intrinsic is available on the

atomic_xsub_relaxed^{⚠}  Experimental Subtract from the current value, returning the previous value.
The stabilized version of this intrinsic is available on the

bitreverse^{⚠}  Experimental Reverses the bits in an integer type 
breakpoint^{⚠}  Experimental Executes a breakpoint trap, for inspection by a debugger. 
bswap^{⚠}  Experimental Reverses the bytes in an integer type 
caller_location^{⚠}  Experimental Gets a reference to a static 
ceilf32^{⚠}  Experimental Returns the smallest integer greater than or equal to an 
ceilf64^{⚠}  Experimental Returns the smallest integer greater than or equal to an 
copysignf32^{⚠}  Experimental Copies the sign from 
copysignf64^{⚠}  Experimental Copies the sign from 
cosf32^{⚠}  Experimental Returns the cosine of an 
cosf64^{⚠}  Experimental Returns the cosine of an 
ctlz^{⚠}  Experimental Returns the number of leading unset bits (zeroes) in an integer type 
ctlz_nonzero^{⚠}  Experimental Like 
ctpop^{⚠}  Experimental Returns the number of bits set in an integer type 
cttz^{⚠}  Experimental Returns the number of trailing unset bits (zeroes) in an integer type 
cttz_nonzero^{⚠}  Experimental Like 
discriminant_value^{⚠}  Experimental Returns the value of the discriminant for the variant in 'v',
cast to a 
exact_div^{⚠}  Experimental Performs an exact division, resulting in undefined behavior where

exp2f32^{⚠}  Experimental Returns 2 raised to the power of an 
exp2f64^{⚠}  Experimental Returns 2 raised to the power of an 
expf32^{⚠}  Experimental Returns the exponential of an 
expf64^{⚠}  Experimental Returns the exponential of an 
fabsf32^{⚠}  Experimental Returns the absolute value of an 
fabsf64^{⚠}  Experimental Returns the absolute value of an 
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_approx_unchecked^{⚠}  Experimental Convert with LLVM’s fptoui/fptosi, which may return undef for values out of range https://github.com/rustlang/rust/issues/10184 
floorf32^{⚠}  Experimental Returns the largest integer less than or equal to an 
floorf64^{⚠}  Experimental Returns the largest integer less than or equal to an 
fmaf32^{⚠}  Experimental Returns 
fmaf64^{⚠}  Experimental Returns 
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. 
init^{⚠}  DeprecatedExperimental Creates a value initialized to zero. 
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 
log10f64^{⚠}  Experimental Returns the base 10 logarithm of an 
log2f32^{⚠}  Experimental Returns the base 2 logarithm of an 
log2f64^{⚠}  Experimental Returns the base 2 logarithm of an 
logf32^{⚠}  Experimental Returns the natural logarithm of an 
logf64^{⚠}  Experimental Returns the natural logarithm of an 
maxnumf32^{⚠}  Experimental Returns the maximum of two 
maxnumf64^{⚠}  Experimental Returns the maximum of two 
min_align_of^{⚠}  Experimental 
min_align_of_val^{⚠}  Experimental 
minnumf32^{⚠}  Experimental Returns the minimum of two 
minnumf64^{⚠}  Experimental Returns the minimum of two 
miri_start_panic^{⚠}  Experimental Internal hook used by Miri to implement unwinding. Compiles to a NOP during nonMiri codegen. 
move_val_init^{⚠}  Experimental Moves a value to an uninitialized memory location. 
mul_with_overflow^{⚠}  Experimental Performs checked integer multiplication
The stabilized versions of this intrinsic are available on the integer
primitives via the 
nearbyintf32^{⚠}  Experimental Returns the nearest integer to an 
nearbyintf64^{⚠}  Experimental Returns the nearest integer to an 
needs_drop^{⚠}  Experimental Returns 
nontemporal_store^{⚠}  Experimental Emits a 
offset^{⚠}  Experimental Calculates the offset from a pointer. 
panic_if_uninhabited^{⚠}  Experimental A guard for unsafe functions that cannot ever be executed if 
powf32^{⚠}  Experimental Raises an 
powf64^{⚠}  Experimental Raises an 
powif32^{⚠}  Experimental Raises an 
powif64^{⚠}  Experimental Raises an 
pref_align_of^{⚠}  Experimental 
prefetch_read_data^{⚠}  Experimental The 
prefetch_read_instruction^{⚠}  Experimental The 
prefetch_write_data^{⚠}  Experimental The 
prefetch_write_instruction^{⚠}  Experimental The 
ptr_offset_from^{⚠}  Experimental See documentation of 
rintf32^{⚠}  Experimental Returns the nearest integer to an 
rintf64^{⚠}  Experimental Returns the nearest integer to an 
rotate_left^{⚠}  Experimental Performs rotate left.
The stabilized versions of this intrinsic are available on the integer
primitives via the 
rotate_right^{⚠}  Experimental Performs rotate right.
The stabilized versions of this intrinsic are available on the integer
primitives via the 
roundf32^{⚠}  Experimental Returns the nearest integer to an 
roundf64^{⚠}  Experimental Returns the nearest integer to an 
rustc_peek^{⚠}  Experimental Magic intrinsic that derives its meaning from attributes attached to the function. 
saturating_add^{⚠}  Experimental Computes 
saturating_sub^{⚠}  Experimental Computes 
sinf32^{⚠}  Experimental Returns the sine of an 
sinf64^{⚠}  Experimental Returns the sine of an 
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 
sqrtf64^{⚠}  Experimental Returns the square root of an 
sub_with_overflow^{⚠}  Experimental Performs checked integer subtraction
The stabilized versions of this intrinsic are available on the integer
primitives via the 
truncf32^{⚠}  Experimental Returns the integer part of an 
truncf64^{⚠}  Experimental Returns the integer part of an 
try^{⚠}  Experimental Rust's "try catch" construct which invokes the function pointer 
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 
unaligned_volatile_store^{⚠}  Experimental Performs a volatile store to the 
unchecked_add^{⚠}  Experimental Returns the result of an unchecked addition, resulting in
undefined behavior when 
unchecked_div^{⚠}  Experimental Performs an unchecked division, resulting in undefined behavior
where y = 0 or x = 
unchecked_mul^{⚠}  Experimental Returns the result of an unchecked multiplication, resulting in
undefined behavior when 
unchecked_rem^{⚠}  Experimental Returns the remainder of an unchecked division, resulting in
undefined behavior where y = 0 or x = 
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 
uninit^{⚠}  DeprecatedExperimental Creates an uninitialized value. 
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 
volatile_copy_nonoverlapping_memory^{⚠}  Experimental Equivalent to the appropriate 
volatile_load^{⚠}  Experimental Performs a volatile load from the 
volatile_set_memory^{⚠}  Experimental Equivalent to the appropriate 
volatile_store^{⚠}  Experimental Performs a volatile store to the 
wrapping_add^{⚠}  Experimental Returns (a + b) mod 2^{N}, where N is the width of T in bits.
The stabilized versions of this intrinsic are available on the integer
primitives via the 
wrapping_mul^{⚠}  Experimental Returns (a * b) mod 2^{N}, where N is the width of T in bits.
The stabilized versions of this intrinsic are available on the integer
primitives via the 
wrapping_sub^{⚠}  Experimental Returns (a  b) mod 2^{N}, where N is the width of T in bits.
The stabilized versions of this intrinsic are available on the integer
primitives via the 