sharedmap
Version:
Multithreading-compatible SharedMap in vanilla JS
2,849 lines (771 loc) • 31.9 kB
HTML
<html lang="en">
<head>
<meta charset="utf-8">
<title>JSDoc: Global</title>
<script src="scripts/prettify/prettify.js"> </script>
<script src="scripts/prettify/lang-css.js"> </script>
<!--[if lt IE 9]>
<script src="//html5shiv.googlecode.com/svn/trunk/html5.js"></script>
<![endif]-->
<link type="text/css" rel="stylesheet" href="styles/prettify-tomorrow.css">
<link type="text/css" rel="stylesheet" href="styles/jsdoc-default.css">
</head>
<body>
<div id="main">
<h1 class="page-title">Global</h1>
<section>
<header>
<h2></h2>
</header>
<article>
<div class="container-overview">
<dl class="details">
</dl>
</div>
<h3 class="subsection-title">Members</h3>
<h4 class="name" id="length"><span class="type-signature"></span>length<span class="type-signature"></span></h4>
<div class="description">
Number of elements present
</div>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="index.js.html">index.js</a>, <a href="index.js.html#line133">line 133</a>
</li></ul></dd>
</dl>
<h4 class="name" id="size"><span class="type-signature"></span>size<span class="type-signature"></span></h4>
<div class="description">
Maximum number of elements allowed
</div>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="index.js.html">index.js</a>, <a href="index.js.html#line142">line 142</a>
</li></ul></dd>
</dl>
<h3 class="subsection-title">Methods</h3>
<h4 class="name" id="clear"><span class="type-signature"></span>clear<span class="signature">()</span><span class="type-signature"> → {void}</span></h4>
<div class="description">
Clear the SharedMap
</div>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="index.js.html">index.js</a>, <a href="index.js.html#line743">line 743</a>
</li></ul></dd>
</dl>
<h5>Returns:</h5>
<dl>
<dt>
Type
</dt>
<dd>
<span class="param-type">void</span>
</dd>
</dl>
<h4 class="name" id="delete"><span class="type-signature"></span>delete<span class="signature">(key, opt<span class="signature-attributes">opt</span>)</span><span class="type-signature"> → {void}</span></h4>
<div class="description">
Delete an element, fully thread-safe, acquires an exlusive lock and it is very expensive
</div>
<h5>Parameters:</h5>
<table class="params">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th>Attributes</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>key</code></td>
<td class="type">
<span class="param-type">string</span>
</td>
<td class="attributes">
</td>
<td class="description last"></td>
</tr>
<tr>
<td class="name"><code>opt</code></td>
<td class="type">
<span class="param-type"><a href="global.html#SharedMapOptions">SharedMapOptions</a></span>
</td>
<td class="attributes">
<optional><br>
</td>
<td class="description last">options, { lockExclusive: true } if manually calling lockExlusive</td>
</tr>
</tbody>
</table>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="index.js.html">index.js</a>, <a href="index.js.html#line576">line 576</a>
</li></ul></dd>
</dl>
<h5>Throws:</h5>
<ul>
<li>
<dl>
<dt>
<div class="param-desc">
when the key does not exit
</div>
</dt>
<dd></dd>
<dt>
<dl>
<dt>
Type
</dt>
<dd>
<span class="param-type">RangeError</span>
</dd>
</dl>
</dt>
<dd></dd>
</dl>
</li>
<li>
<dl>
<dt>
<div class="param-desc">
when calling map.delete(key, value, { lockWrite: true, lockExclusive: false })
</div>
</dt>
<dd></dd>
<dt>
<dl>
<dt>
Type
</dt>
<dd>
<span class="param-type">Error</span>
</dd>
</dl>
</dt>
<dd></dd>
</dl>
</li>
</ul>
<h5>Returns:</h5>
<dl>
<dt>
Type
</dt>
<dd>
<span class="param-type">void</span>
</dd>
</dl>
<h4 class="name" id="get"><span class="type-signature"></span>get<span class="signature">(key, opt<span class="signature-attributes">opt</span>)</span><span class="type-signature"> → {string|undefined}</span></h4>
<div class="description">
Get an element, fully thread-safe, multiple get/set can execute in parallel
</div>
<h5>Parameters:</h5>
<table class="params">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th>Attributes</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>key</code></td>
<td class="type">
<span class="param-type">string</span>
</td>
<td class="attributes">
</td>
<td class="description last"></td>
</tr>
<tr>
<td class="name"><code>opt</code></td>
<td class="type">
<span class="param-type"><a href="global.html#SharedMapOptions">SharedMapOptions</a></span>
</td>
<td class="attributes">
<optional><br>
</td>
<td class="description last">options, { lockWrite: true } if manually calling lockWrite</td>
</tr>
</tbody>
</table>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="index.js.html">index.js</a>, <a href="index.js.html#line514">line 514</a>
</li></ul></dd>
</dl>
<h5>Returns:</h5>
<dl>
<dt>
Type
</dt>
<dd>
<span class="param-type">string</span>
|
<span class="param-type">undefined</span>
</dd>
</dl>
<h4 class="name" id="has"><span class="type-signature"></span>has<span class="signature">(key, opt<span class="signature-attributes">opt</span>)</span><span class="type-signature"> → {boolean}</span></h4>
<div class="description">
Find an element, fully thread-safe, identical to get(key) !== undefined
</div>
<h5>Parameters:</h5>
<table class="params">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th>Attributes</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>key</code></td>
<td class="type">
<span class="param-type">string</span>
</td>
<td class="attributes">
</td>
<td class="description last"></td>
</tr>
<tr>
<td class="name"><code>opt</code></td>
<td class="type">
<span class="param-type"><a href="global.html#SharedMapOptions">SharedMapOptions</a></span>
</td>
<td class="attributes">
<optional><br>
</td>
<td class="description last">options, { lockWrite: true } if manually calling lockWrite</td>
</tr>
</tbody>
</table>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="index.js.html">index.js</a>, <a href="index.js.html#line552">line 552</a>
</li></ul></dd>
</dl>
<h5>Returns:</h5>
<dl>
<dt>
Type
</dt>
<dd>
<span class="param-type">boolean</span>
</dd>
</dl>
<h4 class="name" id="keys"><span class="type-signature">(generator) </span>keys<span class="signature">(opt<span class="signature-attributes">opt</span>)</span><span class="type-signature"> → {Iterable}</span></h4>
<div class="description">
A generator that can be used to iterate over the keys, thread-safe but allows
additions and deletions during the iteration
</div>
<h5>Parameters:</h5>
<table class="params">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th>Attributes</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>opt</code></td>
<td class="type">
<span class="param-type"><a href="global.html#SharedMapOptions">SharedMapOptions</a></span>
</td>
<td class="attributes">
<optional><br>
</td>
<td class="description last">options, { lockWrite: true } if manually calling lockWrite</td>
</tr>
</tbody>
</table>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="index.js.html">index.js</a>, <a href="index.js.html#line648">line 648</a>
</li></ul></dd>
</dl>
<h5>Returns:</h5>
<dl>
<dt>
Type
</dt>
<dd>
<span class="param-type">Iterable</span>
</dd>
</dl>
<h4 class="name" id="lockExclusive"><span class="type-signature"></span>lockExclusive<span class="signature">()</span><span class="type-signature"> → {void}</span></h4>
<div class="description">
Acquire an exclusive lock,
All operations that need it, automatically acquire it,
Use only if you need to block all other threads from accessing the map;
The thread holding the lock can then call map.set(k, v, {lockHeld: true})
</div>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="index.js.html">index.js</a>, <a href="index.js.html#line216">line 216</a>
</li></ul></dd>
</dl>
<h5>Returns:</h5>
<dl>
<dt>
Type
</dt>
<dd>
<span class="param-type">void</span>
</dd>
</dl>
<h4 class="name" id="lockWrite"><span class="type-signature"></span>lockWrite<span class="signature">()</span><span class="type-signature"> → {void}</span></h4>
<div class="description">
Acquire a write lock,
All operations that need it, automatically acquire it,
Use only if you need to block all other threads from writing to the map,
The thread holding the lock can then call map.set(k, v, {lockHeld: true})
</div>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="index.js.html">index.js</a>, <a href="index.js.html#line284">line 284</a>
</li></ul></dd>
</dl>
<h5>Returns:</h5>
<dl>
<dt>
Type
</dt>
<dd>
<span class="param-type">void</span>
</dd>
</dl>
<h5>Example</h5>
<pre class="prettyprint"><code>myMap.lockWrite();
for (let k of myMap.keys({lockWrite: true}))
myMap.set(k,
myMap.get(k, {lockWrite: true}).toUpperCase(),
{lockWrite: true});
myMap.unlockWrite();</code></pre>
<h4 class="name" id="map"><span class="type-signature"></span>map<span class="signature">(cb, thisArg<span class="signature-attributes">opt</span>)</span><span class="type-signature"> → {Array}</span></h4>
<div class="description">
A thread-safe map(). Doesn't block additions or deletions
between two calls of the callback,
all map operations are guaranteed atomic,
map.get(index)=currentValue is guaranteed while the callback runs,
You shall not manipulate the map in the callback, use an explicitly-locked
keys() in this case (look at the example for lockWrite)
</div>
<h5>Parameters:</h5>
<table class="params">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th>Attributes</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>cb</code></td>
<td class="type">
<span class="param-type"><a href="global.html#mapCallback">mapCallback</a></span>
</td>
<td class="attributes">
</td>
<td class="description last">callback</td>
</tr>
<tr>
<td class="name"><code>thisArg</code></td>
<td class="type">
<span class="param-type">*</span>
</td>
<td class="attributes">
<optional><br>
</td>
<td class="description last">callback will have its this set to thisArg</td>
</tr>
</tbody>
</table>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="index.js.html">index.js</a>, <a href="index.js.html#line680">line 680</a>
</li></ul></dd>
</dl>
<h5>Returns:</h5>
<dl>
<dt>
Type
</dt>
<dd>
<span class="param-type">Array</span>
</dd>
</dl>
<h4 class="name" id="reduce"><span class="type-signature"></span>reduce<span class="signature">(cb, initialValue)</span><span class="type-signature"> → {*}</span></h4>
<div class="description">
A thread-safe reduce(). Doesn't block additions or deletions
between two calls of the callback,
map.get(key)=currentValue is guaranteed while the callback runs,
You shall not manipulate the map in the callback, use an explicitly-locked
keys() in this case (look at the example for lockWrite)
</div>
<h5>Parameters:</h5>
<table class="params">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>cb</code></td>
<td class="type">
<span class="param-type"><a href="global.html#reduceCallback">reduceCallback</a></span>
</td>
<td class="description last">callback</td>
</tr>
<tr>
<td class="name"><code>initialValue</code></td>
<td class="type">
<span class="param-type">*</span>
</td>
<td class="description last">initial value of the accumulator</td>
</tr>
</tbody>
</table>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="index.js.html">index.js</a>, <a href="index.js.html#line721">line 721</a>
</li></ul></dd>
</dl>
<h5>Returns:</h5>
<dl>
<dt>
Type
</dt>
<dd>
<span class="param-type">*</span>
</dd>
</dl>
<h4 class="name" id="set"><span class="type-signature"></span>set<span class="signature">(key, value, opt<span class="signature-attributes">opt</span>)</span><span class="type-signature"> → {void}</span></h4>
<div class="description">
Add/replace an element, fully thread-safe, multiple get/set can execute in parallel
</div>
<h5>Parameters:</h5>
<table class="params">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th>Attributes</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>key</code></td>
<td class="type">
<span class="param-type">string</span>
</td>
<td class="attributes">
</td>
<td class="description last"></td>
</tr>
<tr>
<td class="name"><code>value</code></td>
<td class="type">
<span class="param-type">string</span>
|
<span class="param-type">number</span>
</td>
<td class="attributes">
</td>
<td class="description last"></td>
</tr>
<tr>
<td class="name"><code>opt</code></td>
<td class="type">
<span class="param-type"><a href="global.html#SharedMapOptions">SharedMapOptions</a></span>
</td>
<td class="attributes">
<optional><br>
</td>
<td class="description last">options, { lockWrite: true } if manually calling lockWrite</td>
</tr>
</tbody>
</table>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="index.js.html">index.js</a>, <a href="index.js.html#line444">line 444</a>
</li></ul></dd>
</dl>
<h5>Throws:</h5>
<ul>
<li>
<dl>
<dt>
<div class="param-desc">
when the map is full
</div>
</dt>
<dd></dd>
<dt>
<dl>
<dt>
Type
</dt>
<dd>
<span class="param-type">RangeError</span>
</dd>
</dl>
</dt>
<dd></dd>
</dl>
</li>
<li>
<dl>
<dt>
<div class="param-desc">
when the input values do not fit
</div>
</dt>
<dd></dd>
<dt>
<dl>
<dt>
Type
</dt>
<dd>
<span class="param-type">RangeError</span>
</dd>
</dl>
</dt>
<dd></dd>
</dl>
</li>
<li>
<dl>
<dt>
<div class="param-desc">
when the input values are of a wrong type
</div>
</dt>
<dd></dd>
<dt>
<dl>
<dt>
Type
</dt>
<dd>
<span class="param-type">TypeError</span>
</dd>
</dl>
</dt>
<dd></dd>
</dl>
</li>
</ul>
<h5>Returns:</h5>
<dl>
<dt>
Type
</dt>
<dd>
<span class="param-type">void</span>
</dd>
</dl>
<h4 class="name" id="unlockExclusive"><span class="type-signature"></span>unlockExclusive<span class="signature">()</span><span class="type-signature"> → {void}</span></h4>
<div class="description">
Release the exclusive lock
</div>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="index.js.html">index.js</a>, <a href="index.js.html#line224">line 224</a>
</li></ul></dd>
</dl>
<h5>Returns:</h5>
<dl>
<dt>
Type
</dt>
<dd>
<span class="param-type">void</span>
</dd>
</dl>
<h4 class="name" id="unlockWrite"><span class="type-signature"></span>unlockWrite<span class="signature">()</span><span class="type-signature"> → {void}</span></h4>
<div class="description">
Release the write lock
</div>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="index.js.html">index.js</a>, <a href="index.js.html#line293">line 293</a>
</li></ul></dd>
</dl>
<h5>Returns:</h5>
<dl>
<dt>
Type
</dt>
<dd>
<span class="param-type">void</span>
</dd>
</dl>
<h3 class="subsection-title">Type Definitions</h3>
<h4 class="name" id="mapCallback"><span class="type-signature"></span>mapCallback<span class="signature">(currentValue, key<span class="signature-attributes">opt</span>)</span><span class="type-signature"></span></h4>
<h5>Parameters:</h5>
<table class="params">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th>Attributes</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>currentValue</code></td>
<td class="type">
<span class="param-type">string</span>
</td>
<td class="attributes">
</td>
<td class="description last"></td>
</tr>
<tr>
<td class="name"><code>key</code></td>
<td class="type">
<span class="param-type">string</span>
</td>
<td class="attributes">
<optional><br>
</td>
<td class="description last"></td>
</tr>
</tbody>
</table>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="index.js.html">index.js</a>, <a href="index.js.html#line658">line 658</a>
</li></ul></dd>
</dl>
<h4 class="name" id="reduceCallback"><span class="type-signature"></span>reduceCallback<span class="signature">(accumulator, currentValue, key<span class="signature-attributes">opt</span>)</span><span class="type-signature"></span></h4>
<h5>Parameters:</h5>
<table class="params">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th>Attributes</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>accumulator</code></td>
<td class="type">
</td>
<td class="attributes">
</td>
<td class="description last"></td>
</tr>
<tr>
<td class="name"><code>currentValue</code></td>
<td class="type">
<span class="param-type">string</span>
</td>
<td class="attributes">
</td>
<td class="description last"></td>
</tr>
<tr>
<td class="name"><code>key</code></td>
<td class="type">
<span class="param-type">string</span>
</td>
<td class="attributes">
<optional><br>
</td>
<td class="description last"></td>
</tr>
</tbody>
</table>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="index.js.html">index.js</a>, <a href="index.js.html#line698">line 698</a>
</li></ul></dd>
</dl>
<h4 class="name" id="SharedMapOptions">SharedMapOptions</h4>
<h5>Type:</h5>
<ul>
<li>
<span class="param-type">object</span>
</li>
</ul>
<h5 class="subsection-title">Properties:</h5>
<table class="props">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>lockWrite</code></td>
<td class="type">
<span class="param-type">boolean</span>
</td>
<td class="description last">Already holding write lock, useful when manually locking with lockWrite</td>
</tr>
<tr>
<td class="name"><code>lockExclusive</code></td>
<td class="type">
<span class="param-type">boolean</span>
</td>
<td class="description last">Already holding exclusive lock, useful when manually locking with lockExclusive</td>
</tr>
</tbody>
</table>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="index.js.html">index.js</a>, <a href="index.js.html#line427">line 427</a>
</li></ul></dd>
</dl>
</article>
</section>
</div>
<nav>
<h2><a href="index.html">Home</a></h2><h3>Classes</h3><ul><li><a href="module.exports.html">exports</a></li></ul><h3>Global</h3><ul><li><a href="global.html#clear">clear</a></li><li><a href="global.html#delete">delete</a></li><li><a href="global.html#get">get</a></li><li><a href="global.html#has">has</a></li><li><a href="global.html#keys">keys</a></li><li><a href="global.html#length">length</a></li><li><a href="global.html#lockExclusive">lockExclusive</a></li><li><a href="global.html#lockWrite">lockWrite</a></li><li><a href="global.html#map">map</a></li><li><a href="global.html#reduce">reduce</a></li><li><a href="global.html#set">set</a></li><li><a href="global.html#size">size</a></li><li><a href="global.html#unlockExclusive">unlockExclusive</a></li><li><a href="global.html#unlockWrite">unlockWrite</a></li></ul>
</nav>
<br class="clear">
<footer>
Documentation generated by <a href="https://github.com/jsdoc/jsdoc">JSDoc 3.6.5</a> on Sat Aug 22 2020 12:09:51 GMT+0200 (Central European Summer Time)
</footer>
<script> prettyPrint(); </script>
<script src="scripts/linenumber.js"> </script>
</body>
</html>