semafour
Node.js semaphore with synchronous and asynchronous APIs. semafour
uses named semaphores, and can be used to achieve synchronization across multiple processes.
Currently not supported on Windows.
Example
const sem = Semafour.create({ name: '/sem', value: 1 });
// Acquire semaphore asynchronously.
sem.wait((err) => {
// Perform some activity that requires synchronization.
// Release semaphore synchronously.
sem.postSync();
// Delete the semaphore synchronously.
sem.unlinkSync();
});
API
Semafour(options)
constructor
- Arguments
-
options
(object) - A configuration object with the following schema:-
name
(string) - Name for the semaphore. This is global to the operating system. -
value
(number) - An unsigned integer representing the initial value of the semaphore. Optional. Defaults to0
. -
create
(boolean) - Whenfalse
, a new semaphore is created if one does not already exist with the providedname
. If a semaphore already exists with the same name, it will be used. Whencreate
istrue
, an error is thrown if the named semaphore already exists. Defaults totrue
.
-
-
Constructs a new semaphore. Must be called with new
.
Semafour.create(options)
- Arguments
-
options
(object) - A configuration object with the following schema:-
name
(string) - Name for the semaphore. This is global to the operating system. -
value
(number) - An unsigned integer representing the initial value of the semaphore. Optional. Defaults to0
.
-
-
- Returns
-
semaphore
(object) - A semaphore object representing a newly created named semaphore.
-
Factory function used to construct semaphores with create
equal to true
. This is the preferred way to create new semaphores.
Semafour.use(options)
- Arguments
-
options
(object) - A configuration object with the following schema:-
name
(string) - Name for the semaphore. This is global to the operating system. -
value
(number) - An unsigned integer representing the initial value of the semaphore. If the semaphore already exists,value
is ignored. Optional. Defaults to0
.
-
-
- Returns
-
semaphore
(object) - A semaphore object representing a newly created or existing named semaphore.
-
Factory function used to construct semaphores with create
equal to false
. This is the preferred way to retrieve existing semaphores.
Semafour.prototype.post(callback)
- Arguments
-
callback(err)
(function) - Callback function, which takes an error argument.
-
- Returns
- Nothing
Posts the semaphore, and invokes callback
. Any errors that occur are passed to the callback function.
Semafour.prototype.postSync()
- Arguments
- None
- Returns
- Nothing
Posts the semaphore synchronously. Throws if an error occurs.
Semafour.prototype.wait(callback)
- Arguments
-
callback(err)
(function) - Callback function, which takes an error argument.
-
- Returns
- Nothing
Acquires the semaphore asynchronously. The wait operation is performed on a separate thread in the libuv thread pool to avoid blocking the event loop. Once the semaphore is acquired, the callback is invoked. Any errors that occur are passed to the callback function.
Semafour.prototype.waitSync()
- Arguments
- None
- Returns
- Nothing
Acquires the semaphore synchronously. The wait operation is performed on the main thread, and will block the event loop until the semaphore is acquired. Throws if an error occurs.
Semafour.prototype.tryWait()
- Arguments
-
callback(err, acquired)
(function) - Callback function, which takes an error argument, and a boolean that istrue
when the semaphore is acquired, and false otherwise.
-
- Returns
- Nothing
Tries to acquire the semaphore asynchronously. The tryWait operation is performed on the main thread. Calls the provided callback with the results of the lock acquisition, and errors, if any.
Semafour.prototype.tryWaitSync()
- Arguments
- None
- Returns
- A boolean that is true if the semaphore was acquired, and false otherwise.
Tries to acquire the semaphore synchronously. The tryWait operation is performed on the main thread. Throws if an error occurs.
Semafour.prototype.unlink(callback)
- Arguments
-
callback(err)
(function) - Callback function, which takes an error argument.
-
- Returns
- Nothing
Unlinks the semaphore, and invokes callback
. Any errors that occur are passed to the callback function. The semaphore is not destroyed until it is closed by all other processes that have it open.
Semafour.prototype.unlinkSync()
- Arguments
- None
- Returns
- Nothing
Unlinks the semaphore synchronously. Throws if an error occurs. The semaphore is not destroyed until it is closed by all other processes that have it open.
Semafour.prototype.close(callback)
- Arguments
-
callback(err)
(function) - Callback function, which takes an error argument.
-
- Returns
- Nothing
Closes the semaphore, and invokes callback
. Any errors that occur are passed to the callback function.
Semafour.prototype.closeSync()
- Arguments
- None
- Returns
- Nothing
Closes the semaphore synchronously. Throws if an error occurs.