A Web Locks API implementation for Node.js
npm install piscina-locksPiscina-locks is an implementation of the [Web Locks API][] for Node.js.
The Web Locks API allows code to acquire a lock, perform work while the lock
is held, then have the lock automatically released when the work is complete.
Written using TypeScript and N-API.
For Node.js 12.x and higher.
[MIT Licensed][].
``js
const { request } = require('piscina-locks');
const { setTimeout } = require('timers/promises');
(async function() {
return await request('resource', async (lock) => {
await setTimeout(1000);
return lock.name;
});
})();
`
Using workers:
`js
const { request } = require('piscina-locks');
const { Worker, isMainThread } = require('worker_threads');
const { promisify } = require('util');
const sleep = promisify(setTimeout);
request('shared-resource', async () => {
console.log(isMainThread);
await sleep(1000);
});
if (isMainThread) {
// eslint-disable-next-line no-new
new Worker(__filename);
}
`
* name (string) The name of the lock to acquire.options
* (object)mode
* (string) Must be 'exclusive' or 'shared'. Defaults to'exclusive'
. There can be only one holder of an 'exclusive''shared'
lock at a time but multiple holders of locks.ifAvailable
* (boolean) When true, the request will fail iffalse
the lock cannot be granted immediately. Defaults to .steal
* (boolean) When true, any existing held locks are releasedAbortError
and the associated Promises rejected with an and thefalse
requested lock will be granted. Defaults to .signal
* (AbortSignal | EventEmitter) An AbortSignal that cancallback
be used to cancel a pending lock request.
* (function) Invoked when the lock is acquired. The callbackLock
is invoked with the granted as the only argument. If ifAvailabletrue
is and the lock is not available, the argument will be null. The
callback may be a regular function or an async function.
Returns a Promise that resolves with the return value of callback afterLock
the granted is released. The Promise will be rejected if the lockcallback
request is canceled, the granted lock is stolen, or throws.
* Returns objectpending
* (object[])name
* (string)mode
* (string)held
* (object[])name
* (string)mode
* (string)
The query()` method is a diagnostic utility that lists the pending lock
requests and currently held locks. It is useful for debugging purposes only.
* James M Snell
Piscina development is sponsored by [NearForm Research][].
[MIT Licensed]: LICENSE.md
[NearForm Research]: https://www.nearform.com/research/
[Web Locks API]: https://developer.mozilla.org/en-US/docs/Web/API/Web_Locks_API