CountQueuingStrategy.highWaterMark — Eigenschaft · JavaScript-Referenz

Signatur

CountQueuingStrategy.highWaterMark

Beschreibung

Die Eigenschaft highWaterMark einer CountQueuingStrategy gibt den Schwellenwert zurück, der beim Erzeugen der Strategie über new CountQueuingStrategy({ highWaterMark }) festgelegt wurde. Bei dieser Strategie zählt jeder Block genau als 1, egal wie groß er ist. Der Wert entspricht also der Anzahl an Blöcken, die in der internen Warteschlange liegen dürfen.

Streams berechnen damit ihren desiredSize: highWaterMark - Anzahl der Blöcke in der Warteschlange. Wird dieser Wert 0 oder negativ, entsteht Gegendruck (engl. backpressure). Ein ReadableStream ruft pull() dann nicht mehr auf. Bei einem WritableStream wird writer.ready erst wieder erfüllt, wenn die Warteschlange Platz hat.

Die Eigenschaft ist nützlich, um zu protokollieren oder zu prüfen, mit welcher Pufferkonfiguration ein Stream arbeitet. Das ist praktisch, wenn Strategien zentral erzeugt und an mehrere Streams weitergegeben werden. Ändern lässt sich der Wert nachträglich nicht. Wer einen anderen Schwellenwert braucht, legt eine neue Strategie an.

Rückgabewert

Typ

number

Beschreibung

Die beim Konstruktor übergebene Anzahl von Blöcken (nicht negativ, auch 0 oder Infinity möglich).

Beispiele

Schwellenwert einer Strategie auslesen

const strategy = new CountQueuingStrategy({ highWaterMark: 4 });
console.log(strategy.highWaterMark);

// Schreibgeschützt: Zuweisung wird ignoriert (im strict mode TypeError)
strategy.highWaterMark = 10;
console.log(strategy.highWaterMark);

4 4

Gegendruck in einem ReadableStream beobachten

const strategy = new CountQueuingStrategy({ highWaterMark: 3 });

const stream = new ReadableStream({
  start(controller) {
    for (let i = 1; i <= 5; i++) {
      controller.enqueue(`Block ${i}`);
      console.log(`enqueue ${i}, desiredSize = ${controller.desiredSize}`);
    }
  }
}, strategy);

console.log('Limit:', strategy.highWaterMark);

enqueue 1, desiredSize = 2 enqueue 2, desiredSize = 1 enqueue 3, desiredSize = 0 enqueue 4, desiredSize = -1 enqueue 5, desiredSize = -2 Limit: 3

WritableStream mit Gegendruck beschreiben

const strategy = new CountQueuingStrategy({ highWaterMark: 2 });

const writable = new WritableStream({
  async write(chunk) {
    // langsame Senke simulieren
    await new Promise((r) => setTimeout(r, 100));
    console.log('geschrieben:', chunk);
  }
}, strategy);

const writeAll = async (items) => {
  const writer = writable.getWriter();
  console.log(`Puffer: ${strategy.highWaterMark} Blöcke`);
  for (const item of items) {
    await writer.ready; // wartet, solange Gegendruck besteht
    writer.write(item);
  }
  await writer.close();
};

writeAll(['a', 'b', 'c', 'd']);

Puffer: 2 Blöcke geschrieben: a geschrieben: b geschrieben: c geschrieben: d

// Wichtig · Fallstricke

Nur Anzahl, nicht Größe: Ein Block von 1 Byte zählt genauso viel wie einer mit 10 MB. Um nach Bytes zu begrenzen, verwende ByteLengthQueuingStrategy.
Keine harte Grenze: enqueue() und write() funktionieren auch oberhalb des Schwellenwerts. highWaterMark gibt nur ein Signal über desiredSize bzw. writer.ready. Die Quelle muss dieses Signal selbst beachten.
Negative Werte oder NaN beim Konstruktor führen spätestens beim Erzeugen des Streams zu einem RangeError. Der Schlüssel highWaterMark muss angegeben werden, sonst wirft der Konstruktor einen TypeError.
Die Eigenschaft ist ein Getter auf CountQueuingStrategy.prototype. Zuweisungen haben keine Wirkung.
Kompatibilität: in allen modernen Browsern, in Web Workern und in Node.js (global ab v18, vorher über stream/web) verfügbar.

Siehe auch

ByteLengthQueuingStrategy.highWaterMark ChapterInformation.artwork NodeIterator.filter PointerEvent.height PointerEvent.isPrimary