Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/ncpa0cpl/mutex.js
Mutual Exclusion mechanism for Asynchronous JS Code.
https://github.com/ncpa0cpl/mutex.js
async async-await javascript mutex read-write-lock
Last synced: about 7 hours ago
JSON representation
Mutual Exclusion mechanism for Asynchronous JS Code.
- Host: GitHub
- URL: https://github.com/ncpa0cpl/mutex.js
- Owner: ncpa0cpl
- License: mit
- Created: 2021-12-03T15:02:51.000Z (almost 3 years ago)
- Default Branch: master
- Last Pushed: 2022-09-01T14:12:28.000Z (about 2 years ago)
- Last Synced: 2024-11-04T00:22:20.963Z (13 days ago)
- Topics: async, async-await, javascript, mutex, read-write-lock
- Language: TypeScript
- Homepage:
- Size: 84 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Mutex.js
Mutual Exclusion mechanism for Asynchronous JS Code.
## Mutex
Usage of the Mutex is plain and simple. Mutex class provided by this package has only two methods available, `acquire()` and `release()`.
- `acquire()` should be called and awaited before accessing the shared resource.
- `release()` should be called after acquiring and finishing the action on the shared resource.
### Example
The most simple usage of the Mutex class
```ts
import { Mutex } from "mutex.js";
class Foo {
private readonly mutex = new Mutex();
private sharedResource = {};
async actionOnResource() {
await this.mutex.acquire();
try {
// do something with `this.sharedResource`
} finally {
this.mutex.release();
}
}
}
```
A function that takes a callback and executes it with an acquired Mutex lock
```ts
import { Mutex } from "mutex.js";
const mutex = new Mutex();
async function transaction(callback: () => Promise) {
await mutex.acquire();
try {
return await callback();
} finally {
mutex.release();
}
}
// ...
const foo: string = await transaction(async () => {
// some async code
return "success";
});
```
## RWMutex
RWMutex (or read/write mutex) is specialized mutex type the allows for multiple read operations to happen simultaneously, but write operations are always atomic in relation to every other operation.
It works similarly to the regular Mutex, but each "acquire" and "release" must specify if the operation is a read or a write.
Methods it exposes are:
- `acquireWrite()` should be called and awaited before writing to the shared resource.
- `releaseWrite()` should be called after acquiring and finishing the write operation on the shared resource.
- `acquireRead()` should be called and awaited before reading the shared resource.
- `releaseRead()` should be called after acquiring and finishing the reading operation on the shared resource.
### Example
```ts
class DBConnection {
private mutex = new RWMutex();
// Writes to the DB
async insert() {
await this.mutex.acquireWrite();
try {
//
} finally {
this.mutex.releaseWrite();
}
}
// Read from the DB
async select() {
await this.mutex.acquireRead();
try {
//
} finally {
this.mutex.releaseRead();
}
}
}
```
## What's a Mutual Exclusion (ie. Mutex)?
> **Mutual exclusion** is a property of process synchronization which states that **_“no two processes can exist in the critical section at any given point of time”_**. The term was first coined by Djikstra. Any process synchronization technique being used must satisfy the property of mutual exclusion, without which it would not be possible to get rid of a race condition.
>
> Source:
In the context of this library this means that any code put between the `acquire()` and `release()` will only be executed if there is no other instance of code running that's also put between the `acquire()` and `release()` of the same Mutex object. And any attempts to run said code in that situation will be delayed until it is possible to run it, as per the mutual exclusion rule.