Module core::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.rs 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.
Functions
abortExperimental
Aborts the execution of the process.
add_with_overflowExperimental
Performs checked integer addition.
arith_offset⚠Experimental
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.assert_uninit_validExperimental
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_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.assume⚠Experimental
Informs the optimizer that a condition is always true.
If the condition is false, the behavior is undefined.
atomic_and_acqrel⚠Experimental
Bitwise and with the current value, returning the previous value.
atomic_and_acquire⚠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_and_release⚠Experimental
Bitwise and with the current value, returning the previous value.
atomic_and_seqcst⚠Experimental
Bitwise and with the current value, returning the previous value.
atomic_cxchg_acqrel_acquire⚠Experimental
Stores a value if the current value is the same as the
old value.atomic_cxchg_acqrel_relaxed⚠Experimental
Stores a value if the current value is the same as the
old value.atomic_cxchg_acqrel_seqcst⚠Experimental
Stores a value if the current value is the same as the
old value.atomic_cxchg_acquire_acquire⚠Experimental
Stores a value if the current value is the same as the
old value.atomic_cxchg_acquire_relaxed⚠Experimental
Stores a value if the current value is the same as the
old value.atomic_cxchg_acquire_seqcst⚠Experimental
Stores a value if the current value is the same as the
old value.atomic_cxchg_relaxed_acquire⚠Experimental
Stores a value if the current value is the same as the
old value.atomic_cxchg_relaxed_relaxed⚠Experimental
Stores a value if the current value is the same as the
old value.atomic_cxchg_relaxed_seqcst⚠Experimental
Stores a value if the current value is the same as the
old value.atomic_cxchg_release_acquire⚠Experimental
Stores a value if the current value is the same as the
old value.atomic_cxchg_release_relaxed⚠Experimental
Stores a value if the current value is the same as the
old value.atomic_cxchg_release_seqcst⚠Experimental
Stores a value if the current value is the same as the
old value.atomic_cxchg_seqcst_acquire⚠Experimental
Stores a value if the current value is the same as the
old value.atomic_cxchg_seqcst_relaxed⚠Experimental
Stores a value if the current value is the same as the
old value.atomic_cxchg_seqcst_seqcst⚠Experimental
Stores a value if the current value is the same as the
old value.atomic_cxchgweak_acqrel_acquire⚠Experimental
Stores a value if the current value is the same as the
old value.atomic_cxchgweak_acqrel_relaxed⚠Experimental
Stores a value if the current value is the same as the
old value.atomic_cxchgweak_acqrel_seqcst⚠Experimental
Stores a value if the current value is the same as the
old value.atomic_cxchgweak_acquire_acquire⚠Experimental
Stores a value if the current value is the same as the
old value.atomic_cxchgweak_acquire_relaxed⚠Experimental
Stores a value if the current value is the same as the
old value.atomic_cxchgweak_acquire_seqcst⚠Experimental
Stores a value if the current value is the same as the
old value.atomic_cxchgweak_relaxed_acquire⚠Experimental
Stores a value if the current value is the same as the
old value.atomic_cxchgweak_relaxed_relaxed⚠Experimental
Stores a value if the current value is the same as the
old value.atomic_cxchgweak_relaxed_seqcst⚠Experimental
Stores a value if the current value is the same as the
old value.atomic_cxchgweak_release_acquire⚠Experimental
Stores a value if the current value is the same as the
old value.atomic_cxchgweak_release_relaxed⚠Experimental
Stores a value if the current value is the same as the
old value.atomic_cxchgweak_release_seqcst⚠Experimental
Stores a value if the current value is the same as the
old value.atomic_cxchgweak_seqcst_acquire⚠Experimental
Stores a value if the current value is the same as the
old value.atomic_cxchgweak_seqcst_relaxed⚠Experimental
Stores a value if the current value is the same as the
old value.atomic_cxchgweak_seqcst_seqcst⚠Experimental
Stores a value if the current value is the same as the
old value.atomic_fence_acqrel⚠Experimental
An atomic fence.
atomic_fence_acquire⚠Experimental
An atomic fence.
atomic_fence_release⚠Experimental
An atomic fence.
atomic_fence_seqcst⚠Experimental
An atomic fence.
atomic_load_acquire⚠Experimental
Loads the current value of the pointer.
atomic_load_relaxed⚠Experimental
Loads the current value of the pointer.
atomic_load_seqcst⚠Experimental
Loads the current value of the pointer.
atomic_load_unordered⚠Experimental
atomic_max_acqrel⚠Experimental
Maximum with the current value using a signed comparison.
atomic_max_acquire⚠Experimental
Maximum with the current value using a signed comparison.
atomic_max_relaxed⚠Experimental
Maximum with the current value.
atomic_max_release⚠Experimental
Maximum with the current value using a signed comparison.
atomic_max_seqcst⚠Experimental
Maximum with the current value using a signed comparison.
atomic_min_acqrel⚠Experimental
Minimum with the current value using a signed comparison.
atomic_min_acquire⚠Experimental
Minimum with the current value using a signed comparison.
atomic_min_relaxed⚠Experimental
Minimum with the current value using a signed comparison.
atomic_min_release⚠Experimental
Minimum with the current value using a signed comparison.
atomic_min_seqcst⚠Experimental
Minimum with the current value using a signed comparison.
atomic_nand_acqrel⚠Experimental
Bitwise nand with the current value, returning the previous value.
atomic_nand_acquire⚠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_nand_release⚠Experimental
Bitwise nand with the current value, returning the previous value.
atomic_nand_seqcst⚠Experimental
Bitwise nand with the current value, returning the previous value.
atomic_or_acqrel⚠Experimental
Bitwise or with the current value, returning the previous value.
atomic_or_acquire⚠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_or_release⚠Experimental
Bitwise or with the current value, returning the previous value.
atomic_or_seqcst⚠Experimental
Bitwise or with the current value, returning the previous value.
atomic_singlethreadfence_acqrel⚠Experimental
A compiler-only memory barrier.
atomic_singlethreadfence_acquire⚠Experimental
A compiler-only memory barrier.
atomic_singlethreadfence_release⚠Experimental
A compiler-only memory barrier.
atomic_singlethreadfence_seqcst⚠Experimental
A compiler-only memory barrier.
atomic_store_relaxed⚠Experimental
Stores the value at the specified memory location.
atomic_store_release⚠Experimental
Stores the value at the specified memory location.
atomic_store_seqcst⚠Experimental
Stores the value at the specified memory location.
atomic_store_unordered⚠Experimental
atomic_umax_acqrel⚠Experimental
Maximum with the current value using an unsigned comparison.
atomic_umax_acquire⚠Experimental
Maximum with the current value using an unsigned comparison.
atomic_umax_relaxed⚠Experimental
Maximum with the current value using an unsigned comparison.
atomic_umax_release⚠Experimental
Maximum with the current value using an unsigned comparison.
atomic_umax_seqcst⚠Experimental
Maximum with the current value using an unsigned comparison.
atomic_umin_acqrel⚠Experimental
Minimum with the current value using an unsigned comparison.
atomic_umin_acquire⚠Experimental
Minimum with the current value using an unsigned comparison.
atomic_umin_relaxed⚠Experimental
Minimum with the current value using an unsigned comparison.
atomic_umin_release⚠Experimental
Minimum with the current value using an unsigned comparison.
atomic_umin_seqcst⚠Experimental
Minimum with the current value using an unsigned comparison.
atomic_xadd_acqrel⚠Experimental
Adds to the current value, returning the previous value.
atomic_xadd_acquire⚠Experimental
Adds to the current value, returning the previous value.
atomic_xadd_relaxed⚠Experimental
Adds to the current value, returning the previous value.
atomic_xadd_release⚠Experimental
Adds to the current value, returning the previous value.
atomic_xadd_seqcst⚠Experimental
Adds to the current value, returning the previous value.
atomic_xchg_acqrel⚠Experimental
Stores the value at the specified memory location, returning the old value.
atomic_xchg_acquire⚠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_xchg_release⚠Experimental
Stores the value at the specified memory location, returning the old value.
atomic_xchg_seqcst⚠Experimental
Stores the value at the specified memory location, returning the old value.
atomic_xor_acqrel⚠Experimental
Bitwise xor with the current value, returning the previous value.
atomic_xor_acquire⚠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_xor_release⚠Experimental
Bitwise xor with the current value, returning the previous value.
atomic_xor_seqcst⚠Experimental
Bitwise xor with the current value, returning the previous value.
atomic_xsub_acqrel⚠Experimental
Subtract from the current value, returning the previous value.
atomic_xsub_acquire⚠Experimental
Subtract from the current value, returning the previous value.
atomic_xsub_relaxed⚠Experimental
Subtract from the current value, returning the previous value.
atomic_xsub_release⚠Experimental
Subtract from the current value, returning the previous value.
atomic_xsub_seqcst⚠Experimental
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.breakpoint⚠Experimental
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.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.const_allocate⚠Experimental
Allocates a block of memory at compile time.
At runtime, just returns a null pointer.
const_deallocate⚠Experimental
Deallocates a memory which allocated by
intrinsics::const_allocate at compile time.
At runtime, does nothing.const_eval_select⚠Experimental
Selects which function to call depending on the context.
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.ctlzExperimental
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.ctpopExperimental
Returns the number of bits set in an integer type
TcttzExperimental
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_valueExperimental
Returns the value of the discriminant for the variant in ‘v’;
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 == -1exp2f32⚠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.
forgetExperimental
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.
likelyExperimental
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.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_val⚠Experimental
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
nearbyintf32⚠Experimental
Returns the nearest integer to an
f32.nearbyintf64⚠Experimental
Returns the nearest integer to an
f64.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_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_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 inequalptr_maskExperimental
Masks out bits of the pointer according to a mask.
ptr_offset_from⚠Experimental
See documentation of
<*const T>::offset_from for details.ptr_offset_from_unsigned⚠Experimental
See documentation of
<*const T>::sub_ptr for details.raw_eq⚠Experimental
Determines whether the raw bytes of the two values are equal.
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_leftExperimental
Performs rotate left.
rotate_rightExperimental
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_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.sinf32⚠Experimental
Returns the sine of an
f32.sinf64⚠Experimental
Returns the sine of an
f64.size_ofExperimental
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
f32sqrtf64⚠Experimental
Returns the square root of an
f64sub_with_overflowExperimental
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_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.
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 && y == -1unchecked_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 when
y == 0 or x == T::MIN && y == -1unchecked_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.unlikelyExperimental
Hints to the compiler that branch condition is likely to be false.
Returns the value passed to it.
unreachable⚠Experimental
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_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.vtable_align⚠Experimental
ptr must point to a vtable.
The intrinsic will return the alignment stored in that vtable.vtable_size⚠Experimental
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.
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_place⚠Deprecated
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.