sharedmap
Version:
Multithreading-compatible SharedMap in vanilla JS
2,513 lines (721 loc) • 28.5 kB
HTML
<html lang="en">
<head>
<meta charset="utf-8">
<title>JSDoc: Class: SharedMap</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">Class: SharedMap</h1>
<section>
<header>
<h2><span class="attribs"><span class="type-signature"></span></span>SharedMap<span class="signature">(maxSize, keySize, objSize)</span><span class="type-signature"> → {<a href="SharedMap.html">SharedMap</a>}</span></h2>
<div class="class-description">SharedMap
zero-dependency
high-performance
unordered
Vanilla JS implementation of SharedMap,
a synchronous multi-threading capable,
fine-grain-locked with deadlock recovery,
static memory allocated,
coalesced-chaining HashMap,
backed by SharedArrayBuffer
that supports deleting
and is capable of auto-defragmenting itself on delete unless almost full
compatible with both Node.js and SharedArrayBuffer-enabled browsers</div>
</header>
<article>
<div class="container-overview">
<h2>Constructor</h2>
<h4 class="name" id="SharedMap"><span class="type-signature"></span>new SharedMap<span class="signature">(maxSize, keySize, objSize)</span><span class="type-signature"> → {<a href="SharedMap.html">SharedMap</a>}</span></h4>
<div class="description">
Creates a new SharedMap
</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>maxSize</code></td>
<td class="type">
<span class="param-type">number</span>
</td>
<td class="description last">Maximum number of entries</td>
</tr>
<tr>
<td class="name"><code>keySize</code></td>
<td class="type">
<span class="param-type">number</span>
</td>
<td class="description last">Maximum length of keys in UTF-16 codepoints</td>
</tr>
<tr>
<td class="name"><code>objSize</code></td>
<td class="type">
<span class="param-type">number</span>
</td>
<td class="description last">Maximum length of values in UTF-16 codepoints</td>
</tr>
</tbody>
</table>
<dl class="details">
<dt class="tag-author">Author:</dt>
<dd class="tag-author">
<ul>
<li><a href="mailto:momtchil@momtchev.com">Momtchil Momtchev</a></li>
</ul>
</dd>
<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#line96">line 96</a>
</li></ul></dd>
<dt class="tag-see">See:</dt>
<dd class="tag-see">
<ul>
<li><a href="http://github.com/mmomtchev/SharedMap">http://github.com/mmomtchev/SharedMap</a></li>
</ul>
</dd>
</dl>
<h5>Returns:</h5>
<dl>
<dt>
Type
</dt>
<dd>
<span class="param-type"><a href="SharedMap.html">SharedMap</a></span>
</dd>
</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#line741">line 741</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#line574">line 574</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#line512">line 512</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#line550">line 550</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#line646">line 646</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#line678">line 678</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#line719">line 719</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#line442">line 442</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>
</article>
</section>
</div>
<nav>
<h2><a href="index.html">Home</a></h2><h3>Classes</h3><ul><li><a href="SharedMap.html">SharedMap</a></li></ul><h3><a href="global.html">Global</a></h3>
</nav>
<br class="clear">
<footer>
Documentation generated by <a href="https://github.com/jsdoc/jsdoc">JSDoc 3.6.4</a> on Mon Jun 08 2020 20:47:05 GMT+0200 (Central European Summer Time)
</footer>
<script> prettyPrint(); </script>
<script src="scripts/linenumber.js"> </script>
</body>
</html>