--- a/preview.html Thu Nov 14 21:00:09 2013 +0900
+++ b/preview.html Sat Nov 23 21:48:46 2013 -0800
@@ -167,44 +167,43 @@
<p>
Web applications should have the ability to acquire, manipulate and pass data in a wide variety of forms, including as a sequence of data made available over time.
- This specification defines the basic representation for byte streams, and programmatic ways to read and write byte streams and errors raised on those operations.
+ This specification defines the basic representation for byte streams, and programmatic ways to read and write streams of data and errors raised on those operations.
</p>
<p>
- The <a>WritableByteStream</a> interface defines a general protocol for <a href="#consumers">data consuming APIs</a> to communicate with data producing code.
- Data producing code writes data to the data sink inside a data consuming API using:
+ The <a>WritableByteStream</a> interface defines a general protocol for <a href="#consumers">data consuming APIs</a> to communicate with data producing code. In these cases, the data consuming API, such as a decoder, provides a <a>WritableByteStream</a> for other applications to write to, enabling the decoder to begin decoding data as it becomes available. The data is written to the data sink inside a data consuming API using:
<ul>
- <li><code>write()</code> method for writing bytes to the data sink as a <a>ArrayBufferView</a>, <a>DOMString</a> or <a>Blob</a></li>
- <li><code>waitForWritable()</code> method for waiting for the consumer requests for bytes and then producing and writing data</li>
+ <li>The <code>write()</code> method for writing bytes to the data sink as a <a>ArrayBufferView</a>, <a>DOMString</a> or <a>Blob</a></li>
+ <li>The <code>waitForWritable()</code> method for allowing a data-producer to write to the stream only when a data-consumer specifies it is now available to consume more data. This is useful for cases where an app may want to avoid backpressure and filling the internal buffer.</li>
</ul>
Actual transfer of bytes to the data sink may happen either synchronously or asynchronously.
- <a>WritableByteStream</a> hides details of actual communication with the data sink while allowing for efficient transfer of bytes.
+ <a>WritableByteStream</a> hides the details of actual communication with the data sink while allowing for an efficient transfer of bytes.
</p>
<p>
The <a>ReadableByteStream</a> interface defines a general protocol for <a href="#producers">data producing APIs</a> to communicate with data consuming code.
- This interface represents possibly infinite byte streams which are obtained over time and read once.
+ This interface represents the potential for an infinite amount of bytes which are obtained over time and read once.
Data consuming code reads data from the data source inside a data producing API using:
<ul>
- <li><code>read()</code> and <code>readExact()</code> method for reading bytes from the data source as a <a>ArrayBufferView</a>, <a>DOMString</a> or <a>Blob</a></li>
- <li><code>pullAmount</code> attribute to pace data retrieval from the data source</li>
- <li><code>pipe()</code> method for transferring data in bulk from the data source to the data sink of another <a>WritableByteStream</a></li>
+ <li>The <code>read()</code> and <code>readExact()</code> methods for reading bytes from the data source as a <a>ArrayBufferView</a>, <a>DOMString</a> or <a>Blob</a></li>
+ <li>The <code>pullAmount</code> attribute to pace data retrieval from the data source</li>
+ <li>The <code>pipe()</code> method for transferring data in bulk from the data source into the data sink of a <a>WritableByteStream</a> from another API</li>
</ul>
Actual transfer of bytes from the data source may happen either synchronously or asynchronously.
- <a>ReadableByteStream</a> hides details of actual communication with the data source while allowing for efficient transfer of bytes.
+ <a>ReadableByteStream</a> hides the details of actual communication with the data source while allowing for an efficient transfer of bytes.
</p>
<p>
- By the combination of the following features, this interface suite responds to various needs of byte stream handling.
+ With the combination of the following features, this interface suite responds to various simple and complex needs of byte stream handling.
<ul>
<li>Delayed notification of completion by using <a>Promise</a>s</li>
- <li>Explicit back pressure by propagating room for consumption back to producers</li>
+ <li>Explicit back pressure management by propagating room for consumption back to producers</li>
<li><a>WritableByteStream</a> always accepts incoming data synchronously</li>
</ul>
</p>
<p>
- The <a>ByteStream</a> is a simple implementation of both <a>WritableByteStream</a> and <a>ReadableByteStream</a> interface.
+ The <a>ByteStream</a> is a simple implementation of both the <a>WritableByteStream</a> and <a>ReadableByteStream</a> interface.
A ByteStream has a single queue of bytes and it works as a data sink for the WritableByteStream interface and a data source for the ReadableByteStream interface.
</p>
@@ -253,7 +252,7 @@
<p>
In the example below, different code blocks handle progress, error, and success conditions.
The example below demonstrates how to obtain a <a>ReadableByteStream</a> from <a>XMLHttpRequest</a> to begin playing a large video in <code>readystate</code> LOADING.
- The example takes the <a>ReadableByteStream</a> from a <a href="#producers">producer</a>, <a>XMLHttpRequest</a>, and gives to a <a href="#consumers">consumer</a>, the video tag.
+ The example takes the <a>ReadableByteStream</a> from a <a href="#producers">producer</a>, <a>XMLHttpRequest</a>, and gives it to a <a href="#consumers">consumer</a>, the video tag.
</p>
<pre class="example">function handler() {
@@ -274,7 +273,7 @@
<p>
In addition to the <a>ReadableByteStream</a> interface, this specification introduces an interface called <a>WritableByteStream</a> for data consuming APIs.
- The <a>WritableByteStream</a> interface provides a <code>write()</code> method which allows applications to write data to the data consuming API as listed in <a href="#consumers">consumer</a>.
+ The <a>WritableByteStream</a> interface provides a <code>write()</code> method which allows applications to write data to a <a href="#consumers">data consuming API</a>.
<code>write()</code> supports writing bytes represented as a <a>Blob</a>, <a>ArrayBuffer</a>, or <a>DOMString</a>.
</p>
<p>
@@ -303,13 +302,13 @@
}
}
-var streamURL = URL.createObjectURL(theStream);
+var streamURL = URL.createObjectURL(stream);
document.getElementById('audioTag').src = streamURL;
writeData();</pre>
<p>
- If you have a producer code which should do work only when pulled, <code>waitForWritable()</code> should be used to wait for pull event.
+ An producer can also do work only when pulled by using <code>waitForWritable()</code>, which will inform the producer when to produce data. This is useful when high-performance is necessary.
</p>
<pre class="example">function poll() {
@@ -328,17 +327,17 @@
<h2>Data source model</h2>
<p>
- Interfaces introduced in the later sections provide simple and convenient way to consume data.
- They connect a raw sequence of bytes to with JavaScript world using Promises and method invocations.
- Before describing them, here, we'll describe the model of data source which produces bytes to be consumed via the <a>ReadableByteStream</a> interface instances.
+ Interfaces introduced in the later sections provide simple and convenient ways to consume data.
+ They connect raw sequences of bytes using Promises and method invocations.
+ Before describing them, we'll describe the model for a data source, which produces the bytes to be consumed via the <a>ReadableByteStream</a> interface instances. The data source model is not directly surfaced in the API, and is described here to provide details on how internal operations such as <a href="#widl-ReadableByteStream-fork-ReadableByteStream">fork()</a> can be handled.
</p>
<p>
A <dfn>data source</dfn> from which <a>ReadableByteStream</a> retrieves bytes can be anything that:
<ol>
- <li>Produce bytes</li>
+ <li>Produces bytes</li>
<li>
- Receives retrieval request for generation of bytes from <a>ReadableByteStream</a> and reply to it with newly produced bytes.
+ Receives retrieval requests for generation of bytes from a <a>ReadableByteStream</a> and replies to it with the newly produced bytes.
Interpretation of the request is up to data sources.
Data sources may respond to retrieval requests with data larger than requested.
Data sources may produce bytes and send to <a>ReadableByteStream</a> unsolicitedly without receiving any retrieval request.
@@ -367,7 +366,7 @@
<h2>Data sink model</h2>
<p>
- A <dfn>data sink</dfn> to which <a>WritableByteStream</a> interface writes bytes can be anything that:
+ A <dfn>datasink</dfn> to which the <a>WritableByteStream</a> interface writes bytes can be anything that:
<ol>
<li>Accepts bytes</li>
<li>
@@ -383,26 +382,26 @@
<h2>WritableByteStream interface</h2>
<p>
- The WritableByteStream interface defines a protocol for APIs that consume byte stream which includes:
+ The WritableByteStream interface defines a protocol for APIs which consume byte streams. The protocol includes:
<ol>
- <li>How to receive byte stream</li>
+ <li>How to receive the byte stream</li>
<li>How to notify the writer of completion of writing</li>
- <li>How much data it can accept currently</li>
+ <li>How to notify the writer how much data can be currently accepted</li>
</ol>
By returning a <a>Promise</a> and delaying fulfillment of it, the WritableByteStream realizes flow control.
</p>
<p>
- A WritableByteStream has an associated <a>data sink</a> <dfn>dataSink</dfn> and it notifies the WritableByteStream of the number of bytes the data sink can newly accept.
+ A WritableByteStream has an associated <a>datasink</a>, which notifies the WritableByteStream of the number of bytes the data sink can newly accept.
</p>
<p>
- An associated integer variable <dfn>bytesRequested</dfn> holds the number of bytes can be written to the <a>dataSink</a>.
+ An associated integer variable <dfn>bytesRequested</dfn> holds the number of bytes which can be written to the <a>dataSink</a>.
This variable is initialized to 0 on construction.
</p>
<p>
- An associated <a>Promise</a> <dfn>waitPromise</dfn> is used by <code>waitForWritable()</code> method.
+ An associated <a>Promise</a> <dfn>waitPromise</dfn> is used by the <code>waitForWritable()</code> method.
This variable is initialized to null on construction.
</p>
@@ -519,7 +518,7 @@
</p>
<p>
- If <var>data</var> argument is an <a>ArrayBufferView</a>, modification made on the ArrayBufferView's contents between <code>write()</code> method call and fulfill of the returned Promise may affect the data written to <a>dataSink</a>.
+ If <var>data</var> argument is an <a>ArrayBufferView</a>, modifications made on the ArrayBufferView's contents between <code>write()</code> method call and fulfill of the returned Promise may affect the data written to <a>dataSink</a>.
</p>
<dl class="parameters">
@@ -531,7 +530,7 @@
<dt>Promise&lt;unsigned long long> waitForWritable()</dt>
<dd>
<p>
- This method waits until the WritableByteStream becomes able to accept any non-zero amount of data.
+ This method waits until the WritableByteStream bcomes able to accept any non-zero amount of data.
The returned <a>Promise</a> will be fulfilled with the number of bytes the WritableByteStream can accept.
</p>
@@ -560,7 +559,7 @@
<dd>
<p>
This method tells the WritableByteStream that no more data will be written to it.
- Once writeClose() has been called on a WritableByteStream, any more method call must not be made on the WritableByteStream.
+ Once writeClose() has been called on a WritableByteStream, no further method calls can be made on the WritableByteStream.
</p>
<p>
@@ -575,11 +574,11 @@
<h2>ReadableByteStream interface</h2>
<p>
- The ReadableByteStream interface defines a protocol for APIs that produce byte stream which includes:
+ The ReadableByteStream interface defines a protocol for APIs which produce a byte stream. This protocol includes:
<ol>
<li>How to receive a read request from the reader and output bytes</li>
- <li>How to transfer bulk data to other <a>WritableByteStream</a> (by <code>pipe()</code> method)</li>
- <li>How to mirror data to multiple destination code or <a>WritableByteStream</a>s (by <code>fork()</code>)</li>
+ <li>How to transfer data in bulk to another <a>WritableByteStream</a> (by using the <code>pipe()</code> method)</li>
+ <li>How to mirror data to multiple destinations or <a>WritableByteStream</a>s (by using the <code>fork()</code>)</li>
</ol>
By returning a <a>Promise</a> and delaying fulfillment of it, the ReadableByteStream realizes asynchronous data consumption.
@@ -595,29 +594,33 @@
The data source model is explained in <a href="#h2_data_source">this section</a>.
A data source can be shared by multiple ReadableByteStream instances when <code>fork()</code> is used.
A ReadableByteStream is registered with a data source on construction and given a reader ID.
- <a>dataSource</a> of the ReadableByteStream is set to refer to the data source and <dfn>readerId</dfn> of the ReadableByteStream is set to the reader ID.
+ The <a>dataSource</a> of a ReadableByteStream refers to its data source, and <dfn>readerId</dfn> of a ReadableByteStream refers to its reader ID.
</p>
<p>
- An associated flag <dfn>readPending</dfn> prevents multiple read operations from being run.
+ A ReadableByteStream has the following internal mechanisms:
+ </p>
+
+ <p>
+ An associated flag <dfn>readPending</dfn> which prevents multiple read operations from being run.
This flag is set to false on construction.
</p>
<p>
- An associated integer variable <dfn>readExactPullAmount</dfn> temporarily overrides <a href="#widl-ReadableByteStream-pullAmount">pullAmount</a> if necessary for <code>readExact()</code> method call.
+ An associated integer variable <dfn>readExactPullAmount</dfn> which temporarily overrides <a href="#widl-ReadableByteStream-pullAmount">pullAmount</a> if necessary for <code>readExact()</code> method call.
This variable is initialized to 0 on construction.
</p>
<p>
- An associated integer variable <dfn>pipePullAmount</dfn> temporarily overrides <a href="#widl-ReadableByteStream-pullAmount">pullAmount</a> if necessary for <code>pipe()</code> method call.
+ An associated integer variable <dfn>pipePullAmount</dfn> which temporarily overrides <a href="#widl-ReadableByteStream-pullAmount">pullAmount</a> if necessary for <code>pipe()</code> method call.
This variable is initialized to 0 on construction.
</p>
<p>
- An associated integer variable <dfn>bytesBeingRetrieved</dfn> holds the number of bytes being retrieved from <a>dataSource</a>.
+ An associated integer variable <dfn>bytesBeingRetrieved</dfn> which holds the number of bytes being retrieved from <a>dataSource</a>.
This variable is initialized to 0 on construction.
</p>
<p>
- An associated integer variable <dfn>bytesBeingOutput</dfn> holds the number of bytes consumed on the last read operation.
+ An associated integer variable <dfn>bytesBeingOutput</dfn> which holds the number of bytes consumed on the last read operation.
This variable is initialized to 0 on construction.
<section class="note">
@@ -626,7 +629,7 @@
</p>
<p>
- An associated queue <dfn>retrievedDataBuffer</dfn> holds bytes retrieved from <a>dataSource</a>.
+ An associated queue <dfn>retrievedDataBuffer</dfn> which holds bytes retrieved from <a>dataSource</a>.
This queue is initialized to an empty queue on construction.
<section class="note">
Retrieved bytes can be queued in <a>retrievedDataBuffer</a> in any form.
@@ -636,7 +639,7 @@
</p>
<p>
- An associated flag <dfn>eofReached</dfn> indicates that the EOF is received from <a>dataSource</a>.
+ An associated flag <dfn>eofReached</dfn> which indicates that the EOF is received from <a>dataSource</a>.
</p>
<p>
@@ -671,16 +674,16 @@
<dd>
Returns the ASCII-encoded string in lower case representing the media type of the <code>Stream</code>,
expressed as an RFC2046 MIME type [[!RFC2046]].
- Conforming user agents SHOULD return the MIME type of the <code>Stream</code>, if it is known.
- If conforming user agents cannot determine the media type of the <code>Stream</code>, they MUST return the empty string.
+ Conforming user agents SHOULD return the MIME type of the <code>ReadableByteStream</code>, if it is known.
+ If conforming user agents cannot determine the media type of the <code>ReadableByteStream</code>, they MUST return the empty string.
A string is a valid MIME type if it matches the media-type token defined in section 3.7 "Media Types" of RFC 2616 [[!HTTP11]].
</dd>
<dt>attribute ByteStreamReadType readType</dt>
<dd>
<p>
- Specifies as what type data will be read from the ReadableByteStream by a <code>read()</code> and <code>readExact()</code> method call.
- This attribute can be set to any of <a>ByteStreamReadType</a> items.
+ Specifies what data type will be returned by a <code>read()</code> and <code>readExact()</code> method call.
+ This attribute can be set to any of the supported types in <a>ByteStreamReadType</a>.
The default value for this attribute is "<code>arraybuffer</code>".
</p>
</dd>
@@ -700,7 +703,7 @@
<dt>attribute unsigned long long pullAmount</dt>
<dd>
<p>
- This attribute is tells ReadableByteStream a hint how many bytes the reader can consume currently.
+ This attribute provides ReadableByteStream with a hint of how many bytes the reader can consume currently.
Each implementation of ReadableByteStream must initialize the value of pullAmount on construction.
</p>
@@ -709,10 +712,10 @@
</p>
<section class="note">
- This flow control functionality is provided as a separated attribute rather than as an argument of the read() method based on assumption that most people don't change the value so frequently.
+ This flow control functionality is provided as a separated attribute rather than as an argument of the read() method based on the assumption that this value is not changed frequently.
</section>
<section class="note">
- It's possible bytes more than pullAmount value is received by <code>read()</code>.
+ It's possible that the number of bytes received by <code>read()</code> is more than the pullAmount value.
</section>
</dd>
@@ -721,7 +724,7 @@
<p>
This method reads data from the ReadableByteStream.
The returned Promise is fulfilled only when bytes of the specified size is read or the EOF is reached.
- The size of data read by this method is exactly the same as the specified size unless there are bytes less than the specified size until the EOF.
+ The size of data read by this method is exactly the same as the specified size unless an EOF was reached, in which case there will be less bytes, which were the remaining bytes until the EOF.
</p>
<p>
@@ -783,7 +786,7 @@
This method is useful if
<ol>
<li>You don't want to get notified of new data unless bytes of the specified number become available</li>
- <li>You don't want to get result fragmented into multiple objects</li>
+ <li>You don't want to get your data fragmented into multiple parts, thus avoiding the need to buffer and combine chunks yourself</li>
</ol>
</section>
</dd>
@@ -1017,16 +1020,16 @@
<dt>ReadableByteStream fork()</dt>
<dd>
<p>
- This method creates a new ReadableByteStream which refers to the same <a>dataSource</a>.
+ This method creates a new ReadableByteStream which refers to the same <a>dataSource</a> as the current ReadableByteStream.
Data sources are range reference counted so that a range in a data source is freed only when all the ReadableByteStreams sharing the data source finish consuming it.
</p>
<p>
This method must run the steps below:
<ol>
- <li>Let <var>branch</var> be a new ReadableByteStream which refers to <a>dataSource</a> and has the same <a>bytesBeingRetrieved</a> value, <a>retrievedDataBuffer</a> contents and <a>eofReached</a> value</li>
- <li>If <a>bytesBeingRetrieved</a> is not 0, up to <a>bytesBeingRetrieved</a> bytes arriving in the future must be forwarded to <var>branch</var></li>
- <li>Return <var>branch</var></li>
+ <li>Let <var>branch</var> be a new ReadableByteStream which refers to <a>dataSource</a> and has the same <a>bytesBeingRetrieved</a> value, <a>retrievedDataBuffer</a> contents and <a>eofReached</a> value as the current ReadableByteStream.</li>
+ <li>If <a>bytesBeingRetrieved</a> is not 0, up to <a>bytesBeingRetrieved</a> bytes arriving in the future must be forwarded to <var>branch</var>.</li>
+ <li>Return <var>branch</var>.</li>
</ol>
</p>
</dd>
@@ -1050,7 +1053,7 @@
<dl class="idl" title="interface ByteStreamReadResult">
<dt>readonly attribute boolean eof</dt>
- <dd>Set iff the operation resulted in an EOF</dd>
+ <dd>Set if the operation resulted in an EOF</dd>
<dt>readonly attribute any data</dt>
<dd>The contents read converted into an object of the specified type</dd>
<dt>readonly attribute unsigned long long size</dt>