Skip to main content
InterlockedCompareExchange128 function

Performs an atomic compare-and-exchange operation on the specified values. The function compares two specified 128-bit values and exchanges with another 128-bit value based on the outcome of the comparison.

To operate on 16-bit values, use the InterlockedCompareExchange16 function.

To operate on 32-bit values, use the InterlockedCompareExchange function.

To operate on 64-bit values, use the InterlockedCompareExchange64 function.

Syntax


unsigned char __cdecl InterlockedCompareExchange128(
  _Inout_  LONGLONG volatile *Destination,
  _In_     LONGLONG ExchangeHigh,
  _In_     LONGLONG ExchangeLow,
  _Inout_  LONGLONG *ComparandResult
);

Parameters

Destination [in, out]

A pointer to the destination value. This parameter is an array of two 64-bit integers considered as a 128-bit field.

ExchangeHigh [in]

The high part of the exchange value.

ExchangeLow [in]

The low part of the exchange value.

ComparandResult [in, out]

The value to compare to. This parameter is an array of two 64-bit integers considered as a 128-bit field.

Return value

The function returns 1 if ComparandResult equals the original value of the Destination parameter, or 0 if ComparandResult does not equal the original value of the Destination parameter.

Remarks

The function compares the Destination value with the ComparandResult value:

  • If the Destination value is equal to the ComparandResult value, the ExchangeHigh and ExchangeLow values are stored in the array specified by Destination, and also in the array specified by ComparandResult.
  • Otherwise, the ExchangeHigh and ExchangeLow values are only stored in the array specified by ComparandResult.

The parameters for this function must be aligned on a 16-byte boundary; otherwise, the function will behave unpredictably on x64 systems. See _aligned_malloc.

The interlocked functions provide a simple mechanism for synchronizing access to a variable that is shared by multiple threads. This function is atomic with respect to calls to other interlocked functions.

This function is only available on x64-based systems, and it is implemented using a compiler intrinsic. For more information, see the WinBase.h header file and _InterlockedCompareExchange128.

This function generates a full memory barrier (or fence) to ensure that memory operations are completed in order.

Requirements

Minimum supported client

Windows 8 [desktop apps only]

Minimum supported server

Windows Server 2012 [desktop apps only]

Header

Winnt.h (include Windows.h)

See also

Interlocked Variable Access
InterlockedCompare64Exchange128
InterlockedCompareExchange
InterlockedCompareExchangeAcquire
InterlockedCompareExchangeRelease
InterlockedCompareExchangeNoFence
InterlockedCompareExchange16
InterlockedCompareExchange16Acquire
InterlockedCompareExchange16Release
InterlockedCompareExchange16NoFence
InterlockedCompareExchange64
InterlockedCompareExchangeAcquire64
InterlockedCompareExchangeRelease64
InterlockedCompareExchangeNoFence64
InterlockedCompareExchangePointer
InterlockedCompareExchangePointerAcquire
InterlockedCompareExchangePointerRelease
InterlockedCompareExchangePointerNoFence
Synchronization Functions