Split read into read and readExact
authorTakeshi Yoshino <tyoshino@google.com>
Fri, 08 Nov 2013 03:42:09 +0900
changeset 49 1d2b4730c972
parent 48 f31fd34af780
child 50 c8fe7f74d80c
Split read into read and readExact

pipe() returns ByteStreamConsumeResult now
preview.html
--- a/preview.html	Fri Nov 08 02:43:24 2013 +0900
+++ b/preview.html	Fri Nov 08 03:42:09 2013 +0900
@@ -402,7 +402,13 @@
 		<h2>ReadableByteStream interface</h2>
 
 		<p>
-			The ReadableByteStream interface defines a protocol for APIs that produces byte stream how to receive a read request from the reader and output byte stream.
+			The ReadableByteStream interface defines a protocol for APIs that produces byte stream:
+			<ol>
+				<li>How to receive a read request from the reader and output byte stream.</li>
+				<li>How to transfer bulk data to other <a>WritableByteStream</a> (by pipe() method)</li>
+				<li>How to mirror data to multiple destination <a>WritableByteStream</a>s (by substream() method)</li>
+			</ol>
+
 			By returning a Promise and delaying fulfillment of it, the ReadableByteStream realizes asynchronous data consumption.
 		</p>
 
@@ -410,7 +416,7 @@
 			<dt>attribute ByteStreamReadType readType</dt>
 			<dd>
 				<p>
-					Specifies the type of data to receive data read from the ReadableByteStream by a <code>read()</code> method call.
+					Specifies as what type data will be read from the ReadableByteStream by a <code>read()</code> and <code>readExact()</code> method call.
 					This can be set to the empty <a>DOMString</a> (default), "<code>arraybuffer</code>", "<code>blob</code>", "<code>text</code>" or "<code>none</code>" to change the type of the read operation.
 				</p>
 			</dd>
@@ -419,33 +425,53 @@
 			<dd>
 				<p>
 					Specifies a <a>DOMString</a> that represents the label of an encoding [[!EncodingDetermination]].
-					If set, it will be used as part of the encoding determination used when processing a <code>read</code> method call.
-					It will return the label last set, or the empty <a>DOMString</a> if never set.
+					If set, it will be used as part of the encoding determination used when processing a <code>read()</code> method call.
 				</p>
 
+				<section class="note">
+					This parameter is not designed to be specified as an argument of <code>read()</code> since it's not likely to be changed frequently.
+				</section>
+			</dd>
+
+			<dt>ByteStreamConsumeResult readExact()</dt>
+			<dd>
 				<p>
-					This parameter is not designed to be specified as an argument of read() since it's not likely to be changed frequently.
+					The same as <code>read()</code> except for the following points:
+
+					<ol>
+						<li>waits until bytes of the specified number become readable</li>
+						<li><code>readType</code> must be one of "<code>arraybuffer</code>", "<code>blob</code>" and "<code>none</code>"</li>
+						<li>size parameter is not omittable</li>
+					</ol>
 				</p>
+
+				<dl class="parameters">
+					<dt>[Clamp] unsigned long long size</dt>
+					<dd>Number of bytes to read.</dd>
+				</dl>
 			</dd>
 
 			<dt>ByteStreamConsumeResult read()</dt>
 			<dd>
 				<p>
 					This method reads data from the ReadableByteStream.
-					This method takes an optional <var>size</var> argument which represents the number of bytes to be read.
-					Another read() or pipe() call must not be made until the returned Promise is resolved or rejected.
-					The user agent must run the steps below (unless otherwise indicated):
+					If there's no data synchronously readable, waits until any non-empty result can be read.
+					If <var>size</var> argument is specified, this method reads up to <var>size</var> bytes.
 				</p>
 
 				<p>
-					<b>Experimental sync/async hybrid read() method algoritm</b>
+					Another <code>read()</code>, <code>readExact()</code>, <code>pipe()</code> or <code>substream()</code> method call must not be made until this <code>read()</code> completes.
+				</p>
+
+				<p>
+					This method must run the steps below:
 
 					<dl class="switch">
-						<dt>EOF is reached</dt>
+						<dt>If <a>the EOF is reached</a></dt>
 						<dd>
 							<ol>
 								<li>Let <var>result</var> be a <a>ByteStreamConsumeResult</a>.</li>
-								<li>Set eof attribute of <var>result</var> to true.</li>
+								<li>Set eof attribute of <var>result</var> to <code>true</code>.</li>
 								<li>Return <var>result</var>.</li>
 							</ol>
 						</dd>
@@ -453,14 +479,17 @@
 						<dd>
 							<ol>
 								<li>Let <var>result</var> be a <a>ByteStreamConsumeResult</a>.</li>
-								<li>Set eof attribute of <var>result</var> to false.</li>
+								<li>Set eof attribute of <var>result</var> to <code>false</code>.</li>
 								<li>
 									<dl class="switch">
-										<dt>There's any data available to be read synchronously (when readType is "<code>text</code>", also the data need to be decoded to non-empty DOMString)</dt>
+										<dt>There's any data available to be read synchronously (when readType is "<code>text</code>", also the data need to be decoded to non-empty <a>DOMString</a>)</dt>
 										<dd>
 											<ol>
 												<li>Set size attribute of <var>result</var> to the number of bytes consumed.</li>
-												<li>Set data attribute of <var>result</var> to the read data.</li>
+												<li>
+													Set data attribute of <var>result</var> to the read data.
+													If <var>size</var> argument was specified, convert only the first <var>size</var> bytes.
+												</li>
 												<li>Return <var>result</var>.
 											</ol>
 										</dd>
@@ -469,9 +498,9 @@
 											<ol>
 												<li>Set size attribute of <var>result</var> to 0.</li>
 												<li>Let <var>readPromise</var> be a <a>Promise</a>.</li>
-												<li>Set data attribute of <var>result</var> to a <var>promise</var>.</li>
+												<li>Set data attribute of <var>result</var> to <var>readPromise</var>.</li>
 												<li>Return <var>result</var>.</li>
-												<li>When data becomes available for read, rerun this algorithm to create a <a>ByteStreamConsumeResult</a> and fulfill <var>promise</var> with it.</li>
+												<li>When data becomes available for read, rerun this algorithm to create a <a>ByteStreamConsumeResult</a> and fulfill <var>readPromise</var> with it.</li>
 											</ol>
 										</dd>
 									</dl>
@@ -487,42 +516,46 @@
 				</dl>
 			</dd>
 
-			<dt>Promise pipe()</dt>
+			<dt>ByteStreamConsumeResult pipe()</dt>
 			<dd>
 				<p>
 					This method transfers bytes from the ReadableByteStream to a <a>WritableByteStream</a>.
-					This method takes a <var>destination</var> argument and optionally a <var>size</var> argument.
-					Another read() or pipe() call must not be made until the returned <a>Promise</a> is fulfilled or rejected.
-
-					<dl class="parameters">
-						<dt>WritableByteStream destination</dt>
-						<dd>Destination <a>WritableByteStream</a>.</dd>
-						<dt>optional [Clamp] unsigned long long size</dt>
-						<dd>Number of bytes to transfer.</dd>
-					</dl>
 				</p>
 
-				<dt>Promise substream()</dt>
-				<dd>
-					<p>
-						<b>Experimental substream() method, aka fork() method.</b>
-					</p>
-
-					<p>
-						This method creates a clone of the ReadableByteStream which refers to the same internal data sequence.
-						Internal data sequence of the original ReadableByteStream will be reference counted so that a range in the original data sequence is freed only when all the ReadableByteStreams sharing the sequence.
-
-						<dl class="parameters">
-							<dt>in optional [Clamp] unsigned long long size</dt>
-							<dd>Number of bytes to be readable from the new Stream.</dd>
-						</dl>
-					</p>
-				</dd>
-			</dl>
+				<section class="note">
+					Note that fulfillment or rejection of the returned Promise doesn't necessarily mean that the data transferred to the destination <a>WritableByteStream</a> has been successfully read from it.
+				</section>
 
 				<p>
-					Note that fulfillment or rejection of the returned Promise doesn't necessarily mean that the data transferred to the destination Stream has been successfully read from the Stream.
+					Another <code>read()</code>, <code>readExact()</code>, <code>pipe()</code> or <code>substream()</code> method call must not be made until this <code>pipe()</code> completes.
 				</p>
+
+				<dl class="parameters">
+					<dt>WritableByteStream destination</dt>
+					<dd>Destination <a>WritableByteStream</a>.</dd>
+					<dt>optional [Clamp] unsigned long long size</dt>
+					<dd>Number of bytes to transfer.</dd>
+				</dl>
+			</dd>
+
+			<dt>ReadableByteStream substream()</dt>
+			<dd>
+				<p>
+					<b>Experimental substream() method, aka fork() method.</b>
+				</p>
+
+				<p>
+					This method creates a clone of the ReadableByteStream which refers to the same internal data sequence.
+					Internal data sequence of the original ReadableByteStream will be reference counted so that a range in the original data sequence is freed only when all the ReadableByteStreams sharing the sequence.
+
+					<dl class="parameters">
+						<dt>in optional [Clamp] unsigned long long size</dt>
+						<dd>Number of bytes to be readable from the new Stream.</dd>
+					</dl>
+				</p>
+			</dd>
+		</dl>
+
 			</dd>
 		</dl>