cmpxchg16b in core::arch::x86_64 - Rust
Description: Compares and exchange 16 bytes (128 bits) of data atomically.
Keywords: rust, rustlang, rust-lang, cmpxchg16b

# Function core::arch::x86_64::cmpxchg16b
[−][src]

    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)
This is supported 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 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.