Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

WritableStream Example #532

Open
wants to merge 14 commits into
base: gh-pages
Choose a base branch
from
Prev Previous commit
Improve explanation draft.
jpmedley committed Aug 7, 2017
commit 6e466473e16d152197fb8890af312409442ff310
18 changes: 12 additions & 6 deletions streams/index.html
Original file line number Diff line number Diff line change
@@ -7,18 +7,24 @@
<h3>Background</h3>
<p>This sample illustrates the use of <code><a href="https://streams.spec.whatwg.org/#ws">WritableStream</a></code>, which shows how to break apart a longer piece of data and stream it (send it in chunks) to an output.</p>

<p>WritableStreams objects are designed to only be used once. This example creates a new instance every time "Send message" is clicked. The <code>sendMessage()</code> uses that instance to send very byte of the entered message and closes the instance when it is done (<code>defaultWriter.close()</code>).</p>
<p>WritableStreams objects are designed to only be used once. This example creates a new instance every time "Send message" is clicked. The <code>sendMessage()</code> uses that instance to send every byte of the entered message and closes the instance when it is done (<code>defaultWriter.close()</code>).</p>

<p>Data source &gt; writer &gt; sink</p>
<p>The data flow in this example is generally from the text entry field to sink. The details are a bit more complicated. The general flow is this.</p>

<p>The writer is created by the <code>WritableStream</code> object.</p>
<ol>
<li>Create an instance of <code>WritableStream</code>. Pass it a data destination, called a 'sink' in it's constructor as a literal.</li>
<li>Call <code>writableStreamInstance.getWriter()</code> to get a defaul writer.</li>
<li>Iterate the chunks of the message and pass each to the default writer.</li>
<li>Close the default writer.</li>
</ol>

<p>If you're familliar at all with streams you may be wondering how backpressure is implemented using this API, especially since the word 'backpressure' doesn't appear as a member of any of the API's interfaces. Three items combine to create a backpressure signal.</p>

<ul>
<li><em><code>highwatermark</code>:</em> When creating the <code>WritableStream</code> instance, the second property passed to the constructor is a queuing strategy object. This object's constructor takes an object with a <code>highwatermark</code> property whose value species the maximum amount of data that the </code>WritableStream</code> can handle at once.</li>
<li><em><code>writer.ready</code>: </em>This tells you whether the underlying sink is done writing the data it's received. Check this before adding new data to the pipe <strong>and</strong> before closing the writer.</li>
<li><em>The promise returned by <code>write()</code>:</em> The sink's <code>write()</code> method must return a promise. This is used to set <code>writer.ready()</code> to an appropriate value.</li>
<li><em><code>highwatermark</code>:</em> Specifies the maximum amout of data that the <code>WritableStream</code> can handle at once. When creating the <code>WritableStream</code> instance, the second property passed to the constructor is a queuing strategy object. This object's constructor takes an object with a <code>highwatermark</code> property. How <code>highwatermark</code> is specified varies depending on the type of queuing strategy object.</li>
<li><em><code>writer.ready</code>: </em>Returns a promise that resolves whenever the underlying data sink is able to receive more data for writing. Check this before adding new data to the pipe <strong>and</strong> before closing the writer.</li>

<li><em>The promise returned by <code>write()</code>:</em> The sink's <code>write()</code> method must return a promise. This tells <code>writer.ready()</code> when to return its promise.</li>
</ul>

{% capture initial_output_content %}