ReadableStreamBYOBReader: read() Methode

Hinweis: Dieses Feature ist verfügbar in Web Workers.

Die read() Methode der ReadableStreamBYOBReader-Schnittstelle wird verwendet, um Daten in eine Ansicht auf einem vom Benutzer bereitgestellten Puffer aus einem zugehörigen lesbaren Byte-Stream zu lesen. Eine Anfrage nach Daten wird aus den internen Warteschlangen des Streams bedient, falls dort Daten vorhanden sind. Wenn die Stream-Warteschlangen leer sind, kann die Anfrage als Zero-Copy-Transfer von der zugrunde liegenden Byte-Quelle bereitgestellt werden.

Die Methode akzeptiert als Argument eine Ansicht auf einen Puffer, in den die bereitgestellten Daten gelesen werden sollen, und gibt ein Promise zurück. Das Promise erfüllt sich mit einem Objekt, das die Eigenschaften value und done enthält, wenn Daten verfügbar werden oder wenn der Stream abgebrochen wird. Wenn der Stream fehlerhaft ist, wird das Promise mit dem entsprechenden Fehlerobjekt zurückgewiesen.

Wenn ein Datenblock bereitgestellt wird, wird die Eigenschaft value eine neue Ansicht enthalten. Dies wird eine Ansicht über den gleichen Puffer/Rückwärtsspeicher (und vom gleichen Typ) wie die ursprüngliche view sein, die an die read() Methode übergeben wurde, jetzt gefüllt mit dem neuen Datenblock. Beachten Sie, dass die ursprüngliche view, die der Methode übergeben wurde, abgetrennt und nicht mehr verwendbar ist, sobald das Promise erfüllt ist. Das Promise wird mit einem value: undefined erfüllt, wenn der Stream abgebrochen wurde. In diesem Fall wird der Rückwärtsspeicherbereich von view verworfen und nicht an den Aufrufer zurückgegeben (alle zuvor gelesenen Daten im Puffer der Ansicht gehen verloren).

Die Eigenschaft done gibt an, ob weitere Daten erwartet werden. Der Wert wird auf true gesetzt, wenn der Stream geschlossen oder abgebrochen ist, und ansonsten auf false.

Die Methode hat auch ein optionales options.min Argument, das verwendet werden kann, um die minimale Anzahl von Elementen zu spezifizieren, die verfügbar sein müssen, bevor das Promise erfüllt wird, während der Stream aktiv ist. Die in der value Eigenschaft zurückgegebene Ansicht wird immer mindestens diese Anzahl von Elementen haben, außer wenn der Stream geschlossen ist.

Syntax

js
read(view)
read(view, options)

Parameter

view

Die Ansicht, in die die Daten gelesen werden sollen.

options Optional

Die Optionen sind wie folgt:

min

Die minimale Anzahl von Elementen, die gelesen werden sollen, bevor das Promise erfüllt wird, solange der Stream aktiv ist. Wenn nicht angegeben, wird das Promise mit mindestens einem Element aufgelöst, bis zur maximalen Größe der Ansicht. Diese Zahl darf nicht größer sein als die Ansicht, in die gelesen wird.

Rückgabewert

Ein Promise, das sich erfüllt/abweist mit einem Ergebnis abhängig vom Zustand des Streams.

Folgendes ist möglich:

  • Wenn ein Datenblock verfügbar ist und der Stream noch aktiv ist, erfüllt sich das Promise mit einem Objekt der Form:

    js
    { value: theChunk, done: false }
    

    theChunk ist eine Ansicht, die die neuen Daten enthält. Dies ist eine Ansicht des gleichen Typs und über den gleichen Rückwärtsspeicher wie die an die read() Methode übergebene view. Die ursprüngliche view wird abgetrennt und ist nicht mehr verwendbar.

  • Wenn der Stream geschlossen ist, erfüllt sich das Promise mit einem Objekt der Form (wobei theChunk die gleichen Eigenschaften wie oben hat):

    js
    { value: theChunk, done: true }
    
  • Wenn der Stream abgebrochen ist, erfüllt sich das Promise mit einem Objekt der Form:

    js
    { value: undefined, done: true }
    

    In diesem Fall wird der Rückwärtsspeicher verworfen.

  • Wenn der Stream einen Fehler wirft, wird das Promise mit dem entsprechenden Fehler abgelehnt.

Ausnahmen

TypeError

Das Quellobjekt ist kein ReadableStreamBYOBReader, der Stream hat keinen Eigentümer, die Ansicht ist kein Objekt oder wurde abgetrennt, die Länge der Ansicht ist 0, options.min ist 0, oder ReadableStreamBYOBReader.releaseLock() wird aufgerufen (wenn eine ausstehende Leseanforderung vorliegt).

RangeError

Der Wert von options.min ist größer als die in die geschrieben werdende Ansicht.

Beispiele

Lesen in eine Ansicht

Der hier gezeigte Beispielcode stammt aus den Live-Beispielen in Using readable byte streams.

Zuerst erstellen wir den Reader mit ReadableStream.getReader() auf dem Stream und geben mode: "byob" im Optionsparameter an. Wir müssen auch ein ArrayBuffer erstellen, das der "Rückwärtsspeicher" der Ansichten ist, in die wir schreiben werden.

js
const reader = stream.getReader({ mode: "byob" });
let buffer = new ArrayBuffer(4000);

Eine Funktion, die den Reader verwendet, ist unten gezeigt. Diese ruft die read() Methode rekursiv auf, um Daten in den Puffer zu lesen. Die Methode akzeptiert ein Uint8Array typisiertes Array, das eine Ansicht über den Teil des ursprünglichen Array-Puffers ist, der noch nicht geschrieben wurde. Die Parameter der Ansicht werden aus den in früheren Aufrufen empfangenen Daten berechnet, die einen Offset in den ursprünglichen Array-Puffer definieren.

js
readStream(reader);

function readStream(reader) {
  let bytesReceived = 0;
  let offset = 0;

  while (offset < buffer.byteLength) {
    // read() returns a promise that fulfills when a value has been received
    reader
      .read(new Uint8Array(buffer, offset, buffer.byteLength - offset))
      .then(function processBytes({ done, value }) {
        // Result objects contain two properties:
        // done  - true if the stream has already given all its data.
        // value - some data. 'undefined' if the reader is canceled.

        if (done) {
          // There is no more data in the stream
          return;
        }

        buffer = value.buffer;
        offset += value.byteLength;
        bytesReceived += value.byteLength;

        // Read some more, and call this function again
        // Note that here we create a new view over the original buffer.
        return reader
          .read(new Uint8Array(buffer, offset, buffer.byteLength - offset))
          .then(processBytes);
      });
  }
}

Wenn keine weiteren Daten im Stream vorhanden sind, erfüllt sich die read() Methode mit einem Objekt, dessen Eigenschaft done auf true gesetzt ist, und die Funktion kehrt zurück.

Lesen einer minimalen Anzahl von Elementen

Dieses Beispiel ist fast genau dasselbe wie das vorherige, außer dass wir den Code geändert haben, um bei jeder Iteration mindestens 101 Elemente zu lesen.

Wir haben es auch in ein Live-Beispiel umgewandelt. Beachten Sie, dass der größte Teil des Codes für das Beispiel nicht relevant ist und daher ausgeblendet ist. Für mehr Informationen siehe Using readable byte streams.

JavaScript

js
function readStream(reader) {
  let bytesReceived = 0;
  let offset = 0;

  while (offset < buffer.byteLength) {
    // read() returns a promise that resolves when a value has been received
    reader
      .read(new Uint8Array(buffer, offset, buffer.byteLength - offset), {
        min: 101,
      })
      .then(async function processText({ done, value }) {
        // Result objects contain two properties:
        // done  - true if the stream has already given all its data.
        // value - some data. Always undefined when done is true.

        if (done) {
          logConsumer(
            `readStream() complete. Read ${value.byteLength} bytes (total: ${bytesReceived})`,
          );
          return;
        }

        buffer = value.buffer;
        offset += value.byteLength;
        bytesReceived += value.byteLength;

        //logConsumer(`Read ${bytesReceived} bytes: ${value}`);
        logConsumer(`Read ${value.byteLength} bytes (total: ${bytesReceived})`);
        result += value;

        // Read some more, and call this function again
        return reader
          .read(new Uint8Array(buffer, offset, buffer.byteLength - offset), {
            min: 101,
          })
          .then(processText);
      });
  }
}

Ergebnis

Das Logging von der zugrundeliegenden Push-Quelle (links) und dem Verbraucher (rechts) wird unten gezeigt. Beachten Sie, dass, wenn der Browser das options.min Argument unterstützt, jedes Mal mindestens 101 Elemente zurückgegeben werden (und oft mehr), außer wenn der Stream schließt.

Spezifikationen

Specification
Streams Standard
# ref-for-byob-reader-read③

Browser-Kompatibilität

BCD tables only load in the browser

Siehe auch