Re: [whatwg/streams] A variety of clarity and documentation improvements (#875)

lgrahl commented on this pull request.

https://github.com/whatwg/streams/pull/875/files#diff-ec9cfa5f3f35ec1f84feb2e59686c34dR2803

This needs updating since the meaning of the `.write` promise has now been more well defined to either be *I'm done writing* or *I don't have such a signal*. (Might be that there are more sections which need updating because of this.)

> +  <pre><code class="lang-javascript">
+  async function writeSuppliedBytesForever(writableStream, getBytes) {
+    const writer = writableStream.getWriter();
+
+    while (true) {
+      await writer.ready;
+
+      const bytes = getBytes();
+      writer.write(bytes).catch(() => {});
+    }
+  }
+  </code></pre>
+
+  Unlike the previous example, where—because we were always writing exactly
+  {{WritableStreamDefaultWriter/desiredSize|writer.desiredSize}} bytes each time—the
+  {{WritableStreamDefaultWriter/write()}} and {{WritableStreamDefaultWriter/ready}} promises were synchronized, in this

This example (and the one above) assumes that the underlying sink returns such a promise to the writer. It might be worth adding that assumption.

> +      const bytes = getBytes();
+      writer.write(bytes).catch(() => {});
+    }
+  }
+  </code></pre>
+
+  Unlike the previous example, where—because we were always writing exactly
+  {{WritableStreamDefaultWriter/desiredSize|writer.desiredSize}} bytes each time—the
+  {{WritableStreamDefaultWriter/write()}} and {{WritableStreamDefaultWriter/ready}} promises were synchronized, in this
+  case it's quite possible that the {{WritableStreamDefaultWriter/ready}} promise fulfills before the one returned by
+  {{WritableStreamDefaultWriter/write()}} does. Remember, the {{WritableStreamDefaultWriter/ready}} promise fulfills
+  when the <a lt="desired size to fill a stream's internal queue">desired size</a> becomes positive, which might be
+  before the write succeeds (especially in cases with a larger <a>high water mark</a>).
+
+  In other words, <code>await</code>ing the return value of {{WritableStreamDefaultWriter/write()}} means you never
+  queue up writes in the stream's <a>internal queue</a>, instead only executing a write after the previous one succeeds.

Maybe add this at the end of the sentence:

> ... which may result in low throughput.

> +    <p>This function is used to actually send the data to the resource presented by the <a>underlying sink</a>, for
+    example by calling a lower-level API.</p>
+
+    <p>If the process of writing data is asynchronous, and communicates success or failure signals back to its user,
+    then this function can return a promise to signal success or failure. This promise return value will be communicated
+    back to the caller of {{WritableStreamDefaultWriter/write()|writer.write()}}, so they can monitor that individual
+    write. Throwing an exception is treated the same as returning a rejected promise.</p>
+
+    <p>Note that such signals are not always available; compare e.g. [[#example-ws-no-backpressure]] with
+    [[#example-ws-backpressure]]. In such cases, it's best to not return anything.</p>
+
+    <p>The promise potentially returned by this function also governs whether the given chunk counts as written for the
+    purposes of computed the <a lt="desired size to fill a stream's internal queue">desired size to fill the stream's
+    internal queue</a>. That is, during the time it takes the promise to settle,
+    {{WritableStreamDefaultWriter/desiredSize|writer.desiredSize}} will stay at its previous value, only increasing to
+    signal the desire for more chunks once the write succeeds.</p>

 👍 

-- 
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/streams/pull/875#pullrequestreview-96497557