ReadableStreamBYOBRequest

Hinweis: Diese Funktion ist in Web Workers verfügbar.

Die ReadableStreamBYOBRequest-Schnittstelle der Streams API repräsentiert eine "Pull-Anforderung" für Daten aus einer zugrunde liegenden Quelle, die als Zero-Copy-Übertragung an einen Verbraucher erfolgen wird (ohne die internen Warteschlangen des Streams zu durchlaufen).

ReadableStreamBYOBRequest-Objekte werden im "BYOB-Modus" erstellt, wenn ein Verbraucher Daten anfordert und die interne Warteschlange des Streams leer ist. (Der Stream wird die Anforderung des Verbrauchers direkt auflösen, wenn bereits gepufferte Daten vorhanden sind). Eine zugrunde liegende Byte-Quelle kann auf aktive BYOB-Anforderungen über die byobRequest-Eigenschaft ihres Controllers ReadableByteStreamController.byobRequest zugreifen, die auf null gesetzt wird, wenn keine ausstehende Anforderung vorliegt.

Eine zugrunde liegende Quelle, die den "BYOB-Modus" unterstützt, sollte auf ReadableByteStreamController.byobRequest überprüfen und muss diese verwenden, um Daten zu übertragen, wenn sie vorhanden ist. Wenn Daten von der zugrunde liegenden Quelle eintreffen, während ReadableByteStreamController.byobRequest null ist, können sie mithilfe von ReadableByteStreamController.enqueue() in die Warteschlange gestellt werden. Dies kann passieren, wenn eine zugrunde liegende Push-Quelle neue Daten erhält, während die internen Puffer des Streams nicht leer sind.

Eine zugrunde liegende Quelle verwendet die Anforderung, indem sie Daten in die view des BYOB-Anforderung schreibt und dann respond() aufruft oder indem sie respondWithNewView() aufruft und eine neue Ansicht als Argument übergibt. Beachten Sie, dass die "neue Ansicht" tatsächlich eine Ansicht über den gleichen Puffer wie die ursprüngliche view sein muss, beginnend beim gleichen Offset. Dies kann verwendet werden, um einen kürzeren Puffer zurückzugeben, wenn die zugrunde liegende Quelle nicht in der Lage ist, die gesamte ursprüngliche Ansicht zu füllen.

Beachten Sie, dass ein ReadableByteStreamController nur für zugrunde liegende Quellen erstellt wird, wenn type="bytes" für die Quelle im ReadableStream()-Konstruktor angegeben wird. Der "BYOB-Modus" wird aktiviert, wenn entweder autoAllocateChunkSize im ReadableController()-Konstruktor angegeben wird oder wenn ein ReadableStreamBYOBReader verwendet wird (typischerweise durch den Aufruf von ReadableStream.getReader() mit dem Argument { mode: 'byob' } konstruiert).

Konstruktor

Keiner. ReadableStreamBYOBRequest-Instanzen werden bei Bedarf automatisch von ReadableByteStreamController erstellt.

Instanz-Eigenschaften

ReadableStreamBYOBRequest.view Schreibgeschützt: Gibt die aktuelle Ansicht zurück. Dies ist eine Ansicht auf einen Puffer, der an den Verbraucher übertragen wird, wenn ReadableStreamBYOBRequest.respond() aufgerufen wird.

Instanz-Methoden

ReadableStreamBYOBRequest.respond(): Signalisiert, dass der zugehörige lesbare Bytestream die angegebene Anzahl von Bytes in die aktuelle view geschrieben hat, was dann dazu führt, dass die ausstehende Anforderung des Verbrauchers aufgelöst wird. Beachten Sie, dass nach dem Aufruf dieser Methode die view übertragen und nicht mehr geändert werden kann.
ReadableStreamBYOBRequest.respondWithNewView(): Signalisiert dem zugehörigen lesbaren Bytestream, dass die als Argument übergebene Ansicht an den Verbraucher des lesbaren Bytestreams übertragen werden soll. Diese neue Ansicht muss den gleichen Puffer wie die ursprüngliche view verwenden, am gleichen Offset beginnen und die gleiche Länge oder kürzer sein. Beachten Sie, dass nach dem Aufruf dieser Methode die view übertragen und nicht mehr geändert werden kann.

Beispiele

Der folgende Code stammt aus dem Live-Beispiel unter Verwendung lesbarer Bytestreams > Erstellen eines lesbaren Socket-Push-Bytestreams.

Eine pushende zugrunde liegende Byte-Quelle mit zu übertragenden Daten sollte zuerst überprüfen, dass controller.byobRequest nicht null ist. Eine Eine pullende zugrunde liegende Byte-Quelle würde diese Überprüfung nur benötigen, wenn die automatische Speicherblockzuteilung nicht aktiviert ist und sie mit einem Standardleser verwendet wurde.

if (controller.byobRequest) {
  /* code to transfer data */
}

Es gibt zwei Möglichkeiten, Daten in eine ReadableStreamBYOBRequest zu lesen und dann zu übertragen. Die erste ist, die Daten in die ReadableStreamBYOBRequest.view-Eigenschaft zu schreiben und dann ReadableStreamBYOBRequest.respond() aufzurufen, um die zu übertragende Datenmenge anzugeben. Nach der Operation wird byobRequest.view getrennt, und die Anforderung sollte verworfen werden.

Der untenstehende Code zeigt diesen Fall unter Verwendung einer hypothetischen readInto()-Methode, um Daten in die Ansicht zu kopieren:

const v = controller.byobRequest.view;
bytesRead = socket.readInto(v.buffer, v.byteOffset, v.byteLength);
controller.byobRequest.respond(bytesRead);

Der andere Ansatz besteht darin, ReadableStreamBYOBRequest.respondWithNewView() aufzurufen, dabei eine eigene Ansicht auf dieselben zugrunde liegenden Daten zu übergeben. Beachten Sie, dass dies nur eine andere Möglichkeit ist, den Bereich des tatsächlich übertragenen zugrunde liegenden Puffers/Speichers anzugeben. Die respondWithNewView-Entsprechung zu dem obigen Code wäre:

const v = controller.byobRequest.view;
bytesRead = socket.readInto(v.buffer, v.byteOffset, v.byteLength);
const newView = new Uint8Array(v.buffer, v.byteOffset, bytesRead);
controller.byobRequest.respondWithNewView(newView);

Spezifikationen

Specification
Streams Standard # rs-byob-request-class

Browser-Kompatibilität

BCD tables only load in the browser

Siehe auch

Verwendung lesbarer Bytestreams