mutual-exclusion (mutex)
Mutual Exclusion (mutex) object for JavaScript.
Motivation
Promised based mutex allows to sequentially perform the same asynchronous operation. A typical use case example is checking if a resource exists and reading/ creating resource as an atomic asynchronous operation.
Suppose that you have a HTTP service that upon request downloads and serves an image. A naive implementation might look something like this:
router;
In the above example, if two requests are made at near the same time, then both of them will identify that temporaryFileExists
is false
and at least one of them will fail. Mutex solves this problem by limiting concurrent execution of several asynchronous operations (see Image server example).
API
;; /** * Thrown in case of `holdTimeout`. */HoldTimeoutError; /** * Thrown in case of `waitTimeout`. */WaitTimeoutError; const mutex: MutexType = ; async { // Lock is acquired. await mutex; // Lock is released. mutex; // false}
Configuration
MutexConfigurationInputType
(at the mutex-level) and LockConfigurationInputType
(at the individual lock-level) can be used to configure the scope and timeouts.
/** * @property holdTimeout The maximum amount of time lock can be held (default: 30000). * @property key Used to scope mutex (default: a random generated value). * @property waitTimeout The maximum amount of time lock can be waited for (default: 5000). */type MutexConfigurationInputType = | +holdTimeout?: number +key?: string +waitTimeout?: number|; type LockConfigurationInputType = | +holdTimeout?: number +key?: string +waitTimeout?: number|;
Usage examples
Image server example
Motivation section of the documentation demonstrates a flawed implementation of an image proxy server. That same service can utilise Mutex to solve the illustrated problem:
router;
Related libraries
- await-mutex – Similar implementation to mutual-exclusion, but without separation by
key
and timeouts.