Simple-Mutex
Simple mutex is a small library that will help you to lock and wrap custom code like functions and variables. It will cycle between reads and writes, allowing all writes to return in order while queuing all reads. When all writes are complete, all the reads will be executed. This will give you a single threaded nature to your advantage.
Usage
Installation
$ npm install simple-mutex
Require
To use Simpel-Mutext you can simply require the module as follows:
var Lock = require('simple-mutext');
Using a lock
Parameter one of the "write" function will be a unique key name that you can use to read. Parameter two is a callback function witch contains your custom code. When your custom code execution is completed, you can release the lock for the reads to execute their own code (see example 1 for more details).
Lock.write('keyname', function(release) {
//Custom code goes here
//Release the lock
release();
});
Passing arguments to the read
if you want to give your read callback function more information about variables inside your write callback, then you can inject your variables inside the release parameters (see example 3 for more details).
Lock.write('keyname', function(release) {
var foo = 1;
//Release the lock and pass foo to the read callback
release(foo);
});
Using a read
A read will wait for all write functions to complete until it will be executed. The first parameter will be the same key name as the key name given to the write. The second parameter will be your custom callback function that will be executed when the write is completed (see example 1 for more details).
Lock.read('keyname', function() {
//Custom code
});
Your custom callback function will always be injected with an "info" variable as last argument (you can pass more custom arguments). This variable will give you information about the start time of the first read or write, the end time of the executions of all the reads and a total duration in milliseconds.
Lock.read('keyname', function(info) {
console.log(info);
/* Will output something similar to:
{ start: Date Object,
end: Date Object,
duration: 2002 } */
});
Using a read with an expiration date
If you set a duration in milliseconds for the third parameter of the "read" function, the read callback will not be executed if the write callback will not complete in time or the write callback is not created at all (see example 2 for more details).
Lock.read('keyname', function() {
console.log(a);
}, 1000);
important note
- If there is no release within a write callback then a read will by default wait 10 seconds before it deletes itself and will therefore not be executed.
- If you want to disable this, you can pass a duration of 0 milliseconds (no limit).
Examples
Example 1; simple
In this example, the read callback is going to wait 1 second for the write te complete.
var a = 1;
Lock.write('keyname', function(release) {
//Define new value for variable a
a = 2;
//Let the read function wait for 1 sec.
setTimeout(function() {
release();
}, 1000);
});
Lock.read('keyname', function() {
console.log(a); //output is 2
});
Example 2; using a expiration time
In this example, the read will expire after 1 second because the write is created after 2 seconds. Therefore, the read callback will never be executed
var a = 1;
Lock.read('keyname', function() {
console.log(a);
}, 1000);
setTimeout(function() {
Lock.write('keyname', function(release) {
//Define new value for variable a
a = 2;
release();
});
}, 2000);
Example 3; passing arguments to the read
In this example, the release callback in the write function will pass arguments for the read callback to use.
var a = 1;
Lock.write('keyname', function(release) {
a = 2;
var foo = '3';
var bar = '4';
release(foo, bar);
});
Lock.read('keyname', function(attempts, foo, bar) {
console.log(a, foo, bar); //Will output: 2, 3, 4
});