--- a/Overview.htm Mon Feb 03 15:52:36 2014 +0900
+++ b/Overview.htm Mon Feb 03 17:48:19 2014 +0900
@@ -247,30 +247,71 @@
</p>
<p>
- The example below demonstrates how to read a chunk of data from a <a>ReadableStream</a> using <code>readBytes()</code>.
- The <a>ReadableStream</a> may of come from a <a href="#producers">producer</a> such as <code>XMLHttpRequest</code>.
+ The example below demonstrates how to read one object from a <a>ReadableStream</a> and process it.
+ </p>
+
+ <pre class="example">
+readableStream.read().then(
+ function (result) {
+ processData(result.data);
+ },
+ function (error) {
+ processError(error);
+ });
+ </pre>
+
+ <p>
+ The example below demonstrates how to read binary data from a <a>ReadableStream</a> representing binary data and process it.
+ </p>
+
+ <pre class="example">
+// Determine the size of the next binary chunk.
+var nextChunkSize = parse(header);
+readableStream.readBytesAs = "arraybuffer";
+readableStream.readBytes(nextChunkSize).then(
+ function (result) {
+ processResult(result.data);
+ },
+ function (error) {
+ handleError(error);
+ });
+ </pre>
+
+ <p>
+ The example below demonstrates how to read text data from a <a>ReadableStream</a> representing binary data and process it.
+ </p>
+
+ <pre class="example">
+// Determine the size of the chunk containing text data.
+var textChunkSize = parse(header);
+readableStream.readBytesAs = "text";
+readableStream.readEncoding = "UTF-8";
+readableStream.readBytes(textChunkSize).then(
+ function (result) {
+ processData(result.data);
+ },
+ function (error) {
+ handleError(error);
+ });
+ </pre>
+
+ <p>
+ The example below demonstrates how to roughly adjust the amount of data to fetch from the underlying data source and buffer in a <a>ReadableStream</a>.
</p>
<pre class="example">
// Tell stream that we're ready to consume 1024 bytes.
stream.pullAmount = 1024;
-stream.readEncoding = "UTF-8";
-stream.readBytesAs = "arraybuffer";
-stream.readBytes().then(
- function (result) {
- // Process data
- },
- function (error) {
- // Handle error
- });</pre>
+ </pre>
<p>
The example below demonstrates how to read bytes from a <a>ReadableStream</a> until an EOF is encountered.
</p>
- <pre class="example">// Read data from the ReadableStream repeatedly
+ <pre class="example">
+// Read data from the ReadableStream repeatedly
function readUntilEof() {
- stream.read().then(
+ readableStream.read().then(
function (result) {
processData(result.data);
@@ -279,23 +320,24 @@
}
},
function (error) {
- // Handle error
+ handleError(error);
});
}
-readUntilEof();</pre>
+readUntilEof();
+ </pre>
<p>
The example below demonstrates how to obtain a <a>ReadableStream</a> from <a>XMLHttpRequest</a> to begin playing a large video in <code>readystate</code> LOADING.
The example takes the <a>ReadableStream</a> from a <a href="#producers">producer</a>, <a>XMLHttpRequest</a>, and gives it to a <a href="#consumers">consumer</a>, the video tag.
- If the consumer implements the <a>WritableStream</a> interface, we could use <code>pipe()</code> to transfer data to it instead of URL.
</p>
- <pre class="example">function handler() {
+ <pre class="example">
+function handler() {
if(this.readyState == this.LOADING) {
- var theStream = this.response;
- var streamURL = URL.createObjectURL(theStream);
- document.getElementById("myVideoTag").src = streamURL;
+ var readableStream = this.response;
+ var readableStreamURL = URL.createObjectURL(readableStream);
+ document.getElementById("myVideoTag").src = readableStreamURL;
}
}
@@ -308,37 +350,57 @@
client.send();</pre>
<p>
+ If the consumer implements the <a>WritableStream</a> interface, we can use <code>pipe()</code> to transfer data to it directly.
+ </p>
+
+ <pre class="example">
+function handler() {
+ if(this.readyState == this.LOADING) {
+ var readableStream = this.response;
+ readableStream.pipe(destinationStream).then(handleSuccess, handleFailure);
+ }
+}
+
+var client = new XMLHttpRequest();
+client.onreadystatechange = handler;
+client.open("GET", "/video");
+client.responseType = "stream";
+client.send();
+ </pre>
+
+ <p>
The example below demonstrates how to use <code>write()</code> to load a <a>ReadableStream</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>WritableStream</a> and <a>ReadableStream</a>.
It accepts bytes generated by the code via <a>WritableStream</a> methods, and the written data will be consumed by the audio element via the object URL which is a part of <a>ReadableStream</a>'s functionality.
</p>
- <pre class="example">var stream = new ByteStream("audio/mp3");
+ <pre class="example">
+var stream = new ByteStream("audio/mp3");
-function writeData() {
- // Do work to create more data to place into the stream
+function generateAndWriteData() {
+ // Do work to create more data to place into the stream.
var data = generateMusic();
- // If we have no more data to process and place in the stream, we close
- if (moreData == null){
+ // If we have no more data to process and place in the stream, we close the stream.
+ if (data == null){
stream.writeClose();
} else{
// Wait until write() completes.
stream.write(data).then(
function () {
- writeData();
+ generateAndWriteData();
},
function (error) {
- // Handle error
- }
- );
+ handleError(error);
+ });
}
}
var streamURL = URL.createObjectURL(stream);
document.getElementById('audioTag').src = streamURL;
-writeData();</pre>
+generateAndWriteData();
+ </pre>
<p>
A producer can also do work only when pulled by using <code>awaitSpaceAvailable()</code>.
@@ -346,7 +408,8 @@
This is useful when high-performance is necessary.
</p>
- <pre class="example">function poll() {
+ <pre class="example">
+function poll() {
stream.awaitSpaceAvailable().then(
function (pulledAmount) {
stream.write(generateRandomBytes(pulledAmount));
@@ -355,7 +418,8 @@
);
}
-poll();</pre>
+poll();
+ </pre>
<p>
The example below demonstrates how the timing to pull new data is determined.
@@ -365,7 +429,8 @@
In the example, the producer API is requested to produce 16 bytes, and then in the fulfill callback, pullAmount is set to the remaining number of bytes not to let the API produce more data.
</p>
- <pre class="example">stream.pullAmount = 16;
+ <pre class="example">
+stream.pullAmount = 16;
function read() {
stream.read().then(
function (result) {
@@ -380,7 +445,8 @@
}
}
);
-}</pre>
+}
+ </pre>
</section>
<section>