ByteLengthQueuingStrategy.highWaterMark — Eigenschaft · JavaScript-Referenz

Signatur

get ByteLengthQueuingStrategy.prototype.highWaterMark

Beschreibung

Die schreibgeschützte Eigenschaft highWaterMark einer ByteLengthQueuingStrategy liefert den Schwellenwert in Bytes, der beim Erzeugen der Strategie über new ByteLengthQueuingStrategy({ highWaterMark }) festgelegt wurde. Der Wert ist die Obergrenze für die Gesamtgröße aller Datenblöcke (Chunks), die sich in der internen Warteschlange eines ReadableStream oder WritableStream befinden dürfen.

Die Größe eines Chunks ermittelt die Strategie über ihre Methode size(chunk), die einfach chunk.byteLength zurückgibt. Überschreitet die Summe der Chunk-Größen in der Warteschlange den highWaterMark, wird desiredSize des Controllers bzw. Writers null oder negativ – das ist das Signal für Backpressure: Eine Quelle sollte dann keine weiteren Daten erzeugen, und bei WritableStream wird writer.ready erst wieder erfüllt, wenn Platz frei ist.

Sinnvoll ist die Eigenschaft vor allem zur Kontrolle und Fehlersuche: Man kann prüfen, welche Pufferobergrenze eine wiederverwendete Strategie besitzt, oder sie für Logging und Metriken auslesen. Verändern lässt sich der Wert nachträglich nicht – für einen anderen Schwellenwert erzeugt man eine neue Strategie.

Rückgabewert

Typ

number

Beschreibung

Der beim Konstruktor übergebene Schwellenwert in Bytes (nicht-negative Zahl, auch Infinity möglich).

Beispiele

Strategie anlegen und Schwellenwert auslesen

const strategy = new ByteLengthQueuingStrategy({ highWaterMark: 64 * 1024 });

console.log(strategy.highWaterMark);
console.log(strategy.size(new Uint8Array(1024)));

65536 1024

ReadableStream mit Byte-basierter Backpressure

const strategy = new ByteLengthQueuingStrategy({ highWaterMark: 16 });

const stream = new ReadableStream({
  start(controller) {
    // Zwei Chunks à 10 Bytes = 20 Bytes > 16 Bytes
    controller.enqueue(new Uint8Array(10));
    controller.enqueue(new Uint8Array(10));
    console.log(`Limit: ${strategy.highWaterMark} Bytes`);
    console.log(`desiredSize: ${controller.desiredSize}`);
  }
}, strategy);

Limit: 16 Bytes desiredSize: -4

WritableStream: auf writer.ready warten

const strategy = new ByteLengthQueuingStrategy({ highWaterMark: 1024 });

const sink = new WritableStream({
  async write(chunk) {
    // Langsames Ziel simulieren
    await new Promise((r) => setTimeout(r, 50));
  }
}, strategy);

const writer = sink.getWriter();
console.log(`Puffer bis ${strategy.highWaterMark} Bytes`);

for (let i = 0; i < 5; i++) {
  await writer.ready; // respektiert Backpressure
  writer.write(new Uint8Array(512));
  console.log(`Chunk ${i}, desiredSize: ${writer.desiredSize}`);
}
await writer.close();

Puffer bis 1024 Bytes Chunk 0, desiredSize: 1024 Chunk 1, desiredSize: 512 Chunk 2, desiredSize: 0 ...

// Wichtig · Fallstricke

Schreibgeschützt: Eine Zuweisung wie strategy.highWaterMark = 10 wird ignoriert (im Strict Mode TypeError). Für einen anderen Wert eine neue Strategie erzeugen.
Nur für Byte-Chunks: size() liest chunk.byteLength. Bei Strings oder normalen Objekten ist das undefined, was zu einem RangeError bzw. Stream-Fehler führt. Für solche Daten CountQueuingStrategy verwenden.
Kein hartes Limit: Der Wert ist ein Richtwert. enqueue() bzw. write() nehmen auch darüber hinaus Daten an – Backpressure funktioniert nur, wenn der Code desiredSize bzw. writer.ready beachtet.
Der Konstruktor verlangt highWaterMark zwingend; fehlt er, wird ein TypeError geworfen. Negative Werte oder NaN führen beim Einsatz im Stream zu einem RangeError.
Für Byte-Streams (type: "bytes") darf keine Strategie mit size() übergeben werden, sondern nur { highWaterMark }.
Kompatibilität: in allen aktuellen Browsern verfügbar, in Node.js global ab Version 18 (vorher über stream/web).

Siehe auch

CountQueuingStrategy.highWaterMark HighlightRegistry.size MediaTrackConstraints.frameRate MediaTrackConstraints.height PaymentRequest.payerName