Skip to content

Commit

Permalink
regenerate docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@wilk
wilk committed Oct 15, 2018
1 parent 4065731 commit c4b7531
Show file tree
Hide file tree
Showing 4 changed files with 64 additions and 19 deletions.
16 changes: 12 additions & 4 deletions docs/API.html
View file
Expand Up @@ -193,14 +193,22 @@ <h2 id="job">job</h2>
}
</code></pre>
<p>To know how to use it, please refer to the <a href="GUIDE.html#sync-job">Job Guide</a></p>
<h2 id="start">start</h2>
<p><strong>start</strong> can be required directly from microjob:</p>
<pre><code class="lang-js"><span class="hljs-keyword">const</span> {start} = <span class="hljs-built_in">require</span>(<span class="hljs-string">&apos;microjob&apos;</span>)
</code></pre>
<p>Its signature:</p>
<pre><code class="lang-ts"><span class="hljs-function"><span class="hljs-keyword">function</span> <span class="hljs-title">start</span>(<span class="hljs-params"></span>): <span class="hljs-title">Promise</span>&lt;<span class="hljs-title">void</span>&gt;</span>;
</code></pre>
<p>To know how to use it, please refer to the <a href="GUIDE.html#setup">Setup Guide</a></p>
<h2 id="stop">stop</h2>
<p><strong>stop</strong> can be required directly from microjob:</p>
<pre><code class="lang-js"><span class="hljs-keyword">const</span> {stop} = <span class="hljs-built_in">require</span>(<span class="hljs-string">&apos;microjob&apos;</span>)
</code></pre>
<p>It&apos;s a function with this signature:</p>
<pre><code class="lang-ts"><span class="hljs-function"><span class="hljs-keyword">function</span> <span class="hljs-title">stop</span>(<span class="hljs-params"></span>): <span class="hljs-title">void</span>
</span></code></pre>
<p>To know how to use it, please refer to the <a href="GUIDE.html#graceful-shutdown">Teardown Guide</a></p>
<pre><code class="lang-ts"><span class="hljs-function"><span class="hljs-keyword">function</span> <span class="hljs-title">stop</span>(<span class="hljs-params"></span>): <span class="hljs-title">Promise</span>&lt;<span class="hljs-title">void</span>&gt;</span>;
</code></pre>
<p>To know how to use it, please refer to the <a href="GUIDE.html#forceful-shutdown">Teardown Guide</a></p>


</section>
Expand Down Expand Up @@ -240,7 +248,7 @@ <h1 class="search-results-title">No results matching "<span class='search-query'
<script>
var gitbook = gitbook || [];
gitbook.push(function() {
gitbook.page.hasChanged({"page":{"title":"API","level":"1.1.2","depth":2,"previous":{"title":"Guide","level":"1.1.1","depth":2,"path":"GUIDE.md","ref":"GUIDE.md","articles":[]},"dir":"ltr"},"config":{"gitbook":"*","theme":"default","variables":{},"plugins":[],"pluginsConfig":{"highlight":{},"search":{},"lunr":{"maxIndexSize":1000000,"ignoreSpecialCharacters":false},"sharing":{"facebook":true,"twitter":true,"google":false,"weibo":false,"instapaper":false,"vk":false,"all":["facebook","google","twitter","weibo","instapaper"]},"fontsettings":{"theme":"white","family":"sans","size":2},"theme-default":{"styles":{"website":"styles/website.css","pdf":"styles/pdf.css","epub":"styles/epub.css","mobi":"styles/mobi.css","ebook":"styles/ebook.css","print":"styles/print.css"},"showLevel":false}},"structure":{"langs":"LANGS.md","readme":"README.md","glossary":"GLOSSARY.md","summary":"SUMMARY.md"},"pdf":{"pageNumbers":true,"fontSize":12,"fontFamily":"Arial","paperSize":"a4","chapterMark":"pagebreak","pageBreaksBefore":"/","margin":{"right":62,"left":62,"top":56,"bottom":56}},"styles":{"website":"styles/website.css","pdf":"styles/pdf.css","epub":"styles/epub.css","mobi":"styles/mobi.css","ebook":"styles/ebook.css","print":"styles/print.css"}},"file":{"path":"API.md","mtime":"2018-10-02T21:08:33.795Z","type":"markdown"},"gitbook":{"version":"3.2.3","time":"2018-10-02T21:09:29.433Z"},"basePath":".","book":{"language":""}});
gitbook.page.hasChanged({"page":{"title":"API","level":"1.1.2","depth":2,"previous":{"title":"Guide","level":"1.1.1","depth":2,"path":"GUIDE.md","ref":"GUIDE.md","articles":[]},"dir":"ltr"},"config":{"gitbook":"*","theme":"default","variables":{},"plugins":[],"pluginsConfig":{"highlight":{},"search":{},"lunr":{"maxIndexSize":1000000,"ignoreSpecialCharacters":false},"sharing":{"facebook":true,"twitter":true,"google":false,"weibo":false,"instapaper":false,"vk":false,"all":["facebook","google","twitter","weibo","instapaper"]},"fontsettings":{"theme":"white","family":"sans","size":2},"theme-default":{"styles":{"website":"styles/website.css","pdf":"styles/pdf.css","epub":"styles/epub.css","mobi":"styles/mobi.css","ebook":"styles/ebook.css","print":"styles/print.css"},"showLevel":false}},"structure":{"langs":"LANGS.md","readme":"README.md","glossary":"GLOSSARY.md","summary":"SUMMARY.md"},"pdf":{"pageNumbers":true,"fontSize":12,"fontFamily":"Arial","paperSize":"a4","chapterMark":"pagebreak","pageBreaksBefore":"/","margin":{"right":62,"left":62,"top":56,"bottom":56}},"styles":{"website":"styles/website.css","pdf":"styles/pdf.css","epub":"styles/epub.css","mobi":"styles/mobi.css","ebook":"styles/ebook.css","print":"styles/print.css"}},"file":{"path":"API.md","mtime":"2018-10-15T06:46:56.799Z","type":"markdown"},"gitbook":{"version":"3.2.3","time":"2018-10-15T06:47:04.589Z"},"basePath":".","book":{"language":""}});
});
</script>
</div>
Expand Down
49 changes: 41 additions & 8 deletions docs/GUIDE.html
View file
Expand Up @@ -190,13 +190,33 @@ <h2 id="worker-pool">Worker Pool</h2>
<pre><code class="lang-bash">$ <span class="hljs-built_in">export</span> MAX_WORKERS=10; node --experimental-worker index.js
</code></pre>
<p>Invoking <code>job</code> on a function will put it on a task queue and then, when a worker is available, it will be executed, returning the desired result or an error.</p>
<h2 id="setup">Setup</h2>
<p>Before working with microjob you need to boot the worker pool:</p>
<pre><code class="lang-js">(<span class="hljs-keyword">async</span> () =&gt; {
<span class="hljs-keyword">const</span> { start } = <span class="hljs-built_in">require</span>(<span class="hljs-string">&apos;microjob&apos;</span>)

<span class="hljs-keyword">try</span> {
<span class="hljs-comment">// start worker pool</span>
<span class="hljs-keyword">await</span> start()

<span class="hljs-comment">// ...</span>
} <span class="hljs-keyword">catch</span> (err) {
<span class="hljs-built_in">console</span>.error(err)
}
})()
</code></pre>
<p><code>start</code> returns a promise and it will be resolved when all the threads are up and running, available to consume the internal jobs queue.</p>
<p>It&apos;s a good practice to await <code>start</code> thus to avoid race conditions.</p>
<h2 id="sync-job">Sync job</h2>
<p>The common and most used example is the sync job.
A sync job is just a function working in background, in another thread, avoiding to block the main thread with heavy CPU load, made of sync function calls.</p>
<pre><code class="lang-js">(<span class="hljs-keyword">async</span> () =&gt; {
<span class="hljs-keyword">const</span> { job } = <span class="hljs-built_in">require</span>(<span class="hljs-string">&apos;microjob&apos;</span>)
<span class="hljs-keyword">const</span> { start, job } = <span class="hljs-built_in">require</span>(<span class="hljs-string">&apos;microjob&apos;</span>)

<span class="hljs-keyword">try</span> {
<span class="hljs-comment">// start worker pool</span>
<span class="hljs-keyword">await</span> start()

<span class="hljs-comment">// this function will be executed in another thread</span>
<span class="hljs-keyword">const</span> res = <span class="hljs-keyword">await</span> job(() =&gt; {
<span class="hljs-keyword">let</span> i = <span class="hljs-number">0</span>
Expand All @@ -218,9 +238,12 @@ <h2 id="sync-job">Sync job</h2>
<h2 id="async-job">Async job</h2>
<p>An asynchronous job is a task with at least one async call: for instance, a query to a DB, a HTTP request, a file system call, etc, and of course plus a heavy CPU load.</p>
<pre><code class="lang-js">(<span class="hljs-keyword">async</span> () =&gt; {
<span class="hljs-keyword">const</span> { job } = <span class="hljs-built_in">require</span>(<span class="hljs-string">&apos;microjob&apos;</span>)
<span class="hljs-keyword">const</span> { start, job } = <span class="hljs-built_in">require</span>(<span class="hljs-string">&apos;microjob&apos;</span>)

<span class="hljs-keyword">try</span> {
<span class="hljs-comment">// start worker pool</span>
<span class="hljs-keyword">await</span> start()

<span class="hljs-comment">// this function will be executed in another thread</span>
<span class="hljs-keyword">const</span> res = <span class="hljs-keyword">await</span> job(<span class="hljs-keyword">async</span> () =&gt; {
<span class="hljs-keyword">let</span> i = <span class="hljs-number">0</span>
Expand All @@ -244,9 +267,12 @@ <h2 id="async-job">Async job</h2>
<h2 id="job-data">Job data</h2>
<p>Passing custom data to the job is quite easy as calling a function:</p>
<pre><code class="lang-js">(<span class="hljs-keyword">async</span> () =&gt; {
<span class="hljs-keyword">const</span> { job } = <span class="hljs-built_in">require</span>(<span class="hljs-string">&apos;microjob&apos;</span>)
<span class="hljs-keyword">const</span> { start, job } = <span class="hljs-built_in">require</span>(<span class="hljs-string">&apos;microjob&apos;</span>)

<span class="hljs-keyword">try</span> {
<span class="hljs-comment">// start worker pool</span>
<span class="hljs-keyword">await</span> start()

<span class="hljs-comment">// this function will be executed in another thread</span>
<span class="hljs-keyword">const</span> res = <span class="hljs-keyword">await</span> job(data =&gt; {
<span class="hljs-keyword">let</span> i = <span class="hljs-number">0</span>
Expand All @@ -268,9 +294,12 @@ <h2 id="job-context">Job context</h2>
An attacker could perform a JS injection as described <a href="https://github.com/wilk/microjob/issues/2" target="_blank">in this issue</a></strong></p>
<p>Achieving the same result can be done by passing the context object:</p>
<pre><code class="lang-js">(<span class="hljs-keyword">async</span> () =&gt; {
<span class="hljs-keyword">const</span> { job } = <span class="hljs-built_in">require</span>(<span class="hljs-string">&apos;microjob&apos;</span>)
<span class="hljs-keyword">const</span> { start, job } = <span class="hljs-built_in">require</span>(<span class="hljs-string">&apos;microjob&apos;</span>)

<span class="hljs-keyword">try</span> {
<span class="hljs-comment">// start worker pool</span>
<span class="hljs-keyword">await</span> start()

<span class="hljs-comment">// this function will be executed in another thread</span>
<span class="hljs-keyword">const</span> counter = <span class="hljs-number">1000000</span>
<span class="hljs-keyword">const</span> res = <span class="hljs-keyword">await</span> job(() =&gt; {
Expand All @@ -289,9 +318,12 @@ <h2 id="job-context">Job context</h2>
<h2 id="forceful-shutdown">Forceful shutdown</h2>
<p>When you don&apos;t need microjob anymore, you can shut it down with the <code>stop</code> function:</p>
<pre><code class="lang-js">(<span class="hljs-keyword">async</span> () =&gt; {
<span class="hljs-keyword">const</span> { job, stop } = <span class="hljs-built_in">require</span>(<span class="hljs-string">&apos;microjob&apos;</span>)
<span class="hljs-keyword">const</span> { start, job, stop } = <span class="hljs-built_in">require</span>(<span class="hljs-string">&apos;microjob&apos;</span>)

<span class="hljs-keyword">try</span> {
<span class="hljs-comment">// start worker pool</span>
<span class="hljs-keyword">await</span> start()

<span class="hljs-comment">// this function will be executed in another thread</span>
<span class="hljs-keyword">const</span> counter = <span class="hljs-number">1000000</span>
<span class="hljs-keyword">const</span> res = <span class="hljs-keyword">await</span> job(() =&gt; {
Expand All @@ -304,9 +336,10 @@ <h2 id="forceful-shutdown">Forceful shutdown</h2>
<span class="hljs-built_in">console</span>.log(res) <span class="hljs-comment">// 1000000</span>
} <span class="hljs-keyword">catch</span> (err) {
<span class="hljs-built_in">console</span>.error(err)
} <span class="hljs-keyword">finally</span> {
<span class="hljs-comment">// stop worker pool</span>
<span class="hljs-keyword">await</span> stop()
}

stop()
})()
</code></pre>
<p><code>stop</code> ensures that every worker of the worker pool is <a href="https://nodejs.org/api/worker_threads.html#worker_threads_worker_terminate_callback" target="_blank">terminated</a>.</p>
Expand Down Expand Up @@ -353,7 +386,7 @@ <h1 class="search-results-title">No results matching "<span class='search-query'
<script>
var gitbook = gitbook || [];
gitbook.push(function() {
gitbook.page.hasChanged({"page":{"title":"Guide","level":"1.1.1","depth":2,"next":{"title":"API","level":"1.1.2","depth":2,"path":"API.md","ref":"API.md","articles":[]},"previous":{"title":"Introduction","level":"1.1","depth":1,"path":"README.md","ref":"README.md","articles":[{"title":"Guide","level":"1.1.1","depth":2,"path":"GUIDE.md","ref":"GUIDE.md","articles":[]},{"title":"API","level":"1.1.2","depth":2,"path":"API.md","ref":"API.md","articles":[]}]},"dir":"ltr"},"config":{"gitbook":"*","theme":"default","variables":{},"plugins":[],"pluginsConfig":{"highlight":{},"search":{},"lunr":{"maxIndexSize":1000000,"ignoreSpecialCharacters":false},"sharing":{"facebook":true,"twitter":true,"google":false,"weibo":false,"instapaper":false,"vk":false,"all":["facebook","google","twitter","weibo","instapaper"]},"fontsettings":{"theme":"white","family":"sans","size":2},"theme-default":{"styles":{"website":"styles/website.css","pdf":"styles/pdf.css","epub":"styles/epub.css","mobi":"styles/mobi.css","ebook":"styles/ebook.css","print":"styles/print.css"},"showLevel":false}},"structure":{"langs":"LANGS.md","readme":"README.md","glossary":"GLOSSARY.md","summary":"SUMMARY.md"},"pdf":{"pageNumbers":true,"fontSize":12,"fontFamily":"Arial","paperSize":"a4","chapterMark":"pagebreak","pageBreaksBefore":"/","margin":{"right":62,"left":62,"top":56,"bottom":56}},"styles":{"website":"styles/website.css","pdf":"styles/pdf.css","epub":"styles/epub.css","mobi":"styles/mobi.css","ebook":"styles/ebook.css","print":"styles/print.css"}},"file":{"path":"GUIDE.md","mtime":"2018-10-01T13:44:28.182Z","type":"markdown"},"gitbook":{"version":"3.2.3","time":"2018-10-02T21:09:29.433Z"},"basePath":".","book":{"language":""}});
gitbook.page.hasChanged({"page":{"title":"Guide","level":"1.1.1","depth":2,"next":{"title":"API","level":"1.1.2","depth":2,"path":"API.md","ref":"API.md","articles":[]},"previous":{"title":"Introduction","level":"1.1","depth":1,"path":"README.md","ref":"README.md","articles":[{"title":"Guide","level":"1.1.1","depth":2,"path":"GUIDE.md","ref":"GUIDE.md","articles":[]},{"title":"API","level":"1.1.2","depth":2,"path":"API.md","ref":"API.md","articles":[]}]},"dir":"ltr"},"config":{"gitbook":"*","theme":"default","variables":{},"plugins":[],"pluginsConfig":{"highlight":{},"search":{},"lunr":{"maxIndexSize":1000000,"ignoreSpecialCharacters":false},"sharing":{"facebook":true,"twitter":true,"google":false,"weibo":false,"instapaper":false,"vk":false,"all":["facebook","google","twitter","weibo","instapaper"]},"fontsettings":{"theme":"white","family":"sans","size":2},"theme-default":{"styles":{"website":"styles/website.css","pdf":"styles/pdf.css","epub":"styles/epub.css","mobi":"styles/mobi.css","ebook":"styles/ebook.css","print":"styles/print.css"},"showLevel":false}},"structure":{"langs":"LANGS.md","readme":"README.md","glossary":"GLOSSARY.md","summary":"SUMMARY.md"},"pdf":{"pageNumbers":true,"fontSize":12,"fontFamily":"Arial","paperSize":"a4","chapterMark":"pagebreak","pageBreaksBefore":"/","margin":{"right":62,"left":62,"top":56,"bottom":56}},"styles":{"website":"styles/website.css","pdf":"styles/pdf.css","epub":"styles/epub.css","mobi":"styles/mobi.css","ebook":"styles/ebook.css","print":"styles/print.css"}},"file":{"path":"GUIDE.md","mtime":"2018-10-15T06:46:56.800Z","type":"markdown"},"gitbook":{"version":"3.2.3","time":"2018-10-15T06:47:04.589Z"},"basePath":".","book":{"language":""}});
});
</script>
</div>
Expand Down

0 comments on commit c4b7531

Please sign in to comment.