System.AtomicCmpExchange

From RAD Studio API Documentation
Jump to: navigation, search

Delphi

function AtomicCmpExchange(var Target; NewValue: <Integer or NativeInt or Pointer>; Comparand: <Integer or NativeInt or Pointer>; [out Succeeded: Boolean]): Integer; overload;
function AtomicCmpExchange(var Target; NewValue: <Integer or NativeInt or Pointer>; Comparand: <Integer or NativeInt or Pointer>; [out Succeeded: Boolean]): Int64; overload;
function AtomicCmpExchange(var Target; NewValue: <Integer or NativeInt or Pointer>; Comparand: <Integer or NativeInt or Pointer>; [out Succeeded: Boolean]): Pointer; overload;
function AtomicCmpExchange(var Target; NewValue: <Integer or NativeInt or Pointer>; Comparand: <Integer or NativeInt or Pointer>; [out Succeeded: Boolean]): NativeInt; overload;
function AtomicCmpExchange(var Target; NewValue: <Integer or NativeInt or Pointer>; Comparand: <Integer or NativeInt or Pointer>; [out Succeeded: Boolean]): Integer; overload;
function AtomicCmpExchange(var Target; NewValue: <Integer or NativeInt or Pointer>; Comparand: <Integer or NativeInt or Pointer>; [out Succeeded: Boolean]): Int64; overload;
function AtomicCmpExchange(var Target; NewValue: <Integer or NativeInt or Pointer>; Comparand: <Integer or NativeInt or Pointer>; [out Succeeded: Boolean]): Pointer; overload;
function AtomicCmpExchange(var Target; NewValue: <Integer or NativeInt or Pointer>; Comparand: <Integer or NativeInt or Pointer>; [out Succeeded: Boolean]): NativeInt; overload;

Properties

Type Visibility Source Unit Parent
function public System.pas System System

Description

Atomic intrinsic Compare and Exchange function compares the contents of the Target to a given value (Comparand) and, only if they are the same, modifies the contents of Target to the new value.

This function always returns the original value of Target. If a Succeeded parameter is provided, Succeeded becomes True if there is a value exchange (even if both Target and NewValue are the same); it becomes False otherwise.

The System unit provides four atomic intrinsic functions that provide a way to atomically exchange, compare and exchange, increment, and decrement memory values.

AtomicCmpExchange is used for comparing and exchanging memory values.

Atomic operations are used to:

  • Implement multi-threaded locking primitives
  • Provide the primitives necessary for implementing so-called "lock-free" structures

Sample Code

program SystemAtomicCmpExchange;

{$APPTYPE CONSOLE}

{$R *.res}

uses
  System.SysUtils, Winapi.Windows;

var
  Target,
  Comparand,
  Return : Integer;
  Succeeded : Boolean;

const
  ReplaceValue = Integer(5);

begin
  try
    WriteLn('System.AtomicCmpExchange');
    WriteLn;

    Target := 1;
    Comparand := 0;
    WriteLn(Format('Initial values: Target: %d, Comparand: %d, ReplaceValue : %d',
      [Target, Comparand, ReplaceValue]));
    Return := System.AtomicCmpExchange(Target, ReplaceValue, Comparand, Succeeded);
    WriteLn(Format('After calling:  Target: %d, Comparand: %d, Return: %d, Succeeded: %s',
      [Target, Comparand, Return, BoolToStr(Succeeded, true)]));

    WriteLn;

    Target := 1;
    Comparand := 1;
    WriteLn(Format('Initial values: Target: %d, Comparand: %d, ReplaceValue : %d',
      [Target, Comparand, ReplaceValue]));
    Return := System.AtomicCmpExchange(Target, ReplaceValue, Comparand, Succeeded);
    WriteLn(Format('After calling:  Target: %d, Comparand: %d, Return: %d, Succeeded: %s',
      [Target, Comparand, Return, BoolToStr(Succeeded, true)]));

    WriteLn;
    WriteLn('InterlockedCompareExchange');
    WriteLn;

    Target := 1;
    Comparand := 0;
    WriteLn(Format('Initial values: Target: %d, Comparand: %d, ReplaceValue : %d',
      [Target, Comparand, ReplaceValue]));
    Return := InterlockedCompareExchange(Target, ReplaceValue, Comparand);
    WriteLn(Format('After calling:  Target: %d, Comparand: %d, Return: %d',
      [Target, Comparand, Return]));

    WriteLn;

    Target := 1;
    Comparand := 1;
    WriteLn(Format('Initial values: Target: %d, Comparand: %d, ReplaceValue : %d',
      [Target, Comparand, ReplaceValue]));
    Return := InterlockedCompareExchange(Target, ReplaceValue, Comparand);
    WriteLn(Format('After calling:  Target: %d, Comparand: %d, Return: %d',
      [Target, Comparand, Return]));
  except
    on E: Exception do
      Writeln(E.ClassName, ': ', E.Message);
  end;
end.

See Also