--- a/Overview.htm Fri Nov 29 19:02:13 2013 -0800
+++ b/Overview.htm Mon Dec 02 19:20:20 2013 +0900
@@ -174,7 +174,7 @@
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 internal data sink of a data consuming API using:
<ul>
<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>awaitSpaceAvailable()</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>
+ <li>The <code>awaitSpaceAvailable()</code> method for allowing a data-producer to write to the data sink only when the data sink 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 the details of actual communication with the data sink while allowing for an efficient transfer of bytes.
@@ -218,13 +218,15 @@
In the example below, different code blocks handle progress, error, and success conditions.
The example demonstrates how to read a chunk of data from a <a>ReadableByteStream</a> using <code>read()</code>.
The <a>ReadableByteStream</a> may of come from a <a href="#producers">producer</a> such as <code>XMLHttpRequest</code>.
- Additionally, it demonstrates how to read a stream until an EOF is encountered.
+ Additionally, it demonstrates how to read bytes from a <a>ReadableByteStream</a> until an EOF is encountered.
</p>
- <pre class="example">// Read up to 1024 bytes from the ReadableByteStream
+ <pre class="example">
+// Tell stream that we're ready to consume 1024 bytes.
+stream.pullAmount = 1024;
stream.readEncoding = "UTF-8";
stream.readType = "arraybuffer";
-stream.read(1024).then(
+stream.read().then(
function (result) {
// Process data
},
@@ -277,7 +279,9 @@
<code>write()</code> supports writing bytes represented as a <a>Blob</a>, <a>ArrayBuffer</a>, or <a>DOMString</a>.
</p>
<p>
- The example below demonstrates how to use <code>write()</code> to load a Stream into the audio tag, whose data could be processed and built dynamically at read time.
+ The example below demonstrates how to use <code>write()</code> to load a <a>ReadableByteStream</a> into the audio tag, whose data could be processed and built dynamically at read time.
+ ByteStream in the example is a class which implements both <a>WritableByteStream</a> and <a>ReadableByteStream</a>.
+ It accepts bytes generated by the code via <a>WritableByteStream</a> methods, and the written data will be consumed by the audio element via the object URL which is a part of <a>ReadableByteStream</a>'s functionality.
</p>
<pre class="example">var stream = new ByteStream("audio/mp3");
@@ -308,7 +312,7 @@
writeData();</pre>
<p>
- An producer can also do work only when pulled by using <code>awaitSpaceAvailable()</code>, which will inform the producer when to produce data. This is useful when high-performance is necessary.
+ A producer can also do work only when pulled by using <code>awaitSpaceAvailable()</code>, which will inform the producer when to produce data. This is useful when high-performance is necessary.
</p>
<pre class="example">function poll() {
@@ -330,7 +334,7 @@
<ol>
<li>How to receive the byte stream</li>
<li>How to notify the writer of completion of writing</li>
- <li>How to notify the writer of how much data can be currently accepted</li>
+ <li>How to notify the writer of how much data can be accepted currently</li>
</ol>
By returning a <a>Promise</a> and delaying fulfillment of it, the WritableByteStream realizes flow control.
@@ -548,8 +552,7 @@
</section>
<section class="section" id="readableByteStream">
-
- <h2>ReadableByteSteam Interface</h2>
+ <h2>ReadableByteSteam Interface</h2>
<p>
The ReadableByteStream interface defines a protocol for APIs which produce a byte stream. This protocol includes:
<ol>
@@ -562,18 +565,17 @@
</p>
<p>
- Interfaces introduced in this section provide simple and convenient ways to consume data.
- They connect arbitrary byte stream producer and byte stream consuming JavaScript code using Promises and method invocations.
+ Interfaces introduced in this section provide simple and convenient ways to consume data.
+ They connect arbitrary byte stream producer and byte stream consuming JavaScript code using Promises and method invocations.
</p>
<p>
A ReadableByteStream has a one-to-one mapping with an associated data source, and has defined semantics for <a href='#interactingWithDataSource'>interacting with the data source internally</a>. A data source, however, can have a one-to-many relationship with ReadableByteStream, in cases where <code>fork()</code> is used.
</p>
- <section class="section" id="readableByteStreamInterface">
+ <section class="section" id="readableByteStreamInterface">
<h3>ReadableByteStream interface</h3>
-
<dl class="idl" title="interface ReadableByteStream">
<dt>readonly attribute DOMString type</dt>
<dd>
@@ -657,9 +659,9 @@
Queue a task which runs the steps below:
<ol>
<li>Let <var>numBytesReadable</var> be the number of bytes in <a>readDataBuffer</a></li>
- <li>Let <var>bytesToOutput</var> be min(<var>size</var>, <var>numBytesReadable</var>)</li>
- <li>Set <a>numBytesBeingReturned</a> to <var>bytesToOutput</var></li>
- <li>Pop <var>bytesToOutput</var> bytes from <a>readDataBuffer</a>, and then let <var>readBytes</var> be the popped bytes</li>
+ <li>Let <var>bytesToReturn</var> be min(<var>size</var>, <var>numBytesReadable</var>)</li>
+ <li>Set <a>numBytesBeingReturned</a> to <var>bytesToReturn</var></li>
+ <li>Pop <var>bytesToReturn</var> bytes from <a>readDataBuffer</a>, and then let <var>readBytes</var> be the popped bytes</li>
<li>Set <a>readExactPullAmount</a> to 0</li>
@@ -675,7 +677,7 @@
</dl>
</li>
<li>Set <a href="#widl-ByteStreamReadResult-eof">eof</a> of <var>result</var> to <code>true</code> if <a>readDataBuffer</a> is empty and <a>eofReached</a> is set</li>
- <li>Set <a href="#widl-ByteStreamReadResult-size">size</a> of <var>result</var> to <var>bytesToOutput</var></li>
+ <li>Set <a href="#widl-ByteStreamReadResult-size">size</a> of <var>result</var> to <var>bytesToReturn</var></li>
<li>Fulfill <var>readPromise</var> with <var>result</var></li>
</ol>
</li>
@@ -838,20 +840,20 @@
<li>
<dl class="switch">
<dt>If <var>size</var> is specified</dt>
- <dd>Let <var>bytesToTransfer</var> be min(<var>size</var> - <var>totalBytesTransferred</var>, <var>numBytesReadable</var>)</dd>
+ <dd>Let <var>numBytesToTransfer</var> be min(<var>size</var> - <var>totalBytesTransferred</var>, <var>numBytesReadable</var>)</dd>
<dt>Otherwise</dt>
- <dd>Let <var>bytesToTransfer</var> be <var>numBytesReadable</var></dd>
+ <dd>Let <var>numBytesToTransfer</var> be <var>numBytesReadable</var></dd>
</dl>
</li>
- <li>Set <a>numBytesBeingReturned</a> to <a>numBytesBeingReturned</a> + <var>bytesToTransfer</var></li>
- <li>Pop <var>bytesToTransfer</var> bytes from <a>readDataBuffer</a>, and then write it to <a>dataSink</a> of <var>destination</var></li>
+ <li>Set <a>numBytesBeingReturned</a> to <a>numBytesBeingReturned</a> + <var>numBytesToTransfer</var></li>
+ <li>Pop <var>numBytesToTransfer</var> bytes from <a>readDataBuffer</a>, and then write it to <a>dataSink</a> of <var>destination</var></li>
<li>Let <var>tuple</var> be a new <a>pendingWrite</a></li>
<li>Set <var>writePromise</var> of <var>tuple</var> to <code>null</code></li>
- <li>Set <var>size</var> of <var>tuple</var> to <var>bytesToTransfer</var></li>
+ <li>Set <var>size</var> of <var>tuple</var> to <var>numBytesToTransfer</var></li>
<li>Push <var>tuple</var> to <a>pendingWriteQueue</a> of <var>destination</var></li>
- <li>Set <var>totalBytesTransferred</var> to <var>totalBytesTransferred</var> + <var>bytesToTransfer</var></li>
+ <li>Set <var>totalBytesTransferred</var> to <var>totalBytesTransferred</var> + <var>numBytesToTransfer</var></li>
<li>
<dl class="switch">
@@ -1287,13 +1289,14 @@
<section class="section" id="producers-consumers">
<h2>Stream Consumers and Producers</h2>
<p>
- Streams can be both produced and consumed by various APIs. APIs which create streams are identified as producers, and ones which read and act on a stream are known as consumers. This section identifies some of the APIs where Streams may be produced and consumed.
+ Byte streams can be both produced and consumed by various APIs. APIs which create streams are identified as producers, and ones which read and act on a byte stream are known as consumers. This section identifies some of the APIs where Streams may be produced and consumed.
<section class="note">The list of producers and consumers below is not an exhaustive list. It is placed here as informative for the time being.</section>
</p>
<section class="section" id="consumers">
<h2>Stream Consumers</h2>
- <p>This section outlines APIs which can consume a Stream object</p>
+ <p>This section outlines APIs which can consume a byte stream</p>
<ul>
+ <li>XMLHttpRequest</li>
<li>Web Audio</li>
<li>Media Source Extensions</li>
<li>Web Cryptography API</li>
@@ -1306,7 +1309,7 @@
<section class="section" id="producers">
<h2>Stream Producers</h2>
- <p>This section outlines APIs which can produce a Stream object</p>
+ <p>This section outlines APIs which can produce a byte stream</p>
<ul>
<li>XMLHttpRequest</li>
<li>FileReader</li>
@@ -1521,22 +1524,22 @@
Thanks to Eliot Graff for editorial assistance.
Special thanks to the W3C.
The editor would like to thank
+ Adrian Bateman,
Anne van Kesteren,
Austin William Wright,
Aymeric Vitte,
Domenic Denicola,
Elliott Sprehn,
+ Harris Syed,
Isaac Schlueter,
Jonas Sicking,
Kenneth Russell,
Kinuko Yasuda,
+ Lindsay Verola
Michael Davidson,
Taiju Tsuiki,
Yusuke Suzuki,
Yutaka Hirano,
- Adrian Bateman,
- Harris Syed,
- Lindsay Verola
for their contributions to this specification.
</p>
</section>