Function core::arch::x86_64::cmpxchg16b

pub unsafe fn cmpxchg16b(
    dst: *mut u128, 
    old: u128, 
    new: u128, 
    success: Ordering, 
    failure: Ordering
) -> u128

🔬 This is a nightly-only experimental API. (stdsimd #48556)

Available on x86-64 and target feature cmpxchg16b only.

Compares and exchange 16 bytes (128 bits) of data atomically.

This intrinsic corresponds to the cmpxchg16b instruction on x86_64 processors. It performs an atomic compare-and-swap, updating the ptr memory location to val if the current value in memory equals old.

Return value

This function returns the previous value at the memory location. If it is equal to old then the memory was updated to new.

Memory Orderings

This atomic operations has the same semantics of memory orderings as AtomicUsize::compare_exchange does, only operating on 16 bytes of memory instead of just a pointer.

For more information on memory orderings here see the compare_exchange documentation for other Atomic* types in the standard library.

Unsafety

This method is unsafe because it takes a raw pointer and will attempt to read and possibly write the memory at the pointer. The pointer must also be aligned on a 16-byte boundary.

This method also requires the cmpxchg16b CPU feature to be available at runtime to work correctly. If the CPU running the binary does not actually support cmpxchg16b and the program enters an execution path that eventually would reach this function the behavior is undefined.

The success ordering must also be stronger or equal to failure, or this function call is undefined. See the Atomic* documentation’s compare_exchange function for more information. When compare_exchange panics, this is undefined behavior. Currently this function aborts the process with an undefined instruction.