ArrayBuffer.prototype.maxByteLength — Eigenschaft · JavaScript-Referenz

Signatur

get ArrayBuffer.prototype.maxByteLength

Beschreibung

Die Accessor-Eigenschaft maxByteLength gibt an, auf wie viele Bytes ein ArrayBuffer höchstens anwachsen kann. Den Wert legt man beim Erzeugen über die Option maxByteLength fest: new ArrayBuffer(länge, { maxByteLength }). Danach ist er nur noch lesbar. Einen Setter gibt es nicht.

Bei größenveränderbaren Buffern (resizable === true) ist maxByteLength die feste Obergrenze für ArrayBuffer.prototype.resize(). Bei festen Buffern ohne diese Option hat maxByteLength immer denselben Wert wie byteLength.

Die Eigenschaft ist praktisch, wenn Speicher schrittweise wachsen soll, zum Beispiel bei Stream-Puffern, Parsern oder WebAssembly-nahem Code. Vor einem resize() kann man damit prüfen, ob die gewünschte Größe überhaupt erlaubt ist, statt einen RangeError abzufangen. Wird ein Buffer abgelöst (detached), etwa durch transfer() oder postMessage mit Transfer-Liste, liefert maxByteLength den Wert 0.

Rückgabewert

Typ

number

Beschreibung

Nicht-negative ganze Zahl: die maximale Größe in Bytes. Bei festen Buffern gleich byteLength, bei abgelösten Buffern 0.

Beispiele

Größenveränderbaren Buffer anlegen und Grenze auslesen

const buffer = new ArrayBuffer(8, { maxByteLength: 64 });

console.log(buffer.byteLength);    // aktuelle Größe
console.log(buffer.maxByteLength); // Obergrenze
console.log(buffer.resizable);

buffer.resize(32);
console.log(buffer.byteLength, buffer.maxByteLength);

8 64 true 32 64

Fester Buffer: maxByteLength entspricht byteLength

const fixed = new ArrayBuffer(16);

console.log(fixed.resizable);                          // false
console.log(fixed.maxByteLength);                      // 16
console.log(fixed.maxByteLength === fixed.byteLength); // true

false 16 true

Sicher wachsen: Anfrage auf das Maximum begrenzen

const buffer = new ArrayBuffer(0, { maxByteLength: 1024 });
const view = new Uint8Array(buffer); // längenabhängige Ansicht wächst mit

const append = (bytes) => {
  const needed = buffer.byteLength + bytes.length;
  if (needed > buffer.maxByteLength) {
    throw new RangeError(`Puffer voll: ${needed} > ${buffer.maxByteLength} Bytes`);
  }
  const offset = buffer.byteLength;
  buffer.resize(needed);
  view.set(bytes, offset);
};

append(new Uint8Array([1, 2, 3]));
append(new Uint8Array([4, 5]));
console.log(view.length, [...view]);

try {
  append(new Uint8Array(2000));
} catch (err) {
  console.log(err.message);
}

5 [ 1, 2, 3, 4, 5 ] Puffer voll: 2005 > 1024 Bytes

Nach transfer() ist der alte Buffer abgelöst

const original = new ArrayBuffer(4, { maxByteLength: 16 });
const moved = original.transfer();

console.log(original.detached, original.maxByteLength); // true 0
console.log(moved.resizable, moved.maxByteLength);      // true 16

true 0 true 16

// Wichtig · Fallstricke

Nur lesbar: Eine Zuweisung wie buffer.maxByteLength = 128 bewirkt nichts und wirft im Strict Mode einen TypeError. Die Obergrenze lässt sich nur beim Konstruktor-Aufruf festlegen.
RangeError im Konstruktor: Ist maxByteLength kleiner als die Anfangslänge, wirft new ArrayBuffer() einen RangeError. Dasselbe passiert, wenn resize() einen Wert größer als maxByteLength bekommt.
Speicher: Engines dürfen den Adressraum bis maxByteLength vorab reservieren. Sehr große Werte wie 2 ** 32 können daher fehlschlagen oder unnötig Adressraum belegen. Wähle eine realistische Obergrenze.
Kompatibilität: Neu in ES2024. Ältere Engines ignorieren das Options-Objekt und legen einen festen Buffer an. maxByteLength ist dort undefined. Zur Erkennung eignet sich 'maxByteLength' in ArrayBuffer.prototype.
Für SharedArrayBuffer gibt es das Gegenstück SharedArrayBuffer.prototype.maxByteLength. Dort wird mit grow() vergrößert, und Verkleinern ist nicht möglich.

Siehe auch

ArrayBuffer ArrayBuffer.prototype.byteLength ArrayBuffer.prototype.resizable ArrayBuffer.prototype.resize() ArrayBuffer.prototype.transfer() SharedArrayBuffer.prototype.maxByteLength