ReadableStreamBYOBRequest

Limited availability

This feature is not Baseline because it does not work in some of the most widely-used browsers.

ReadableStreamBYOBRequest はストリーム API のインターフェイスで、は、コンシューマーにゼロコピーで移譲される(ストリーム内部のキューをバイパスする)基盤からのデータの「プルリクエスト」を表します。

ReadableStreamBYOBRequest オブジェクトは、コンシューマーがデータのリクエストを行い、ストリームの内部キューが空である場合に、「BYOBモード」で作成されます。 (ストリームがすでにバッファーされたデータを持っている場合、ストリームはコンシューマーのリクエストを直接解決します。) 基盤のバイトソースは、コントローラの ReadableByteStreamController.byobRequest プロパティを通してアクティブな BYOB リクエストにアクセスすることができます。

「BYOB モード」に対応している基盤ソースは、 ReadableByteStreamController.byobRequest を調べ、存在する場合はそれを使用してデータを移譲しなければなりません。もし ReadableByteStreamController.byobRequest が null の時に基盤からデータが到着した場合、 ReadableByteStreamController.enqueue() を使用してキューに入れることができます。これは、ストリームの内部バッファーが空でないときに、基盤のプッシュソースが新しいデータを受信した場合に発生する可能性があります。

基盤ソースは、 BYOB リクエストの view にデータを書き込んでから respond() を呼び出すか、 respondWithNewView() を呼び出して新しいビューを引数として渡すことで、リクエストを使用します。「新しいビュー」は、実際には元の view と同じバッファー上で、同じオフセットから始まるビューでなければならないことに注意してください。これは、基盤が元のビュー全体を満たすことができない場合に、より短いバッファーを返すために使用することができます。

なお、 ReadableByteStreamController は ReadableStream() コンストラクターで type="bytes" を指定した場合のみ、が基盤ソースに対して作成されます。「BYOB モード」は autoAllocateChunkSize を ReadableController() コンストラクターで指定した場合、または ReadableStreamBYOBReader (ふつうは ReadableStream.getReader() に引数 { mode: 'byob' } 付きで呼び出すことで構築される)を使用した場合にに有効になります。

コンストラクター

なし。 ReadableStreamBYOBRequest インスタンスは ReadableByteStreamController によって必要に応じて作成されます。

インスタンスプロパティ

ReadableStreamBYOBRequest.view 読取専用: 現在のビューを返します。 ReadableStreamBYOBRequest.respond() が呼び出されたときにコンシューマーに移譲されるバッファーに関するビューです。

インスタンスメソッド

ReadableStreamBYOBRequest.respond(): 関連付けられた読み取り可能なバイトストリームに、指定したバイト数が現在の view に書き込まれたことを通知し、コンシューマーからの待機中のリクエストを解決させます。このメソッドが呼び出された後、viewは移譲され、変更できなくなることに注意してください。
ReadableStreamBYOBRequest.respondWithNewView(): 引数として渡された、読み取り可能なバイトストリームのコンシューマーに転送される、関連付けられた読み取り可能なストリームビューへ通知します。この新しいビューは、元の view と同じバッファーを使用し、同じオフセットから始まり、同じ長さかそれ以下でなければなりません。このメソッドが呼び出された後、 view は移譲され、変更できなくなることに注意してください。

例

以下のコードは、読み取り可能なバイトストリーム > 読み取り可能なソケットプッシュバイトストリームの作成のライブ例から引用したものです。

データを移譲するプッシュ基盤バイトソースは、最初に controller.byobRequest が null でないことを調べる必要があります。このチェックが必要なのは、自動チャンク割り当てが有効でなく、既定のリーダーで使用する場合のみです。

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

ReadableStreamBYOBRequest にデータを読み込んでそれを移譲するには 2 つの方法があります。最初の方法は ReadableStreamBYOBRequest.view プロパティにデータを書き込んでから ReadableStreamBYOBRequest.respond() を呼び出して移譲するデータ量を示す方法です。処理後、 byobRequest.view を切り離し、リクエストを破棄すべきです。

下記のコードはこの用途を示すもので、データをビューにコピーするために readInto() メソッドを使用しています。

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

他にも、 ReadableStreamBYOBRequest.respondWithNewView() を呼び出して、同じ基盤バッキングデータに自分自身でビューを渡す、という手法があります。これは単に、実際に移譲される基盤バッファー/メモリーバッキングの範囲を指定する別の方法であることに注意してください。上のコードと同等の respondWithNewView は次のようになります。

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);