SharedArrayBuffer.prototype.maxByteLength — Eigenschaft · JavaScript-Referenz

Signatur

get SharedArrayBuffer.prototype.maxByteLength

Beschreibung

Die Zugriffs-Eigenschaft maxByteLength ist nur lesbar und liefert die Obergrenze in Bytes, bis zu der ein wachstumsfähiger (growable) SharedArrayBuffer vergrößert werden kann. Den Wert legen Sie einmalig beim Erzeugen fest, und zwar über die Option maxByteLength des Konstruktors: new SharedArrayBuffer(länge, { maxByteLength }). Danach lässt er sich nicht mehr ändern.

Wurde der Puffer ohne die Option maxByteLength erzeugt, ist er nicht wachstumsfähig (growable === false). In diesem Fall gibt maxByteLength denselben Wert wie byteLength zurück.

Die Eigenschaft ist vor allem nützlich, wenn Sie SharedArrayBuffer.prototype.grow() aufrufen wollen. Vor dem Vergrößern können Sie prüfen, ob die gewünschte Größe erlaubt ist, und so einen RangeError vermeiden. Außerdem kann ein Worker, der den Puffer über postMessage() bekommt, die Obergrenze selbst auslesen und seine Speicherplanung (zum Beispiel für Ringpuffer oder wachsende Warteschlangen) daran ausrichten.

Wichtig: Die JavaScript-Engine kann beim Erzeugen den Adressraum für maxByteLength reservieren. Legen Sie die Obergrenze deshalb so fest, wie Sie sie realistisch brauchen, und nicht unnötig hoch.

Rückgabewert

Typ

number

Beschreibung

Die maximale Größe in Bytes als nicht-negative Ganzzahl. Bei nicht wachstumsfähigen Puffern ist der Wert gleich byteLength.

Beispiele

Wachstumsfähigen Puffer anlegen und auslesen

const sab = new SharedArrayBuffer(8, { maxByteLength: 16 });

console.log(sab.byteLength);    // aktuelle Größe
console.log(sab.maxByteLength); // Obergrenze
console.log(sab.growable);

sab.grow(12);
console.log(sab.byteLength, sab.maxByteLength);

8 16 true 12 16

Nicht wachstumsfähiger Puffer: maxByteLength === byteLength

const fixed = new SharedArrayBuffer(1024);

console.log(fixed.growable);
console.log(fixed.maxByteLength);
console.log(fixed.maxByteLength === fixed.byteLength);

false 1024 true

Sicheres Vergrößern mit Prüfung der Obergrenze

const ensureCapacity = (sab, needed) => {
  if (needed <= sab.byteLength) return true;
  if (!sab.growable || needed > sab.maxByteLength) {
    console.warn(`Benötigt ${needed} Bytes, erlaubt sind höchstens ${sab.maxByteLength}.`);
    return false;
  }
  sab.grow(needed);
  return true;
};

const buffer = new SharedArrayBuffer(64, { maxByteLength: 256 });
console.log(ensureCapacity(buffer, 128), buffer.byteLength);
console.log(ensureCapacity(buffer, 512), buffer.byteLength);

true 128 Benötigt 512 Bytes, erlaubt sind höchstens 256. false 128

Obergrenze im Worker auslesen (Node.js)

import { Worker } from 'node:worker_threads';

const sab = new SharedArrayBuffer(4, { maxByteLength: 4096 });

const worker = new Worker(`
  const { parentPort } = require('node:worker_threads');
  parentPort.once('message', (buf) => {
    parentPort.postMessage(`Worker sieht Obergrenze: ${buf.maxByteLength}`);
  });
`, { eval: true });

worker.once('message', (msg) => {
  console.log(msg);
  worker.terminate();
});
worker.postMessage(sab);

Worker sieht Obergrenze: 4096

// Wichtig · Fallstricke

Nur lesbar: Es gibt keinen Setter. Eine Zuweisung wie sab.maxByteLength = 32 wird im nicht-strikten Modus stillschweigend ignoriert und löst im strikten Modus einen TypeError aus.
Nur vergrößern: grow() kann einen Puffer nicht verkleinern. Werte, die kleiner als byteLength oder größer als maxByteLength sind, lösen einen RangeError aus.
Ist die Option maxByteLength im Konstruktor kleiner als die Anfangslänge, wirft der Konstruktor einen RangeError.
Große Obergrenzen können Adressraum reservieren. Ist das nicht möglich, schlägt schon der Konstruktor fehl, obwohl der Puffer anfangs klein ist.
Browser: SharedArrayBuffer gibt es nur in cross-origin-isolierten Kontexten. Dafür sind die Header Cross-Origin-Opener-Policy: same-origin und Cross-Origin-Embedder-Policy: require-corp nötig. Prüfen Sie das mit self.crossOriginIsolated.
Kompatibilität: Wachstumsfähige Puffer gibt es seit ES2024. In älteren Engines fehlt maxByteLength (undefined). Für eine Feature-Erkennung eignet sich 'maxByteLength' in SharedArrayBuffer.prototype.

Siehe auch

SharedArrayBuffer SharedArrayBuffer.prototype.grow() SharedArrayBuffer.prototype.growable SharedArrayBuffer.prototype.byteLength ArrayBuffer.prototype.maxByteLength Atomics