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
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 dieread()
Methode übergebeneview
. Die ursprünglicheview
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, oderReadableStreamBYOBReader.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.
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.
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
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
ReadableStreamBYOBReader()
Konstruktor- Using readable byte stream