[streams] Change the model for ReadableStream to have async read() (#288)

This replaces the dual ready + read() approach previously, which was derived from the epoll(7) + read(2) paradigm. In #253, we discussed about how the ready + read() model causes a conflict with the semantics we want for byte streams. Briefly, because some byte streams will demand to know the size of the buffer they must fill before doing any I/O (the fread(3) model), the readInto(arrayBuffer, ...) method for byte streams must be asynchronous. If such byte streams are then to conform to the readable stream interface, with a read() method derived from their readInto() method, then read() must also be async, across all readable streams.

This is a slight usability upgrade for consumers, in some cases. However, it potentially costs more microtasks when multiple chunks of data would be available synchronously.

In the process of updating the tests to reflect async read, they were given a number of small unrelated tweaks (e.g. to wording, or to eliminate some setTimeout(,0)s).

TODO:
- This commit eliminates ExclusiveStreamReader, but this was done in error based on mistaken assumptions. It will be reversed.
- Almost none of the spec is updated. Examples.md was updated and the examples in the spec were updated, but none of the algorithms or non-normative notes.

----

Getting this up there largely so that people can get a sense of how much of a change this is. The changes worth looking at are in lib/readable-stream.js, lib/readable-stream-abstract-ops.js, Examples.md, and index.bs. The rest are tests.

I thought we could get rid of ExclusiveStreamReader since people would be able to get exclusive access to the chunks by just reading them as soon as they are available. However sometimes you want to be able to prevent interference from a stream, but you also want to let chunks accumulate in the internal buffer instead of reading them immediately---for backpressure purposes. So we still need a lock to prevent other consumers from snatching them from you.

I think adding back ExclusiveStreamReader will actually reduce the diff pretty significantly so this is not that big of a change to the non-test files. That is heartening to me. So feel free to put off reviewing for another day. I wanted to get this up here though to show that I am working on the problem and that's why I haven't had much time to review e.g. OperationStream or respond to comments in #253. I will do my best to catch up tomorrow and maybe a bit over the weekend.
You can view, comment on, or merge this pull request online at:

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

-- Commit Summary --

  * Change the model for ReadableStream to have async read()

-- File Changes --

    M Examples.md (48)
    M index.bs (43)
    D reference-implementation/lib/exclusive-stream-reader.js (148)
    M reference-implementation/lib/readable-stream-abstract-ops.js (157)
    M reference-implementation/lib/readable-stream.js (116)
    M reference-implementation/lib/transform-stream.js (4)
    M reference-implementation/run-tests.js (12)
    M reference-implementation/test/bad-underlying-sources.js (135)
    M reference-implementation/test/brand-checks.js (87)
    M reference-implementation/test/count-queuing-strategy.js (120)
    D reference-implementation/test/exclusive-stream-reader.js (531)
    M reference-implementation/test/pipe-through.js (3)
    M reference-implementation/test/pipe-to.js (520)
    M reference-implementation/test/readable-stream-cancel.js (239)
    M reference-implementation/test/readable-stream.js (875)
    M reference-implementation/test/transform-stream-errors.js (41)
    M reference-implementation/test/transform-stream.js (275)
    M reference-implementation/test/utils/random-push-source.js (23)
    M reference-implementation/test/utils/readable-stream-to-array.js (18)

-- Patch Links --

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

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