core::arch::x86_64::cmpxchg16b - Rust
Description: API documentation for the Rust `cmpxchg16b` fn in crate `core`.
Keywords: rust, rustlang, rust-lang, cmpxchg16b

# [−][src]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)
This is supported on x86-64 and target feature `cmpxchg16b` only.

Compare 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.

# Help

## Keyboard Shortcuts

`?`
  Show this help dialog
`S`
  Focus the search field
`↑`
  Move up in search results
`↓`
  Move down in search results
`↹`
  Switch tab
`⏎`
  Go to active search result
`+`
  Expand all sections
`-`
  Collapse all sections

## Search Tricks

Prefix searches with a type followed by a colon (e.g., `fn:`) to restrict the search to a given type.

Accepted types are: `fn`, `mod`, `struct`, `enum`, `trait`, `type`, `macro`, and `const`.

Search functions by type signature (e.g., `vec -> usize` or `* -> vec`)

Search multiple things at once by splitting your query with comma (e.g., `str,u8` or `String,struct:Vec,test`)