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 for use with Delphi mobile compilers. 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.

Because the Delphi mobile compilers do not support a built-in assembler, 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