Abstract Class: MutexDriver

The base class of the lock drivers: it acquires, releases and renews the locks in a store shared by their holders. A Mutex creates its driver from its driver option and adds the waiting, the automatic renewal and the lost locks; a custom subclass cannot be given to it. The drivers are exported to use a store directly (scripts, tests): they neither wait nor renew, and their errors are the clients' errors, not a MutexDriverException.

Example

import {MemoryMutexDriver, type DriverLock, type MutexDriver} from 'lakutata/com/mutex'

async function once(driver: MutexDriver, name: string, work: () => Promise<void>): Promise<boolean> {
    const lock: DriverLock | undefined = await driver.acquire(name, 10000)
    if (!lock) return false
    try {
        await work()
    } finally {
        await driver.release(name, lock)
    }
    return true
}

const driver: MutexDriver = new MemoryMutexDriver('script:')
console.log(await once(driver, 'migrate', async (): Promise<void> => undefined))
await driver.close()

Extended by

• MemoryMutexDriver
• FileMutexDriver
• RedisMutexDriver
• PostgresMutexDriver
• MysqlMutexDriver

Constructors

Constructor

new MutexDriver(): MutexDriver

Returns

MutexDriver

Properties

expiring

abstract readonly expiring: boolean

Whether the locks expire after their ttl unless renewed: true for the memory, file and Redis drivers and the table mode; false for the advisory locks of PostgreSQL and MySQL, which end with their connection instead.

---

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

Methods

acquire()

abstract acquire(name, ttl): Promise<DriverLock | undefined>

Try to acquire a lock once, without waiting.

Parameters

name

string

The lock name; the driver's prefix is added to it in the store.

ttl

number

How long the lock stays held without a renewal, in milliseconds (ignored by the advisory locks).

Returns

Promise<DriverLock | undefined>

The lock granted, or undefined when another holder has it.

Throws

When the client package of the driver is not installed.

---

close()

abstract close(): Promise<void>

Close the driver's connections; the advisory locks they hold are released by the database. The driver is not meant to be used after it.

Returns

Promise<void>

---

extend()

abstract extend(name, lock, ttl): Promise<boolean>

Renew a lock for ttl milliseconds from now, when the store still has it for this holder; for the advisory locks, check that it is still held.

Parameters

name

string

The lock name, as acquired.

lock

DriverLock

The lock returned by MutexDriver.acquire.

ttl

number

How long the lock stays held without another renewal, in milliseconds.

Returns

Promise<boolean>

Whether the lock is still held by this holder.

---

release()

abstract release(name, lock): Promise<boolean>

Release a lock, when the store still has it for this holder.

Parameters

name

string

The lock name, as acquired.

lock

DriverLock

The lock returned by MutexDriver.acquire.

Returns

Promise<boolean>

Whether it was released: false when the store no longer has it for this holder (expired, taken, or its connection closed).