SharedArrayBuffer.prototype.growable — Eigenschaft · JavaScript-Referenz

Signatur

get SharedArrayBuffer.prototype.growable

Beschreibung

Die Zugriffseigenschaft growable ist schreibgeschützt. Sie gibt true zurück, wenn der SharedArrayBuffer mit der Option maxByteLength erzeugt wurde. Ohne diese Option ist sie false. Ein erweiterbarer Puffer lässt sich zur Laufzeit mit SharedArrayBuffer.prototype.grow() bis höchstens maxByteLength vergrößern.

Die Eigenschaft ist vor allem dann nützlich, wenn Code einen Puffer von außen erhält, etwa per postMessage aus einem Worker oder aus einer Bibliothek, und prüfen muss, ob ein Aufruf von grow() möglich ist. Ruft man grow() auf einem nicht erweiterbaren Puffer auf, wird ein TypeError geworfen.

Anders als ein ArrayBuffer kann ein SharedArrayBuffer nur wachsen, nie schrumpfen, weil andere Threads gleichzeitig auf den Speicher zugreifen. Deshalb gibt es kein resizable, sondern growable. Das Gegenstück bei ArrayBuffer ist ArrayBuffer.prototype.resizable.

Rückgabewert

Typ

boolean

Beschreibung

true, wenn der Puffer mit maxByteLength erzeugt wurde und damit erweiterbar ist, sonst false.

Beispiele

Erweiterbaren und festen Puffer vergleichen

const fest = new SharedArrayBuffer(8);
const erweiterbar = new SharedArrayBuffer(8, { maxByteLength: 64 });

console.log(fest.growable);
console.log(erweiterbar.growable);
console.log(erweiterbar.maxByteLength);

false true 64

Vor dem Vergrößern prüfen, ob grow() möglich ist

const ensureCapacity = (sab, needed) => {
  if (sab.byteLength >= needed) return true;
  if (!sab.growable || needed > sab.maxByteLength) {
    console.warn(`Kann nicht auf ${needed} Bytes wachsen`);
    return false;
  }
  sab.grow(needed);
  return true;
};

const sab = new SharedArrayBuffer(16, { maxByteLength: 256 });
ensureCapacity(sab, 128);
console.log(sab.byteLength);

ensureCapacity(new SharedArrayBuffer(16), 32);

128 Kann nicht auf 32 Bytes wachsen

Längenabhängige Typed-Array-Sicht wächst mit

const sab = new SharedArrayBuffer(4, { maxByteLength: 16 });
const view = new Int32Array(sab); // ohne feste Länge: folgt byteLength

console.log(sab.growable, view.length);
sab.grow(16);
console.log(view.length);

true 1 4

// Wichtig · Fallstricke

Nur lesbar: Die Eigenschaft ist ein reiner Getter. Eine Zuweisung wie sab.growable = true wird im nicht-strikten Modus stillschweigend ignoriert und wirft im strikten Modus einen TypeError. Ob ein Puffer erweiterbar ist, lässt sich nur beim Erzeugen festlegen.
Bei nicht erweiterbaren Puffern ist maxByteLength gleich byteLength.
Voraussetzungen: SharedArrayBuffer steht im Browser nur in einem cross-origin-isolierten Kontext zur Verfügung. Dafür braucht es die HTTP-Header Cross-Origin-Opener-Policy: same-origin und Cross-Origin-Embedder-Policy: require-corp. Prüfen lässt sich das mit self.crossOriginIsolated.
Kompatibilität: Erweiterbare Puffer sind Teil von ES2024. Unterstützt werden sie ab Chrome/Edge 111, Firefox 128, Safari 16.4 und Node.js 20. In älteren Umgebungen ist growable undefined. Deshalb sollte man sab.growable === true prüfen statt nur auf einen falschen Wert.
Wenn ein anderer Thread den Puffer vergrößert, sehen Sichten ohne feste Länge die neue Größe automatisch. Für die Synchronisation sollte man Atomics verwenden.

Siehe auch

Atomics SharedArrayBuffer[Symbol.species] SharedArrayBuffer.prototype.byteLength SharedArrayBuffer.prototype.maxByteLength ArrayBuffer.prototype.resizable