diff --git a/README.md b/README.md index 24b919a..de8f18a 100644 --- a/README.md +++ b/README.md @@ -6,6 +6,7 @@ A Node.js library providing asynchronous locking mechanisms including in-memory - **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 @@ -69,6 +70,53 @@ async function fileProtectedOperation() { } ``` +### 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 @@ -83,6 +131,27 @@ async function fileProtectedOperation() { - `acquire(filePath): Promise` - 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` - Connects to the lock server +- `readLock(): Promise` - Acquires a read lock +- `writeLock(): Promise` - Acquires a write lock +- `unlock(): Promise` - Releases the currently held lock + ## Testing Run the test suite with: diff --git a/lock-client.js b/lock-client.js index fe4833c..645e020 100644 --- a/lock-client.js +++ b/lock-client.js @@ -135,6 +135,9 @@ class LockClient extends EventEmitter { this.cleanup(); this._logger.debug(`Lock released for resource: ${this.resource}`); } + async release(){ + await this.unlock(); + }