165 lines
4.0 KiB
Markdown
165 lines
4.0 KiB
Markdown
# nlocks
|
|
|
|
A Node.js library providing asynchronous locking mechanisms including in-memory locks and file-based locks for coordinating access to resources across concurrent processes.
|
|
|
|
## Features
|
|
|
|
- **AsyncLock**: In-memory asynchronous lock for coordinating access to resources within a single process
|
|
- **FileLock**: File-based lock for coordinating access to resources across multiple processes
|
|
- **TCPLock**: TCP-based distributed lock for coordinating access to resources across multiple machines
|
|
- Lightweight and easy to use
|
|
- Promise-based API
|
|
- Comprehensive test coverage
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
npm install nlocks
|
|
```
|
|
|
|
## Usage
|
|
|
|
### Via index.js (recommended)
|
|
|
|
```javascript
|
|
const { AsyncLock, FileLock } = require('nlocks');
|
|
|
|
const asyncLock = new AsyncLock();
|
|
const fileLock = new FileLock();
|
|
```
|
|
|
|
### AsyncLock
|
|
|
|
An in-memory lock for synchronizing async operations within a single Node.js process:
|
|
|
|
```javascript
|
|
const AsyncLock = require('nlocks/async-lock');
|
|
|
|
const lock = new AsyncLock();
|
|
|
|
async function protectedOperation() {
|
|
await lock.acquire();
|
|
try {
|
|
// Your critical section code here
|
|
console.log('Performing protected operation');
|
|
await someAsyncWork();
|
|
} finally {
|
|
lock.release();
|
|
}
|
|
}
|
|
```
|
|
|
|
### FileLock
|
|
|
|
A file-based lock for synchronizing operations across multiple Node.js processes:
|
|
|
|
```javascript
|
|
const FileLock = require('nlocks/file-lock');
|
|
|
|
const lock = new FileLock();
|
|
|
|
async function fileProtectedOperation() {
|
|
await lock.acquire('/path/to/your/file.txt');
|
|
try {
|
|
// Your file operation code here
|
|
console.log('Performing file operation');
|
|
await someFileAsyncWork();
|
|
} finally {
|
|
lock.release('/path/to/your/file.txt');
|
|
}
|
|
}
|
|
```
|
|
|
|
### TCPLock
|
|
|
|
A TCP-based distributed lock for synchronizing operations across multiple machines:
|
|
|
|
#### Server side
|
|
|
|
```javascript
|
|
const TCPLockServer = require('nlocks/lock.tcp');
|
|
|
|
// Create and start a TCP lock server
|
|
const server = new TCPLockServer({
|
|
host: '0.0.0.0', // Listen host
|
|
port: 7301 // Listen port
|
|
});
|
|
|
|
server.start();
|
|
```
|
|
|
|
#### Client side
|
|
|
|
```javascript
|
|
const TcpRwLock = require('nlocks/lock-client.tcp');
|
|
|
|
// Create a TCP lock client
|
|
const lock = new TcpRwLock('resource-name', {
|
|
connect: {
|
|
host: 'localhost', // Server host
|
|
port: 7301 // Server port
|
|
}
|
|
});
|
|
|
|
async function tcpProtectedOperation() {
|
|
await lock.connect(); // Connect to the lock server
|
|
try {
|
|
await lock.readLock(); // Acquire a read lock
|
|
// Or use await lock.writeLock(); for a write lock
|
|
|
|
// Your critical section code here
|
|
console.log('Performing protected operation');
|
|
await someAsyncWork();
|
|
} finally {
|
|
await lock.unlock(); // Release the lock
|
|
await lock.close(); // Disconnect from server
|
|
}
|
|
}
|
|
```
|
|
|
|
## API
|
|
|
|
### AsyncLock
|
|
|
|
- `new AsyncLock()` - Creates a new AsyncLock instance
|
|
- `acquire(): Promise<void>` - Acquires the lock
|
|
- `release(): void` - Releases the lock
|
|
|
|
### FileLock
|
|
|
|
- `new FileLock()` - Creates a new FileLock instance
|
|
- `acquire(filePath): Promise<void>` - Acquires a lock for the specified file path
|
|
- `release(filePath): void` - Releases the lock for the specified file path
|
|
|
|
### TCPLock
|
|
|
|
#### Server
|
|
|
|
- `new TCPLockServer(options)` - Creates a new TCP lock server instance
|
|
- `options.host`: Host to listen on (default: '0.0.0.0')
|
|
- `options.port`: Port to listen on (default: 7301)
|
|
- `start(): void` - Starts the lock server
|
|
- `stop(): void` - Stops the lock server
|
|
|
|
#### Client
|
|
|
|
- `new TcpRwLock(resource, options)` - Creates a new TCP lock client instance
|
|
- `resource`: Name of the resource to lock
|
|
- `options.connect.host`: Server hostname to connect to (default: 'localhost')
|
|
- `options.connect.port`: Server port to connect to (default: 7301)
|
|
- `connect(): Promise<void>` - Connects to the lock server
|
|
- `readLock(): Promise<void>` - Acquires a read lock
|
|
- `writeLock(): Promise<void>` - Acquires a write lock
|
|
- `unlock(): Promise<void>` - Releases the currently held lock
|
|
|
|
## Testing
|
|
|
|
Run the test suite with:
|
|
|
|
```bash
|
|
npm test
|
|
```
|
|
|
|
## License
|
|
|
|
[MIT](LICENSE) |