_InterlockedExchange Intrinsic Functions

Article
06/05/2017

The new home for Visual Studio documentation is Visual Studio 2017 Documentation on docs.microsoft.com.

The latest version of this topic can be found at _InterlockedExchange Intrinsic Functions.

Microsoft Specific**

Generates an atomic instruction to set a specified value.

Syntax

long _InterlockedExchange(  
   long volatile * Target,  
   long Value  
);  
long _InterlockedExchange_acq(  
   long volatile * Target,  
   long Value  
);  
long _InterlockedExchange_HLEAcquire(  
   long volatile * Target,  
   long Value  
);  
long _InterlockedExchange_HLERelease(  
   long volatile * Target,  
   long Value  
);  
long _InterlockedExchange_nf(  
   long volatile * Target,  
   long Value  
);  
long _InterlockedExchange_rel(  
   long volatile * Target,  
   long Value  
);  
char _InterlockedExchange8(  
   char volatile * Target,  
   char Value  
);  
char _InterlockedExchange8_acq(  
   char volatile * Target,  
   char Value  
);  
char _InterlockedExchange8_nf(  
   char volatile * Target,  
   char Value  
);  
char _InterlockedExchange8_rel(  
   char volatile * Target,  
   char Value  
);  
short _InterlockedExchange16(  
   short volatile * Target,  
   short Value  
);  
short _InterlockedExchange16_acq(  
   short volatile * Target,  
   short Value  
);  
short _InterlockedExchange16_nf(  
   short volatile * Target,  
   short Value  
);  
short _InterlockedExchange16_rel(  
   short volatile * Target,  
   short Value  
);  
__int64 _InterlockedExchange64(  
   __int64 volatile * Target,  
   __int64 Value  
);  
__int64 _InterlockedExchange64_acq(  
   __int64 volatile * Target,  
   __int64 Value  
);  
__int64 _InterlockedExchange64_HLEAcquire(  
   __int64 volatile * Target,  
   __int64 Value  
);  
__int64 _InterlockedExchange64_HLERelease(  
   __int64 volatile * Target,  
   __int64 Value  
);  
__int64 _InterlockedExchange64_nf(  
   __int64 volatile * Target,  
   __int64 Value  
);  
__int64 _InterlockedExchange64_rel(  
   __int64 volatile * Target,  
   __int64 Value  
);

Parameters

[in, out] Target
Pointer to the value to be exchanged. The function sets this variable to Value and returns its prior value.

[in] Value
Value to be exchanged with the value pointed to by Target.

Return Value

Returns the initial value pointed to by Target.

Requirements

Intrinsic	Architecture	Header
`_InterlockedExchange`, `_InterlockedExchange8`, `_InterlockedExchange16`, `_InterlockedExchange64`	x86, ARM, x64	<intrin.h>
`_InterlockedExchange_acq`, `_InterlockedExchange_nf`, `_InterlockedExchange_rel`, `_InterlockedExchange8_acq`, `_InterlockedExchange8_nf`, `_InterlockedExchange8_rel`, `_InterlockedExchange16_acq`, `_InterlockedExchange16_nf`, `_InterlockedExchange16_rel`, `_InterlockedExchange64_acq`, `_InterlockedExchange64_nf`, `_InterlockedExchange64_rel`,	ARM	<intrin.h>
`_InterlockedExchange_HLEAcquire`, `_InterlockedExchange_HLERelease`, `_InterlockedExchange64_HLEAcquire`, `_InterlockedExchange64_HLERelease`	x86, x64	<immintrin.h>

Remarks

_InterlockedExchange provides compiler intrinsic support for the Win32 Windows SDK InterlockedExchange function.

There are several variations on _InterlockedExchange that vary based on the data types they involve and whether processor-specific acquire or release semantics is used.

While the _InterlockedExchange function operates on 32-bit integer values, _InterlockedExchange8 operates on 8-bit integer values, _InterlockedExchange16 operates on 16-bit integer values, and _InterlockedExchange64 operates on 64-bit integer values.

On ARM platforms, use the intrinsics with _acq and _rel suffixes for acquire and release semantics, such as at the beginning and end of a critical section. The intrinsics with an _nf ("no fence") suffix do not act as a memory barrier.

On Intel platforms that support Hardware Lock Elision (HLE) instructions, the intrinsics with _HLEAcquire and _HLERelease suffixes include a hint to the processor that can accelerate performance by eliminating a lock write step in hardware. If these intrinsics are called on platforms that do not support HLE, the hint is ignored.

These routines are only available as intrinsics.

Example

For a sample of how to use _InterlockedExchange, see _InterlockedDecrement.