SharedArrayBuffer

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.

* Some parts of this feature may have varying levels of support.

Das SharedArrayBuffer-Objekt wird verwendet, um einen generischen Rohdatenpuffer darzustellen, ähnlich dem ArrayBuffer-Objekt, jedoch auf eine Weise, die es ermöglicht, Ansichten auf den gemeinsamen Speicher zu erstellen. Ein SharedArrayBuffer ist kein Transferable Object, im Gegensatz zu einem ArrayBuffer, der übertragbar ist.

Beschreibung

Um Speicher mit SharedArrayBuffer-Objekten von einem Agenten im Cluster zu einem anderen zu teilen (ein Agent ist entweder das Hauptprogramm der Webseite oder einer ihrer Web-Worker), wird postMessage und structured cloning verwendet.

Der strukturierte Klon-Algorithmus akzeptiert SharedArrayBuffer-Objekte und typisierte Arrays, die auf SharedArrayBuffer-Objekte abgebildet sind. In beiden Fällen wird das SharedArrayBuffer-Objekt an den Empfänger übertragen, was zu einem neuen, privaten SharedArrayBuffer-Objekt im empfangenden Agenten führt (ebenso wie bei ArrayBuffer). Jedoch verweist der gemeinsame Datenblock, auf den die beiden SharedArrayBuffer-Objekte verweisen, auf denselben Datenblock, und eine Nebenwirkung auf den Block in einem Agenten wird schließlich im anderen Agenten sichtbar.

js
const sab = new SharedArrayBuffer(1024);
worker.postMessage(sab);

Gemeinsamer Speicher kann gleichzeitig in Workern oder im Haupt-Thread erstellt und aktualisiert werden. Abhängig vom System (die CPU, das Betriebssystem, der Browser) kann es eine Weile dauern, bis die Änderung in allen Kontexten propagiert wird. Zur Synchronisation sind atomare Operationen erforderlich.

SharedArrayBuffer-Objekte werden von einigen Web-APIs verwendet, wie z.B.:

Sicherheitsanforderungen

Gemeinsamer Speicher und hochauflösende Timer wurden zu Beginn des Jahres 2018 effektiv deaktiviert angesichts Spectre. Im Jahr 2020 wurde ein neuer, sicherer Ansatz standardisiert, um gemeinsamen Speicher wieder zu aktivieren.

Um gemeinsamen Speicher zu verwenden, muss Ihr Dokument in einem sicheren Kontext und cross-origin isoliert sein. Sie können die Eigenschaften Window.crossOriginIsolated und WorkerGlobalScope.crossOriginIsolated verwenden, um zu prüfen, ob das Dokument cross-origin isoliert ist:

js
const myWorker = new Worker("worker.js");

if (crossOriginIsolated) {
  const buffer = new SharedArrayBuffer(16);
  myWorker.postMessage(buffer);
} else {
  const buffer = new ArrayBuffer(16);
  myWorker.postMessage(buffer);
}

Wenn es cross-origin isoliert ist, wirft postMessage() nicht mehr für SharedArrayBuffer-Objekte, und gemeinsamer Speicher über Threads hinweg ist daher verfügbar.

API-Verfügbarkeit

Je nachdem, ob die oben genannten Sicherheitsmaßnahmen ergriffen werden, haben die verschiedenen Speicherfreigabe-APIs unterschiedliche Verfügbarkeiten:

  • Das Atomics-Objekt ist stets verfügbar.
  • SharedArrayBuffer-Objekte sind grundsätzlich immer verfügbar, aber leider ist der Konstruktor auf dem globalen Objekt verborgen, es sei denn, die beiden oben genannten Header sind gesetzt, um Kompatibilität mit Webinhalten zu gewährleisten. Es besteht die Hoffnung, dass diese Einschränkung in Zukunft entfernt werden kann. WebAssembly.Memory kann weiterhin zur Instanzerstellung verwendet werden.
  • Sofern die beiden oben genannten Header nicht gesetzt sind, werden die verschiedenen postMessage()-APIs für SharedArrayBuffer-Objekte eine Ausnahme werfen. Wenn sie gesetzt sind, funktioniert postMessage() auf Window-Objekten und dedizierten Workern und erlaubt eine Speicherfreigabe.

WebAssembly gemeinsamer Speicher

WebAssembly.Memory-Objekte können mit dem shared Konstruktor-Flag erstellt werden. Wenn dieses Flag auf true gesetzt ist, kann das konstruierte Memory-Objekt zwischen Workern über postMessage() geteilt werden, genau wie SharedArrayBuffer, und der unterstützende buffer des Memory-Objekts ist ein SharedArrayBuffer. Daher gelten die oben genannten Anforderungen für das Teilen eines SharedArrayBuffer zwischen Workern auch für das Teilen eines WebAssembly.Memory.

Der WebAssembly Threads-Vorschlag definiert auch eine neue Reihe von atomaren Anweisungen. Genau wie SharedArrayBuffer und seine Methoden bedingungslos aktiviert sind (und nur das Teilen zwischen Threads neuen Headern unterliegt), sind auch die WebAssembly atomaren Anweisungen bedingungslos erlaubt.

Wachstum von SharedArrayBuffers

SharedArrayBuffer-Objekte können durch Einschließen der maxByteLength-Option beim Aufruf des SharedArrayBuffer()-Konstruktors vergrößerbar gemacht werden. Sie können abfragen, ob ein SharedArrayBuffer vergrößerbar ist und welche maximale Größe er hat, indem Sie seine growable- und maxByteLength-Eigenschaften aufrufen. Sie können einem vergrößerbaren SharedArrayBuffer mit einem grow()-Aufruf eine neue Größe zuweisen. Neue Bytes werden mit 0 initialisiert.

Diese Funktionen machen das Wachstum von SharedArrayBuffers effizienter — andernfalls müssten Sie eine Kopie des Puffers mit neuer Größe erstellen. Es bietet JavaScript auch Parität mit WebAssembly in dieser Hinsicht (Wasm-Linearspeicher kann mit WebAssembly.Memory.prototype.grow() resizeredimensioniert werden).

Aus Sicherheitsgründen können SharedArrayBuffers nicht verkleinert, sondern nur vergrößert werden.

Konstruktor

SharedArrayBuffer()

Erstellt ein neues SharedArrayBuffer-Objekt.

Statische Eigenschaften

SharedArrayBuffer[Symbol.species]

Gibt den Konstruktor zurück, der verwendet wird, um Rückgabewerte von SharedArrayBuffer-Methoden zu konstruieren.

Instanz-Eigenschaften

Diese Eigenschaften sind auf SharedArrayBuffer.prototype definiert und werden von allen SharedArrayBuffer-Instanzen geteilt.

SharedArrayBuffer.prototype.byteLength

Die Größe des Arrays in Bytes. Dies wird bei der Erstellung des Arrays festgelegt und kann nur mit der SharedArrayBuffer.prototype.grow()-Methode geändert werden, wenn der SharedArrayBuffer vergrößerbar ist.

SharedArrayBuffer.prototype.constructor

Die Konstruktorfunktion, die das Instanzobjekt erstellt hat. Für SharedArrayBuffer-Instanzen ist der anfängliche Wert der SharedArrayBuffer-Konstruktor.

SharedArrayBuffer.prototype.growable

Schreibgeschützt. Gibt true zurück, wenn der SharedArrayBuffer vergrößerbar ist, andernfalls false.

SharedArrayBuffer.prototype.maxByteLength

Die schreibgeschützte maximale Länge in Bytes, auf die der SharedArrayBuffer vergrößert werden kann. Dies wird bei der Erstellung des Arrays festgelegt und kann nicht geändert werden.

SharedArrayBuffer.prototype[Symbol.toStringTag]

Der anfängliche Wert der [Symbol.toStringTag]-Eigenschaft ist der String "SharedArrayBuffer". Diese Eigenschaft wird in Object.prototype.toString() verwendet.

Instanz-Methoden

SharedArrayBuffer.prototype.grow()

Vergrößert den SharedArrayBuffer auf die angegebene Größe in Bytes.

SharedArrayBuffer.prototype.slice()

Gibt einen neuen SharedArrayBuffer zurück, dessen Inhalt eine Kopie der Bytes dieses SharedArrayBuffer von begin (einschließlich) bis end (ausschließlich) ist. Wenn begin oder end negativ sind, beziehen sie sich auf einen Index vom Ende des Arrays statt vom Anfang.

Beispiele

Erstellen eines neuen SharedArrayBuffer

js
const sab = new SharedArrayBuffer(1024);

Slicing des SharedArrayBuffer

js
sab.slice(); // SharedArrayBuffer { byteLength: 1024 }
sab.slice(2); // SharedArrayBuffer { byteLength: 1022 }
sab.slice(-2); // SharedArrayBuffer { byteLength: 2 }
sab.slice(0, 1); // SharedArrayBuffer { byteLength: 1 }

Verwendung in einem WebGL-Puffer

js
const canvas = document.querySelector("canvas");
const gl = canvas.getContext("webgl");
const buffer = gl.createBuffer();
gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
gl.bufferData(gl.ARRAY_BUFFER, sab, gl.STATIC_DRAW);

Spezifikationen

Specification
ECMAScript® 2025 Language Specification
# sec-sharedarraybuffer-objects

Browser-Kompatibilität

Report problems with this compatibility data on GitHub
desktopmobileserver
Chrome
Edge
Firefox
Opera
Safari
Chrome Android
Firefox for Android
Opera Android
Safari on iOS
Samsung Internet
WebView Android
WebView on iOS
Deno
Node.js
SharedArrayBuffer
[Symbol.species]
SharedArrayBuffer() constructor
maxByteLength option
byteLength
grow
growable
maxByteLength
slice

Legend

Tip: you can click/tap on a cell for more information.

Full support
Full support
No support
No support

Siehe auch