Class: FileMutexDriver
The file driver ({type: 'file'}): each lock is a file of a directory, created exclusively, shared by the processes of one host using the same directory and prefix (several workers or applications of a machine). It needs no package. The processes must share the directory: the default one (lakutata-mutex in the operating system's temporary directory) can differ between users. A directory shared by several hosts (a network file system) works only as far as its exclusive creation and renames are atomic, and only the expiration then frees the lock of a crashed host.
The locks expire after their ttl unless renewed; a lock whose process is gone on this host is taken over at once, without waiting for its expiration. The driver gives no fencing token (fence is undefined).
Example
import {FileMutexDriver, type DriverLock} from 'lakutata/com/mutex'
//The workers of this machine run the migration one at a time
const driver: FileMutexDriver = new FileMutexDriver('/var/lock/my-app', 'my-app:')
const lock: DriverLock | undefined = await driver.acquire('migrate', 60000)
if (lock) {
try {
console.log('migrating')
} finally {
await driver.release('migrate', lock)
}
}Extends
Constructors
Constructor
new FileMutexDriver(
directory,prefix?):FileMutexDriver
Create a driver on a directory, created at the first acquisition when it does not exist.
Parameters
directory
string
The directory of the lock files.
prefix?
string
The prefix added to the lock names; '' by default.
Returns
FileMutexDriver
Overrides
Properties
expiring
readonlyexpiring:boolean
true: the locks expire after their ttl unless renewed.
Overrides
onLost
onLost: (
names) =>void
Called with the names of the locks the driver lost at once, when the connection holding advisory locks closes or fails. A Mutex sets it; it does nothing by default.
Parameters
names
string[]
Returns
void
Inherited from
Methods
acquire()
acquire(
name,ttl):Promise<DriverLock|undefined>
Try to acquire a lock once: create its file exclusively, or take over a file expired, abandoned, or whose process of this host is gone.
Parameters
name
string
The lock name.
ttl
number
How long the lock stays held without a renewal, in milliseconds.
Returns
Promise<DriverLock | undefined>
The lock (without fencing token), or undefined when another holder has it.
Throws
When the directory cannot be created or the file written (permissions, disk full).
Overrides
close()
close():
Promise<void>
Do nothing: the driver keeps no file open; the lock files stay until they are released or taken over.
Returns
Promise<void>
Overrides
extend()
extend(
name,lock,ttl):Promise<boolean>
Renew a lock whose file still holds this holder's token, for ttl milliseconds from now: the file is taken away (renamed), checked, rewritten and given back without replacing a lock another process acquired meanwhile (the renewal fails then). A lock expired is not renewed (lost), even when no other process took it over yet.
Parameters
name
string
The lock name.
lock
The lock acquired.
ttl
number
How long the lock stays held without another renewal, in milliseconds.
Returns
Promise<boolean>
Whether it was renewed.
Overrides
release()
release(
name,lock):Promise<boolean>
Release a lock by removing its file, when the file still holds this holder's token.
Parameters
name
string
The lock name.
lock
The lock acquired.
Returns
Promise<boolean>
Whether it was released.