SharedArrayBuffer.prototype.byteLength — Eigenschaft · JavaScript-Referenz

Signatur

get SharedArrayBuffer.prototype.byteLength

Beschreibung

Die Zugriffseigenschaft byteLength liefert die Größe des gemeinsam genutzten Speicherbereichs eines SharedArrayBuffer in Bytes. Der Wert wird beim Erzeugen über den Konstruktor festgelegt, z. B. new SharedArrayBuffer(1024). Es gibt nur einen Getter und keinen Setter: Eine Zuweisung hat keine Wirkung und wirft im Strict Mode einen TypeError.

Bei wachstumsfähigen Puffern (erzeugt mit der Option { maxByteLength }, ES2024) gibt byteLength immer die aktuelle Größe an. Nach einem Aufruf von grow() steigt der Wert. Die Obergrenze steht in maxByteLength. Ein SharedArrayBuffer kann nie schrumpfen und nicht abgetrennt (detached) werden, deshalb ist byteLength nie kleiner als beim Erzeugen.

In der Praxis brauchst du byteLength, um typisierte Sichten wie Int32Array oder Float64Array passend zu dimensionieren, um Grenzen vor Atomics-Operationen zu prüfen oder um die Puffergröße zwischen Hauptthread und Workern abzustimmen.

Rückgabewert

Typ

number

Beschreibung

Eine nicht negative ganze Zahl: die aktuelle Länge des Puffers in Bytes.

Beispiele

Größe eines Puffers abfragen

const sab = new SharedArrayBuffer(16);
console.log(sab.byteLength);

// Zuweisung wird ignoriert (kein Setter)
sab.byteLength = 64;
console.log(sab.byteLength);

16 16

Typisierte Sicht passend zur Puffergröße anlegen

const sab = new SharedArrayBuffer(1024);
const ints = new Int32Array(sab);

// Anzahl der Elemente aus der Bytegröße ableiten
const anzahl = sab.byteLength / Int32Array.BYTES_PER_ELEMENT;
console.log(anzahl, ints.length);

Atomics.store(ints, anzahl - 1, 42);
console.log(Atomics.load(ints, anzahl - 1));

256 256 42

Wachstumsfähigen Puffer vergrößern (ES2024)

const sab = new SharedArrayBuffer(8, { maxByteLength: 64 });
console.log(sab.byteLength, sab.maxByteLength, sab.growable);

sab.grow(32);
console.log(sab.byteLength);

// Längenverfolgende Sicht wächst automatisch mit
const view = new Uint8Array(sab);
sab.grow(48);
console.log(view.length);

8 64 true 32 48

Puffergröße im Worker prüfen

// main.js
const sab = new SharedArrayBuffer(4096);
const worker = new Worker('worker.js');
worker.postMessage(sab);

// worker.js
self.onmessage = ({ data }) => {
  if (data.byteLength < 4096) {
    throw new RangeError('Puffer zu klein');
  }
  console.log(`Gemeinsamer Speicher: ${data.byteLength} Bytes`);
};

Gemeinsamer Speicher: 4096 Bytes

// Wichtig · Fallstricke

Nur lesbar: Eine Zuweisung an byteLength ändert nichts und wirft im Strict Mode einen TypeError. Zum Vergrößern nimmst du grow(), das nur bei wachstumsfähigen Puffern funktioniert.
Nebenläufigkeit: Bei wachstumsfähigen Puffern kann ein anderer Thread den Puffer gleichzeitig vergrößern. Ein einmal gelesener Wert kann also schnell veraltet sein. Er kann aber nie kleiner werden.
Wird der Getter auf einem ArrayBuffer oder einem anderen Objekt aufgerufen (z. B. über call), wirft er einen TypeError.
Verfügbarkeit im Browser: SharedArrayBuffer gibt es nur in cross-origin-isolierten Kontexten. Dafür müssen die HTTP-Header Cross-Origin-Opener-Policy: same-origin und Cross-Origin-Embedder-Policy: require-corp gesetzt sein. Ob das zutrifft, zeigt self.crossOriginIsolated. In Node.js ist die Klasse ohne Einschränkung verfügbar.
Wachstumsfähige Puffer (maxByteLength, grow()) gibt es erst seit ES2024. Ältere Umgebungen ignorieren die Option, und dort fehlt grow.

Siehe auch

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