Function core::core_arch::x86_64::cmpxchg16b::cmpxchg16b

1.67.0 · source ·
pub unsafe fn cmpxchg16b(
    dst: *mut u128,
    old: u128,
    new: u128,
    success: Ordering,
    failure: Ordering
) -> u128
Available on x86-64 and target feature cmpxchg16b only.
Expand description

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 operation has the same semantics of memory orderings as AtomicUsize::compare_exchange does, only operating on 16 bytes of memory instead of just a pointer.

The failure ordering must be Ordering::SeqCst, Ordering::Acquire or Ordering::Relaxed.

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.