Merge pull request #2 from whatwg/master

Merge from Original Repo

byte-streams-explainer.md

@@ -13,6 +13,22 @@ output. Furthermore, being able to have BYOB readers has benefits in terms of st
 detaches, it can guarantee that one does not write into the same buffer twice, hence avoiding race conditions. BYOB
 readers can reduce the number of times we run garbage collection, because we can reuse buffers.
 
+## API Proposed
+
+*   Constructing a Readable Byte Stream
+    *   <code>new [ReadableStream](https://streams.spec.whatwg.org/#rs-constructor)({ type: "bytes" })</code>
+*   Getting a BYOB reader
+    *   <code>[getReader](https://streams.spec.whatwg.org/#rs-get-reader)({ mode: "byob" })</code>
+*   As part of the implementation, there are 3 main classes that will be added to the Streams API:
+    *   The [ReadableStreamBYOBReader](https://streams.spec.whatwg.org/#byob-reader-class) class
+        *   This class represents a BYOB reader designed to be vended by a `ReadableStream` instance.
+    *   The [ReadableByteStreamController](https://streams.spec.whatwg.org/#rbs-controller-class) class
+        *   This class has methods that allow control of a `ReadableStream`’s state and internal queue. When
+        constructing a `ReadableStream` that is a readable byte stream, the underlying source is given a corresponding
+        `ReadableByteStreamController` instance to manipulate.
+    *   The [ReadableStreamBYOBRequest](https://streams.spec.whatwg.org/#rs-byob-request-class) class
+        *   This class represents a pull-into request in a `ReadableByteStreamController`.
+
 
 ## Examples
 
@@ -86,3 +102,23 @@ function makeReadableByteStream() {
 With this in hand, we can create and use BYOB readers for the returned `ReadableStream`. The adaptation between the
 low-level byte tracking of the underlying byte source shown here, and the higher-level chunk-based consumption of
 a default reader, is all taken care of automatically by the streams implementation.
+
+
+## Goals
+
+*   Provide a way to represent a [ReadableStream](https://streams.spec.whatwg.org/#rs-class) for bytes efficiently.
+*   Avoid races caused by multiple access for the same buffer.
+*   Permit buffer re-use to reduce GC churn.
+
+## Non-Goals
+
+*   Non-binary chunk types will not be supported. They can still use the default type of readable stream.
+*   Shared array buffers will not be supported. Currently, we always detach buffers, but shared array buffers
+cannot be detached.
+
+
+## Alternatives
+
+*   Some of the early versions of the standard had a specific ReadableByteStream constructor which would keep the two
+types of streams completely separate. However, this was unnecessary and we decided to just use separate controllers
+to support byte streams and non-byte streams with the same ReadableStream API to make it simpler.