site docs

Author: j50n

docs/example-concurrent-processing.html

@@ -181,9 +181,9 @@ <h1 id="concurrent-processes"><a class="header" href="#concurrent-processes">Con
 most storage. <code>proc</code> makes it possible to run <code>ls --summarize</code> with parallelism
 matching the number of CPU cores available (or whatever concurrency you
 specify). The specific methods that support concurrent operations are
-<a href="https://deno.land/x/proc@0.21.6/mod3.ts?s=Enumerable&amp;p=prototype.concurrentMap">.concurrentMap()</a>
+<a href="https://deno.land/x/proc@0.21.7/mod3.ts?s=Enumerable&amp;p=prototype.concurrentMap">.concurrentMap()</a>
 and
-<a href="https://deno.land/x/proc@0.21.6/mod3.ts?s=Enumerable&amp;p=prototype.concurrentUnorderedMap">.concurrentUnorderedMap()</a>.</p>
+<a href="https://deno.land/x/proc@0.21.7/mod3.ts?s=Enumerable&amp;p=prototype.concurrentUnorderedMap">.concurrentUnorderedMap()</a>.</p>
 <p>To list the <code>s3</code> buckets in your AWS account from terminal:</p>
 <pre><code class="language-sh">aws s3 ls
 </code></pre>
@@ -223,7 +223,7 @@ <h1 id="concurrent-processes"><a class="header" href="#concurrent-processes">Con
 )
 </code></pre>
 <p>Use <code>nice</code> because <em>this will eat your server otherwise.</em> The method
-<a href="https://deno.land/x/proc@0.21.6/mod3.ts?s=Enumerable&amp;p=prototype.concurrentUnorderedMap">.concurrentUnorderedMap()</a>
+<a href="https://deno.land/x/proc@0.21.7/mod3.ts?s=Enumerable&amp;p=prototype.concurrentUnorderedMap">.concurrentUnorderedMap()</a>
 will, by default, run one process for each CPU available concurrently until all
 work is done.</p>
 <p>The result will look something like this:</p>

docs/index.html

@@ -173,21 +173,21 @@ <h1 class="menu-title">proc</h1>
 
                 <div id="content" class="content">
                     <main>
-                        <h1 id="proc-0216"><a class="header" href="#proc-0216"><code>proc 0.21.6</code></a></h1>
+                        <h1 id="proc-0217"><a class="header" href="#proc-0217"><code>proc 0.21.7</code></a></h1>
 <p><code>proc</code> let's you use child processes with
 <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/AsyncIterator"><code>AsyncIterable</code></a>
 instead of the streams API, and it includes a library of higher-order functions
 for <code>AsyncIterator</code> via
-<a href="https://deno.land/x/proc@0.21.6/mod.ts?s=Enumerable"><code>Enumerable</code></a> that
+<a href="https://deno.land/x/proc@0.21.7/mod.ts?s=Enumerable"><code>Enumerable</code></a> that
 roughly matches what you can do with an array (<code>map</code>, <code>filter</code>, <code>find</code>), but for
 asynchronous code.</p>
 <p><code>proc</code> simplifies the process of converting a <code>bash</code> script into a Deno
 application. The intention is to make writing code that uses lots of IO and
 child processes <em>almost</em> as easy as shell scripting, but you also get proper
 error handling, type checking, and Deno's security-by-default.</p>
-<p><a href="https://deno.land/x/proc@0.21.6/mod.ts">Developer Documentation</a></p>
+<p><a href="https://deno.land/x/proc@0.21.7/mod.ts">Developer Documentation</a></p>
 <h2 id="usage"><a class="header" href="#usage">Usage</a></h2>
-<pre><code class="language-typescript">import { run } from &quot;https://deno.land/x/proc@0.21.6/mod.ts&quot;;
+<pre><code class="language-typescript">import { run } from &quot;https://deno.land/x/proc@0.21.7/mod.ts&quot;;
 </code></pre>
 <h2 id="a-simple-example"><a class="header" href="#a-simple-example">A Simple Example</a></h2>
 <p>Run <code>ls -la</code> as a child process. Decode <code>stdout</code> as lines of text. Print to

docs/introduction.html

@@ -173,21 +173,21 @@ <h1 class="menu-title">proc</h1>
 
                 <div id="content" class="content">
                     <main>
-                        <h1 id="proc-0216"><a class="header" href="#proc-0216"><code>proc 0.21.6</code></a></h1>
+                        <h1 id="proc-0217"><a class="header" href="#proc-0217"><code>proc 0.21.7</code></a></h1>
 <p><code>proc</code> let's you use child processes with
 <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/AsyncIterator"><code>AsyncIterable</code></a>
 instead of the streams API, and it includes a library of higher-order functions
 for <code>AsyncIterator</code> via
-<a href="https://deno.land/x/proc@0.21.6/mod.ts?s=Enumerable"><code>Enumerable</code></a> that
+<a href="https://deno.land/x/proc@0.21.7/mod.ts?s=Enumerable"><code>Enumerable</code></a> that
 roughly matches what you can do with an array (<code>map</code>, <code>filter</code>, <code>find</code>), but for
 asynchronous code.</p>
 <p><code>proc</code> simplifies the process of converting a <code>bash</code> script into a Deno
 application. The intention is to make writing code that uses lots of IO and
 child processes <em>almost</em> as easy as shell scripting, but you also get proper
 error handling, type checking, and Deno's security-by-default.</p>
-<p><a href="https://deno.land/x/proc@0.21.6/mod.ts">Developer Documentation</a></p>
+<p><a href="https://deno.land/x/proc@0.21.7/mod.ts">Developer Documentation</a></p>
 <h2 id="usage"><a class="header" href="#usage">Usage</a></h2>
-<pre><code class="language-typescript">import { run } from &quot;https://deno.land/x/proc@0.21.6/mod.ts&quot;;
+<pre><code class="language-typescript">import { run } from &quot;https://deno.land/x/proc@0.21.7/mod.ts&quot;;
 </code></pre>
 <h2 id="a-simple-example"><a class="header" href="#a-simple-example">A Simple Example</a></h2>
 <p>Run <code>ls -la</code> as a child process. Decode <code>stdout</code> as lines of text. Print to

docs/performance.html

@@ -175,44 +175,37 @@ <h1 class="menu-title">proc</h1>
                     <main>
                         <h1 id="performance"><a class="header" href="#performance">Performance</a></h1>
 <p>A few notes on performance.</p>
-<h2 id="avoid-string-conversions"><a class="header" href="#avoid-string-conversions">Avoid String Conversions</a></h2>
-<p>Avoid unnecessary string conversions.</p>
-<p>Conversions from bytes to JavaScript strings and back are expensive. String data
-is typically represented at UTF-8, which is one to six bytes per unicode code
-point. JavaScript strings are represented in memory as UTF-16, or 16 bits or 32
-bits (2 bytes or 4 bytes) to represent one unicode code point. Conversion logic
-is non-trivial.</p>
-<p>Whenever possible, <code>proc</code> allows passing raw byte arrays between processes so
-conversion is optional.</p>
-<p>Do this:</p>
-<pre><code class="language-typescript">const lineCount = parseInt(
-  await read(&quot;warandpeace.txt&quot;).run(&quot;wc&quot;, &quot;-l&quot;).lines.first,
-  10,
-);
-</code></pre>
-<p>Not this. This will work, as the lines will automatically be converted back to
-UTF-8 before being passed to <code>wc -l</code> (which counts lines). However, this makes
-the V8 engine do a lot of extra work and slows down execution.</p>
-<pre><code class="language-typescript">const lineCount = parseInt(
-  await read(&quot;warandpeace.txt&quot;).lines.run(&quot;wc&quot;, &quot;-l&quot;).lines.first,
-  10,
-);
-</code></pre>
-<h2 id="asynchronous-code"><a class="header" href="#asynchronous-code">Asynchronous Code</a></h2>
-<p>Asynchronous code is fast, but it's not as fast as code using for-loops, arrays,
-and simple types.</p>
-<p>Given what it is doing, V8 does a stellar job of optimizing asynchronous code.
-Most of the time, you shouldn't have to worry about performance of code written
-this way. However, <code>async</code>/<code>await</code> isn't (quite) a zero-cost abstraction.</p>
-<p>When performance is a concern and data size allows, it may be more performant to
-move operations to in-memory arrays. Code that does lots of small operations or
-works on very small data can usually be reworked into non-asynchronous code for
-better performance.</p>
-<p>Keep in mind that code written using promises, <code>AsyncIterable</code>, and
-<code>async</code>/<code>await</code> is going to be very well optimized and run quickly. A <em>lot</em> of
-work went into making promise code run as quickly as possible in V8. Write clean
-code first and measure your performance before you start trying to hand-optimize
-things.</p>
+<h2 id="does-performance-matter"><a class="header" href="#does-performance-matter">Does Performance Matter?</a></h2>
+<p>For 90% of the code you write, the bottom line is that performance does not
+matter. For example, if you have some code that reads configuration on startup
+and dumps it into an object, that code might be complicated, but it won't matter
+if it runs in 10 milliseconds or 100 nanoseconds. Write clear code first and
+optimize once things are working. Follow this process, and you will quickly
+figure out which things do and don't matter.</p>
+<h2 id="the-cost-of-iteration"><a class="header" href="#the-cost-of-iteration">The Cost of Iteration</a></h2>
+<p>We use iteration everywhere. Doing it wrong can kill your performance. Doing it
+right can get you close to (single threaded) C performance. This is a quick
+summary of what you can expect. To keep it short, I am just going to cover the
+high points and not show my work.</p>
+<p>The fastest code you can write in pure JavaScript looks like
+<a href="https://en.wikipedia.org/wiki/Asm.js">asm.js</a>. If you stick to <code>for</code> loops that
+count and index simple types or data object lookups in arrays or numbers in
+typed-arrays (like <code>Uint8Array</code>), you can expect that code to run at or near
+single-threaded C speed.</p>
+<p>Expect <code>for...of</code> with iterables and generators to be about 10x slower. This
+includes array methods like <code>map</code>, <code>filter</code>, and <code>reduce</code>. Anything that has to
+call a function in a loop is going to have extra overhead.</p>
+<p>Promise-driven asynchronous code is another 10x slower, or 100x slower than the
+<code>asm.js</code>-style code. This affects code written using <code>proc</code>, particularly
+<code>Enumerable</code>.</p>
+<p>So does this mean you have to always use <code>asm.js</code> syntax? Not at all. <code>for...of</code>
+syntax and array methods make for cleaner code, and asynchronous operations are
+the whole reason we're here. Iteration performance is mostly about the inner
+loops. If your inner loops are tight, a little less efficiency in the outer
+loops won't matter much. Write clean code first. When things are working, look
+for opportunities to make it faster. Often this will mean a little profiling and
+rewriting a few routines in <code>asm.js</code> style. If you do it right, you should be
+able to get very good performance along with readable code.</p>
 <p><a href="https://medium.com/netscape/async-iterators-these-promises-are-killing-my-performance-4767df03d85b">Async Iterators: These Promises Are Killing My Performance!</a>
 on Medium and supporting benchmarks in
 <a href="https://github.com/danvk/async-iteration">async-iteration</a> on Github.</p>