From 3d4467f5c9344d8449a5bc4acec8651f949ad281 Mon Sep 17 00:00:00 2001 From: Yonathan Randolph Date: Mon, 30 May 2022 19:27:32 -0700 Subject: [PATCH] Clarify that tee backpressures to the faster consumed branch --- index.bs | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/index.bs b/index.bs index 2a9f693f0..e47d5dcee 100644 --- a/index.bs +++ b/index.bs @@ -164,7 +164,8 @@ execute any cancellation mechanism of the [=underlying source=]. Consumers can also tee a readable stream using its {{ReadableStream/tee()}} method. This will [=locked to a reader|lock=] the stream, making it no longer directly usable; however, it will create two new streams, called branches, which can be consumed independently. +readable stream tee">branches, which can be consumed independently or in sequence, +so long as the unconsumed data at the branch that is consumed more slowly fits in memory. For streams representing bytes, an extended version of the [=readable stream=] is provided to handle bytes efficiently, in particular by minimizing copies. The [=underlying source=] for such a readable @@ -257,9 +258,10 @@ sink=], which gets updated as the ultimate sink finishes writing [=chunks=]. The {{ReadableStream/pipeTo()}} method used to construct the chain automatically ensures this information propagates back through the [=pipe chain=]. -When [=tee a readable stream|teeing=] a readable stream, the [=backpressure=] signals from its two -[=branches of a readable stream tee|branches=] will aggregate, such that if neither branch is read +When [=tee a readable stream|teeing=] a readable stream, the [=backpressure=] signals from the +faster [=branches of a readable stream tee|branch=] will propagate. If neither branch is read from, a backpressure signal will be sent to the [=underlying source=] of the original stream. +Unread data will accumulate without limit onto the buffer of the slower consumed branch. Piping [=locks=] the readable and writable streams, preventing them from being manipulated for the duration of the pipe operation. This allows the implementation to perform important optimizations, @@ -960,11 +962,13 @@ option. If {{UnderlyingSource/type}} is set to undefined (including via omission 1. Return ? [$ReadableStreamTee$]([=this=], false).
- Teeing a stream is most useful when you wish to let two independent consumers read from the stream - in parallel, perhaps even at different speeds. For example, given a writable stream + Teeing a stream is most useful when you wish to let two consumers read from the stream + in parallel or in sequence, perhaps even at different speeds, + so long as the difference in consumption fits in memory. + For example, given a writable stream cacheEntry representing an on-disk file, and another writable stream httpRequestBody representing an upload to a remote server, you could pipe the same - readable stream to both destinations at once: + readable stream to both destinations at once assuming that the data fits in memory: const [forLocal, forRemote] = readableStream.tee();