readwrite-lock

Read/Write locks on asynchronous code

Installation

npm install readwrite-lock

Readwrite lock rules:

• There may be one or more readers at a time
• There may be only one writer at a time
• Attempts to acquire read lock are queued as long as a write lock is taken
• Attempts to acquire write lock are queued as long as at least one read lock is taken

Features

• Uses ES6 promises
• Individual or an array of lock keys supported
• Timeout supported
• Pending task limit supported

Why you need locking on single threaded nodejs?

Nodejs is single threaded, and the code execution is never get interrupted inside an event loop, so locking is unnecessary? This is true ONLY IF your critical section can be executed inside a single event loop. However, if you have any async code inside your critical section (it can be simply triggered by any I/O operation, or timer), your critical logic will across multiple event loops, therefore it's not concurrency safe!

Consider the following code

redis.get('key', function(err, value){
    redis.set('key', value * 2);
});

The above code simply multiply a redis key by 2. However, if two users run concurrency, the execution order may like this

user1: redis.get('key') -> 1
user2: redis.get('key') -> 1
user1: redis.set('key', 1 x 2) -> 2
user2: redis.set('key', 1 x 2) -> 2

Obviously it's not what you expected

With readwriteLock, you can easily write your async critical section

lock.acquireWrite('key', () => {
    // Concurrency safe
    return new Promise((resolve, reject) => {
        redis.get('key', (err, value) => {
            redis.set('key', value * 2, (err, value) => {
                if (err) {
                    reject(err);
                } else {
                    resolve();
                }
            });
        });
    });
}).then((result) => {
}).catch((err) => {
});

Why read/write locking?

Read locks run concurrently, while write locks run exclusively. This is useful when working with multiple async IO calls to modify a resource. Consider the below example of how read write locks can help organize your async nodejs app. This is of course could be fixed using better coding rather than locks, it is only used as an example of what can happen when using asynchronous IO in NodeJS.

function concatHtml() {
    return new Promise((resolve, reject) => {
        htmlDownload("https://www.google.com", googleHtml => {
            fs.writeFile('concat_html.txt', googleHtml, () => {
                htmlDownload("https://www.github.com", githubHtml => {
                    fs.appendFile('concat_html.txt', githubHtml, () => resolve());
                });
            });
        });
    });
}

function readHtml() {
    return new Promise((resolve, reject) => {
        fs.readFile('concat_html.txt', result => resolve(result))
    });
}

user1: concatHtml()
user2: readHtml() -> only googleHtml found in file
user3: readHtml() -> googleHtml + githubHtml found in file

With readwriteLock, you can make sure that read locks can run concurrently as long as no writes are queued up. Likewise, writes block all reads until they are completed.

lock.acquireWrite('key', () => {
    // no other locks exist when this is running
    return concatHtml();
}).then(result => {
}).catch(err => {
});

lock.acquireRead('key', () => {
    // runs parallel with other read locks
    return readHtml();
}).then(result => {
}).catch(err => {
});

lock.acquireRead('key', () => {
    // runs parallel with other read locks
    return readHtml();
}).then(result => {
}).catch(err => {
});

Getting Started

var ReadwriteLock = require('readwrite-lock');
var lock = new ReadwriteLock();

/**
 * @param {String|Array} key 	resource key or keys to lock
 * @param {function} fn 	execute function
 * @param {Object} opts 	(optional) options
 */
lock.acquireRead(key, () => {
    // critical section
    // return value or promise
}, opts).then(() => {
    // continue execution outside critical section
    // NOTE: LOCK IS RELEASED AS SOON AS CRITICAL SECTION RETURNS
    //       there is no guaranteed order of this "then()" call
    //       compared to other recently released locks of same key
});

/**
 * @param {String|Array} key 	resource key or keys to lock
 * @param {function} fn 	execute function
 * @param {Object} opts 	(optional) options
 */
lock.acquireWrite(key, () => {
    // critical section
    // return value or promise
}, opts).then(() => {
    // continue execution outside critical section
    // NOTE: LOCK IS RELEASED AS SOON AS CRITICAL SECTION RETURNS
    //       there is no guaranteed order of this "then()" call
    //       compared to other recently released locks of same key
});

Error Handling

lock.acquireRead(key, () => {
    throw new Error('error');
}).catch(err => {
    console.log(err.message); // output: error
});


lock.acquireWrite(key, () => {
    throw new Error('error');
}).catch(err => {
    console.log(err.message); // output: error
});

Acquire multiple keys

lock.acquireRead([key1, key2], fn)
    .then(() => {
        // no longer in critical section
    })
    .catch(err => {
        console.log(err.message);
    });

lock.acquireWrite([key1, key2], fn)
    .then(() => {
        // no longer in critical section
    })
    .catch(err => {
        console.log(err.message);
    });

Options

// Specify timeout
var lock = new ReadwriteLock({timeout : 5000});
lock.acquireRead(key, () => {
    // critical section will never be entered if timeout occurs
}).catch(err => {
    // timed out error will be returned here if lock not acquired in given time
});
lock.acquireWrite(key, () => {
    // critical section will never be entered if timeout occurs
}).catch(err => {
    // timed out error will be returned here if lock not acquired in given time
});

// Set max pending tasks
var lock = new ReadwriteLock({maxPending : 1000});
lock.acquireRead(key, () => {
    // critical section will never be entered if pending limit reached
}).catch(err => {
    // too many pending tasks error will be returned here if lock not acquired in given time
});
lock.acquireWrite(key, () => {
    // critical section will never be entered if pending limit reached
}).catch(err => {
    // too many pending tasks error will be returned here if lock not acquired in given time
});

// Whether there is any running or pending async function
lock.isBusy();

// Use your own promise library instead of the global Promise variable
var lock = new ReadwriteLock({Promise : require('bluebird')}); // Bluebird
var lock = new ReadwriteLock({Promise : require('q').Promise}); // Q

Issues

See isse tracker.

License

MIT, see LICENSE