Add how to notify abort/error signal
authorTakeshi Yoshino <tyoshino@google.com>
Tue, 10 Dec 2013 02:54:48 +0900
changeset 119 218f3b3a2df5
parent 118 360cd31579a7
child 122 667dbc39f9e6
Add how to notify abort/error signal
Overview.htm
--- a/Overview.htm	Tue Dec 10 01:20:10 2013 +0900
+++ b/Overview.htm	Tue Dec 10 02:54:48 2013 +0900
@@ -529,10 +529,12 @@
 						Data sinks must be able to accept data more than it notified <a>WritableByteStream</a> of.
 					</li>
 					<li>
-						Notifies <a>WritableByteStream</a> of acknowledgement of the EOF signal.
+						Notifies <a>WritableByteStream</a> of that the data sink is gone.
+						This signal may mean an error.
+						If it means an error, an object indicating the details of the error is attached.
 					</li>
 					<li>
-						Notifies <a>WritableByteStream</a> of acknowledgement of the write-abort signal.
+						Notifies <a>WritableByteStream</a> of acknowledgement of the write-abort signal with error detail object.
 					</li>
 					<li>
 						How to calculate an integer value <dfn>cost</dfn> of each object which the data sink can consume.
@@ -588,15 +590,32 @@
 				<ol>
 					<li>If <a>pendingWriteQueue</a> is empty, break from this loop</li>
 					<li>Let <var>pendingWrite</var> be the head element of <a>pendingWriteQueue</a></li>
-					<li>Let <var>amountToAcknowledge</var> be min(<var>pendingWrite.amount</var> - <var>pendingWrite.ackedAmount</var>, <a>spaceAvailable</a>)</li>
-					<li>Set <a>spaceAvailable</a> to <a>spaceAvailable</a> - <var>amountToAcknowledge</var></li>
-					<li>Set <var>pendingWrite.ackedAmount</var> to <var>pendingWrite.ackedAmount</var> + <var>amountToAcknowledge</var></li>
 					<li>
-						If <var>pendingWrite.ackedAmount</var> equals to <var>pendingWrite.amount</var>, run the steps below:
-						<ol>
-							<li>Pop <var>pendingWrite</var> from <a>pendingWriteQueue</a></li>
-							<li>If <var>pendingWrite.promise</var> is not <code>null</code>, fulfill it with <var>pendingWrite.amount</var></li>
-						</ol>
+						<dl class="switch">
+							<dt>If <a>sinkGone</a> is set</dt>
+							<dd>Run the steps below:
+								<ol>
+									<li>Pop <var>pendingWrite</var> from <a>pendingWriteQueue</a>, and then</li>
+									<li>If <var>pendingWrite.promise</var> is not <code>null</code>, reject it with <a>sinkErrorDetail</a></li>
+								</ol>
+							</dd>
+							<dt>Otherwise</dt>
+							<dd>Run the steps below:
+								<ol>
+									<li>Let <var>amountToAcknowledge</var> be min(<var>pendingWrite.amount</var> - <var>pendingWrite.ackedAmount</var>, <a>spaceAvailable</a>)</li>
+									<li>Set <a>spaceAvailable</a> to <a>spaceAvailable</a> - <var>amountToAcknowledge</var></li>
+									<li>Set <var>pendingWrite.ackedAmount</var> to <var>pendingWrite.ackedAmount</var> + <var>amountToAcknowledge</var></li>
+									<li>
+										If <var>pendingWrite.ackedAmount</var> equals to <var>pendingWrite.amount</var>, run the steps below:
+										<ol>
+											<li>Pop <var>pendingWrite</var> from <a>pendingWriteQueue</a></li>
+											<li>If <var>pendingWrite.promise</var> is not <code>null</code>, fulfill it with <var>pendingWrite.amount</var></li>
+										</ol>
+									</li>
+								</ol>
+							</dd>
+						</dl>
+					</li>
 				</ol>
 			</p>
 
@@ -607,6 +626,23 @@
 					<li><a>Process pendingWriteQueue</a></li>
 				</ol>
 			</p>
+
+			<p>
+				A WritableByteStream has an associated flag <dfn>sinkGone</dfn> which is set when the data sink is gone.
+			</p>
+
+			<p>
+				A WritableByteStream has an associated object <dfn>sinkErrorDetail</dfn> which is initialized to null, and when the data sink is gone, set to the error detail object.
+			</p>
+
+			<p>
+				When <a>dataSink</a> notifies the WritableByteStream of that the data sink is gone, queue a task which runs the steps below:
+				<ol>
+					<li>Set <a>sinkGone</a></li>
+					<li>Set <a>sinkErrorDetail</a> to the error detail object</li>
+					<li><a>Process pendingWriteQueue</a></li>
+				</ol>
+			</p>
 		</section>
 	</section>
 
@@ -736,8 +772,9 @@
 											<dd>Set <var>result</var>.<a href="#widl-ByteStreamReadResult-data">data</a> to an object of the type specified by <var>latchedType</var> which represents <var>readBytes</var></dd>
 										</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-amountConsumed">amountConsumed</a> of <var>result</var> to <var>amountToReturn</var></li>
+									<li>Set <var>result</var>.<a href="#widl-ByteStreamReadResult-eof">eof</a> to <code>true</code> if <a>readDataBuffer</a> is empty and <a>eofReached</a> is set</li>
+									<li>Set <var>result</var>.<a href="#widl-ByteStreamReadResult-amountConsumed">amountConsumed</a> to <var>amountToReturn</var></li>
+									<li>Set <var>result</var>.<a href="#widl-ByteStreamReadResult-error">error</a> to <a>sourceErrorDetail</a></li>
 									<li>Fulfill <var>readPromise</var> with <var>result</var></li>
 								</ol>
 							</li>
@@ -835,6 +872,7 @@
 							<li>Set <var>result</var>.<a href="#widl-ByteStreamReadResult-data">data</a> to <var>readData</var></li>
 							<li>Set <var>result</var>.<a href="#widl-ByteStreamReadResult-eof">eof</a> to <code>true</code> if <a>eofReached</a> is set and <a>readDataBuffer</a> is empty</li>
 							<li>Set <var>result</var>.<a href="#widl-ByteStreamReadResult-amountConsumed">amountConsumed</a> to <var>amountConsumed</var></li>
+							<li>Set <var>result</var>.<a href="#widl-ByteStreamReadResult-error">error</a> to <a>sourceErrorDetail</a></li>
 
 							<li>Set <a>amountBeingReturned</a> to <var>amountConsumed</var></li>
 
@@ -1013,28 +1051,10 @@
 					</p>
 				</dd>
 
-				<dt>Promise&amp;lt;undefined&gt; readClose()</dt>
-				<dd>
-					<p>
-						This method tells the ReadableByteStream that no more data will be read from it without indication of any error.
-					</p>
-
-					<p>
-						This method must run the steps below:
-						<ol>
-							<li>Let <var>closePromise</var> be a new <a>Promise</a></li>
-							<li>Return <var>closePromise</var>, and then continue the process the steps in this algorithm</li>
-							<li>Notify <a>dataSource</a> of readClosure</li>
-							<li>Wait until <a>dataSource</a> acknowledges the readClosure</li>
-							<li>Fulfill <var>closePromise</var> with <code>undefined</code></li>
-						</ol>
-					</p>
-				</dd>
-
 				<dt>Promise&amp;lt;undefined&gt; readAbort(optional any reason)</dt>
 				<dd>
 					<p>
-						This method tells the ReadableByteStream that no more data will be read from it with indication of error.
+						This method tells the ReadableByteStream that no more data will be read from it optionally with indication of error.
 						The details of the error will be given by <var>reason</var> argument.
 						The interpretation of <var>reason</var> is up to <a>dataSource</a>.
 						Once readAbort() has been called on a ReadableByteStream, no further method calls can be made on the ReadableByteStream.
@@ -1070,6 +1090,11 @@
 						Produces bytes. Newly produced bytes will be delivered to the associated <a>ReadableByteStream</a>.
 					</li>
 					<li>
+						Notifies <a>ReadableByteStream</a> of the EOF signal.
+						This signal may mean an error.
+						If it means an error, an object indicating the details of the error is attached.
+					</li>
+					<li>
 						Accepts requests for production of bytes from a <a>ReadableByteStream</a>. A byte production request consists of an integer indicating the number of bytes to produce in addition to already requested ones.
 						Interpretation of the request is up to data sources.
 						Data sources may respond to retrieval requests with data larger than requested.
@@ -1077,10 +1102,7 @@
 						Data sources may produce bytes and send to <a>ReadableByteStream</a> unsolicitedly without receiving any retrieval request.
 					</li>
 					<li>
-						Accepts and acknowledges readClosure signal which means the associated <a>ReadableByteStream</a> has completed consuming bytes from this data source without indication of any error.
-					</li>
-					<li>
-						Accepts and acknowledges read-abort signal which means the associated <a>ReadableByteStream</a> has completed consuming bytes from this data source with indication of any error.
+						Accepts and acknowledges read-abort signal which means the associated <a>ReadableByteStream</a> has completed consuming bytes from this data source optionally with indication of any error.
 					</li>
 				</ul>
 			</p>
@@ -1168,6 +1190,10 @@
 			</p>
 
 			<p>
+				An associated object <dfn>sourceErrorDetail</dfn> which is initialized to <code>null</code>, and once the EOF meaning an error is received from the <a>dataSource</a>, set to the error detail object.
+			</p>
+
+			<p>
 				To <dfn>retrieve data</dfn>, run the steps below:
 				<ol>
 					<li>Let <var>readableAmount</var> be the number of bytes in the <a>readDataBuffer</a></li>
@@ -1192,10 +1218,9 @@
 			</p>
 
 			<p>
-				When the EOF is received from <a>dataSource</a>, queue a task which sets <a>eofReached</a>.
+				When the EOF is received from <a>dataSource</a>, queue a task which sets <a>eofReached</a> and <a>sourceErrorDetail</a>
 			</p>
-
-	    </section>
+	  </section>
 	</section>
 
 	<section class="section">
@@ -1212,6 +1237,8 @@
 			<dd>The contents read converted into an object of the specified type</dd>
 			<dt>readonly attribute unsigned long long amountConsumed</dt>
 			<dd>The size, in bytes, of the data read</dd>
+			<dt>readonly attribute any error</dt>
+			<dd>Once any error occurred, set to the error detail object on all ByteStreamReadResults returned after the error</dd>
 		</dl>
 	</section>