Class: MutexLock
A lock held, returned by Mutex.acquire and Mutex.tryAcquire (and given to the function of Mutex.synchronized); the component creates it. It stays held until it is released (once: the next releases do nothing) or lost; the component renews it in the store meanwhile. Declared with await using, it is released at the end of its scope.
Its MutexLock.signal is aborted when it is lost: a renewal found it expired or taken by another holder, a renewal failed, or the connection holding it closed. A lost lock is not released in the store: another holder may get it once it expires. The work it protects should stop then, and the writes it makes may carry its MutexLock.fence so that the store refuses the writes of an older holder.
Example
import type {Mutex, MutexLock} from 'lakutata/com/mutex'
declare const mutex: Mutex
declare function writeReport(fence: number | undefined, signal: AbortSignal): Promise<void>
await using lock: MutexLock = await mutex.acquire('report:daily')
lock.signal.addEventListener('abort', (): void => console.warn(`lost: ${lock.signal.reason}`))
await writeReport(lock.fence, lock.signal)
console.log(lock.held, Date.now() - lock.acquiredAt.getTime())Implements
AsyncDisposable
Constructors
Constructor
new MutexLock(
name,token,fence,actions):MutexLock
Create a held lock (the component does it, when the store grants a lock).
Parameters
name
string
The lock name, without the component's prefix.
token
string
The random token identifying this holder in the store.
fence
number | undefined
The fencing token given by the store, or undefined when the driver gives none.
actions
How the component releases and renews the lock.
extend
(lock, ttl?) => Promise<boolean>
release
(lock) => Promise<boolean>
Returns
MutexLock
Properties
acquiredAt
readonlyacquiredAt:Date
When the lock was acquired (the time this object was created, once the store granted it).
fence
readonlyfence:number|undefined
name
readonlyname:string
token
readonlytoken:string
Accessors
held
Get Signature
get held():
boolean
Whether the lock is still held: false once it is released or lost. It reflects what the component knows; an expiring lock whose renewal is late may already be expired in the store.
Returns
boolean
signal
Get Signature
get signal():
AbortSignal
Aborted when the lock is lost, with a MutexLostException as its reason: a renewal found it expired or taken, a renewal failed, or the connection holding it closed. The work the lock protects should stop then. It is not aborted by a release.
Returns
AbortSignal
Methods
[asyncDispose]()
[asyncDispose]():
Promise<void>
Release the lock at the end of an await using scope, as MutexLock.release does.
Returns
Promise<void>
Throws
When the store fails.
Implementation of
AsyncDisposable.[asyncDispose]
extend()
extend(
ttl?):Promise<boolean>
Renew the lock now, for ttl milliseconds from now; the component already renews it automatically every third of its ttl. A ttl given here is used by the next automatic renewals too, their interval following it. For the advisory locks (which do not expire), it checks that the lock is still held by a query on its connection.
Parameters
ttl?
number
How long the lock stays held without a renewal, in milliseconds; the lock's last ttl (the one of its acquisition) by default.
Returns
Promise<boolean>
Whether the lock is still held; when the store no longer has it, the lock is marked lost (its signal aborted) and false is returned.
Throws
When the store fails (the lock is not marked lost then).
lose()
lose(
reason):void
Mark the lock as lost and abort its signal with the reason; the component calls it when a renewal fails or the connection holding the lock closes. It does nothing on a lock no longer held, and it does not release the lock in the store nor stop its renewal: the applications do not call it.
Parameters
reason
Error
The signal's abort reason, a MutexLostException from the component.
Returns
void
release()
release():
Promise<boolean>
Release the lock in the store and stop its renewal. Only the first call releases it; the next ones, and the calls on a lost lock, return false without reaching the store. The lock no longer counts as held even when the store fails, in which case it stays in the store until it expires.
Returns
Promise<boolean>
Whether the store still had the lock for this holder (false when it had expired, been taken, or its connection had closed).
Throws
When the store fails.