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() statische Methode tauscht einen gegebenen Ersatzwert an einer bestimmten Position im Array aus, wenn ein erwarteter Wert dem alten Wert entspricht. Es gibt den alten Wert an dieser Position zurück, unabhängig davon, ob er dem erwarteten Wert entsprach oder nicht. Dieser atomare Vorgang garantiert, dass keine andere Schreibaktion 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 integer-typisiertes Array. Eine der folgenden: Int8Array, Uint8Array, Int16Array, Uint16Array, Int32Array, Uint32Array, BigInt64Array oder BigUint64Array.
index: Die Position im typedArray, an der ein replacementValue ausgetauscht wird.
expectedValue: Der Wert, der auf Gleichheit überprüft werden soll.
replacementValue: Die Zahl, die ausgetauscht wird.

Rückgabewert

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

Ausnahmen

TypeError: Wird ausgelöst, wenn typedArray nicht einer der erlaubten Integer-Typen ist.
RangeError: Wird ausgelöst, wenn index außerhalb der Grenzen des 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

Vergleich und Tausch garantiert, dass der neue Wert auf der Grundlage aktueller Informationen berechnet wird; wenn der Wert in der Zwischenzeit von einem anderen Thread aktualisiert wurde, schlägt der Schreibvorgang fehl. Daher sollten Sie den Rückgabewert von compareExchange() überprüfen, um festzustellen, ob er fehlgeschlagen ist, und falls nötig 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 wird versucht, ihn mit dem neuen Wert zu aktualisieren. Es wird so lange versucht, bis der Wert erfolgreich aktualisiert wurde.

Spezifikationen

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