[streams] First draft at tee algorithms, for critique (#302)

First shot at addressing #271. Want to get these up early for review before formalizing them.

- TeeReadableStream: when a consumer pulls on `branch1` or `branch2` (triggering their underlying source's `pull` method), they in turn "pull" from `stream` (using `reader.read()`). Once a chunk has been pulled from `stream`, it gets enqueued in both branches---no matter which branch initiated the pull. This should preserve backpressure and also has the "OOM" property discussed in #271 such that if the consumer for branch1 is slow and the consumer for branch2 is fast, then branch1 ends up with a lot of unconsumed chunks in its queue.
- SpeculativeTeeReadableByteStream is based on the vision outlined in https://github.com/whatwg/streams/issues/294#issuecomment-81557090 where byte streams also have internal queues, which can be used sometimes, whereas other times, a direct call through to the underlying source `read()` will happen. The underlying sources for `branch1` and `branch2` both have `pull` methods like in TeeReadableStream, which might be used if someone goes for an auto-reader on either of them. But they also have `read` methods, such that if someone does e.g. `reader1.read(view1)`, it will call through to `us1.read(view1)` which does two things: (1) `reader.read(view1)`, pulling a chunk from `stream` and using it to fulfill the direct read call; (2) enqueue the view into the queue for `branch2`. Thus, later, if someone does `reader2.read(view2)`, there will be a copy/transfer from `branch2`'s queue into `view2`.

All of these include a `clone` boolean argument, which if present, will result in structured clones happening for anything enqueued. This is important if we envision the two branches being consumed on different threads, e.g. as in #244 or #276.

Would love a review to validate!
You can view, comment on, or merge this pull request online at:

  https://github.com/whatwg/streams/pull/302

-- Commit Summary --

  * First draft at tee algorithms, for critique
  * Remove original TeeReadableStream with broken backpressure

-- File Changes --

    M reference-implementation/lib/readable-stream.js (154)

-- Patch Links --

https://github.com/whatwg/streams/pull/302.patch
https://github.com/whatwg/streams/pull/302.diff

---
Reply to this email directly or view it on GitHub:
https://github.com/whatwg/streams/pull/302