Atomics.compareExchange()

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since December 2021.

Die Atomics.compareExchange()-statistische Methode tauscht einen gegebenen Ersatzwert an einer bestimmten Position im Array aus, wenn ein erwarteter Wert dem alten Wert entspricht. Sie gibt den alten Wert an dieser Position zurück, unabhängig davon, ob er dem erwarteten Wert entsprach oder nicht. Diese atomare Operation garantiert, dass kein anderer Schreibvorgang erfolgt, bis der geänderte Wert zurückgeschrieben wird.

Probieren Sie es aus

// Create a SharedArrayBuffer with a size in bytes
const buffer = new SharedArrayBuffer(16);
const uint8 = new Uint8Array(buffer);
uint8[0] = 5;

Atomics.compareExchange(uint8, 0, 5, 2); // Returns 5
console.log(Atomics.load(uint8, 0));
// Expected output: 2

Atomics.compareExchange(uint8, 0, 5, 4); // Returns 2
console.log(Atomics.load(uint8, 0));
// Expected output: 2

Syntax

Atomics.compareExchange(typedArray, index, expectedValue, replacementValue)

Parameter

typedArray: Ein Ganzzahl-Typ-Array. Eines von Int8Array, Uint8Array, Int16Array, Uint16Array, Int32Array, Uint32Array, BigInt64Array oder BigUint64Array.
index: Die Position im typedArray, um einen replacementValue auszutauschen.
expectedValue: Der Wert, um die Gleichheit zu überprüfen.
replacementValue: Die Zahl, die ausgetauscht werden soll.

Rückgabewert

Der alte Wert an der angegebenen Position (typedArray[index]). Wenn der Rückgabewert gleich expectedValue ist, war der Austausch erfolgreich; andernfalls ist der Austausch fehlgeschlagen.

Ausnahmen

TypeError: Wird ausgelöst, wenn typedArray nicht einer der erlaubten Ganzzahltypen ist.
RangeError: Wird ausgelöst, wenn index außerhalb der Grenzen im typedArray liegt.

Beispiele

Verwendung von compareExchange()

const sab = new SharedArrayBuffer(1024);
const ta = new Uint8Array(sab);
ta[0] = 7;

Atomics.compareExchange(ta, 0, 7, 12); // returns 7, the old value
Atomics.load(ta, 0); // 12

Überprüfung des Rückgabewertes

Compare-and-swap gewährleistet, dass der neue Wert auf Basis aktueller Informationen berechnet wird; wenn der Wert inzwischen von einem anderen Thread aktualisiert wurde, würde der Schreibvorgang fehlschlagen. Daher sollten Sie den Rückgabewert von compareExchange() überprüfen, um festzustellen, ob er fehlgeschlagen ist, und bei Bedarf erneut versuchen.

Hier ist ein Beispiel für einen atomaren Addierer (gleiche Funktionalität wie Atomics.add()), angepasst aus dem verlinkten Wikipedia-Artikel:

function add(mem, index, a) {
  let done = false;
  while (!done) {
    const value = Atomics.load(mem, index);
    done = Atomics.compareExchange(mem, index, value, value + a) === value;
  }
  return value + a;
}

Zuerst wird der Wert an dem angegebenen Index gelesen, dann versucht, ihn mit dem neuen Wert zu aktualisieren. Der Vorgang wird so lange wiederholt, bis der Wert erfolgreich aktualisiert wird.

Spezifikationen

Specification
ECMAScript® 2026 Language Specification # sec-atomics.compareexchange