Re: [whatwg/encoding] Rename Encoding's "streams" to "I/O queues" (#215)

@annevk commented on this pull request.



> @@ -94,35 +90,133 @@ bitwise AND by "&", and bitwise OR by "|".
 
 <hr>
 
-<p>A <dfn id=concept-token>token</dfn> is a piece of data, such as a <a>byte</a> or
-<a>scalar value</a>.
+<p>An <dfn id=concept-stream export>I/O queue</dfn> is a type of <a for=/>list</a>
+with <a for=list>items</a> of a particular type (i.e. <a>bytes</a> or <a>scalar
+values</a>). <dfn id="end-of-stream" export>End-of-queue</dfn> is a special
+<a for=list>item</a> that can be present in <a for=/>I/O queues</a> of any type, and that
+signifies no more <a for=list>items</a> are in the queue.
+
+<p>To <dfn for="I/O queue" export>create</dfn> an <a for=/>I/O queue</a>, optionally initialized
+with a list <var>contents</var>, return a new <a for=/>I/O queue</a> containing the
+<a for=list>items</a> of <var>contents</var> in order, if it is given, followed by an
+<a>end-of-queue</a> item.

Do we really need the create primitive instead of using the shorthand syntax for lists? It seems confusing to me to have it and only allow immediate-queue creation.

> + underlying network stream closes, an <a>end-of-queue</a> item is to be
+ <a for="I/O queue">pushed</a> into the queue.
+
+ <p>Since reading from a streaming <a for=/>I/O queue</a> might block, streaming
+ <a for=/>I/O queues</a> are not to be used from an <a for=/>event loop</a>.
+ They are to be used <a>in parallel</a> instead.
+</div>
+
+<p>To <dfn id=concept-stream-read for="I/O queue" export>read</dfn> an
+<a for=list>item</a> from an <a for=/>I/O queue</a> <var>ioQueue</var>, run these steps:
+
+<ol>
+ <li><p>If <var>ioQueue</var> is <a for=list>empty</a>, then wait until its
+ <a for=list>size</a> is at least 1.
+
+ <li><p>If the first item in <var>ioQueue</var> is <a>end-of-queue</a>, then

ioQueue[0] is ...

> +
+<p>To <dfn id=concept-stream-read for="I/O queue" export>read</dfn> an
+<a for=list>item</a> from an <a for=/>I/O queue</a> <var>ioQueue</var>, run these steps:
+
+<ol>
+ <li><p>If <var>ioQueue</var> is <a for=list>empty</a>, then wait until its
+ <a for=list>size</a> is at least 1.
+
+ <li><p>If the first item in <var>ioQueue</var> is <a>end-of-queue</a>, then
+ return <a>end-of-queue</a>.
+
+ <li><p>Otherwise, <a for=list>remove</a> the first item in <var>ioQueue</var>
+ and return it.
+</ol>
+
+<p>To read a number <var>number</var> of <a for=list>items</a> from <var>ioQueue</var>,

This needs a dfn if we are to keep it.

-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/whatwg/encoding/pull/215#pullrequestreview-453207284