metarhia / web-locks

Web Locks API 🔒

Web Locks API

Web Locks API implementation for Node.js based on worker_threads, Atomics, SharedArrayBuffer, asynchronous functions, and queue.

See specification: wicg.github.io/web-locks/ and documentation: developer.mozilla.org/en-US/docs/Web/API/Lock

This implementation is a part of Metarhia technology stack, needed for the first pilot project of Node.js application server based on parallel programming and workload micro-isolation. Web Locks API is intended to be merged into Node.js in future.

Features

• Simplest parallel programming primitive to solve a problem of data races and race conditions.
• Node.js and worker_threads support.
• Different optimized implementations for certain cases: single-threaded asynchronous locks, multi-threaded locks with a single unifyed API.

Installation

$ npm install web-locks

Usage

await locks.request('Resource name', async lock => {
  // use named resource and release it after return
});

License

This implementation of Web Locks API is MIT licensed.

web-locks's Issues

Force resource release

This may looks like locks.release('A');

Add type definitions

Multi-threaded implementation

Priority in resource request queue

There can be two priority modes:

• all-threads - all request will be added with equal priority (thread independent);
• thread-first - if lock will leave resource in certain thread, all thread-local requests will be processed before passing resource to the different thread.

Such optimization may reduce message passing intensity between threads and improve performance.

Promise rejection is handled differently than in the browser

Describe the bug
In the browser, promise rejection in the callback causes the request method to reject. In node (this library), it results in an uncaught exception.

To Reproduce
Run this in the browser
await navigator.locks.request("test-key", async () => {throw new Error("stuff")}).catch(err => console.log("PROMISE REJECTED", err));

Run this in node
await locks.request("test-key", async () => {throw new Error("stuff")}).catch(err => console.log("PROMISE REJECTED", err));

Notice that we get a console log in the browser, but not in node.

Expected behavior
We should match the browser implementation.

Support windows

Add tests

• Options:
  • Mode: exclusive/shared
  • Abort signal
  • ifAvailable flag
• Nested locks
  • Simple usage
  • Deadlocks
  • Live locks
• Implementation switching
  • Single-threaded
  • Multi-threaded

Implement locking timeout

await locks.request('A', { timeout: 5000 }, async () => {
  // resource will be released if this function will not end before timeout
});

Lock abort

Implement:

• AbortSignal
• AbortError
• AbortController
• LockOptions { signal: controller.signal }

See: https://wicg.github.io/web-locks/

Implement Symbol usage for resource identification

await locks.request(Symbol('Resource name'), async lock => {
  // use named resource and release it after return
});

Implement better queue for the purposes of performance

Internaly web-locks uses default array as a queue and it can cause performance issues in case of drasticaly growing consumers amount.

The solution would be to replace current queue with more efficient implementation.

I propose to either use single-linked list or more perfomant implementation of array queue.

First approach would be to use my implementation of queue that can be found here.
Queue based on default array leads to O(n) time complexity of retrieving because of reindexing every other element in queue.
Single-linked list changes it to O(1) time consumption.

Another approach would be to use improved version of default array based queue from @datastructures-js/queue which also gives us O(1) time complexity but with additional memory consumption.

Benchmarks shows us that they both works much faster than original one.
Actually second one is a bit faster (on average) than first because of less memory allocation for each node of the queue.

Since performance of resource access is crucial in this plot I believe it's necessary to change the implementation.