General utilities

The Asyncmux class and AsyncmuxLock APIs. Signatures of lock and rLock, lock options, and release rules.

Asyncmux class

Manages per-key independent locks and global locks that conflict with every lock.

import { Asyncmux } from "asyncmux";

const mux = new Asyncmux();

constructor()

constructor(options?: AsyncmuxOptions);

Initializes the instance with the given options. Each instance holds independent lock state.

lock()

lock(): Promise<AsyncmuxLock>;

Acquires a keyless write lock (global write lock). It conflicts with every lock in the instance.

lock(key)

lock(key: string): Promise<AsyncmuxLock>;

Acquires the write lock for the given key. It conflicts with locks on the same key and coexists with locks on different keys.

lock(options)

lock(options: AsyncmuxLockOptions): Promise<AsyncmuxLock>;

Acquires a write lock with a key and an AbortSignal specified via options. Omitting key results in a global write lock.

using _ = await mux.lock({ key: "user:42", signal: controller.signal });

rLock()

rLock(): Promise<AsyncmuxLock>;

Acquires a keyless read lock (global read lock). It conflicts with every write lock and coexists with read locks.

rLock(key)

rLock(key: string): Promise<AsyncmuxLock>;

Acquires the read lock for the given key. It conflicts with write locks on the same key, while read locks coexist with each other.

rLock(options)

rLock(options: AsyncmuxLockOptions): Promise<AsyncmuxLock>;

Acquires a read lock with a key and an AbortSignal specified via options. Omitting key results in a global read lock.

Common behavior

lock and rLock always return a Promise that resolves with an AsyncmuxLock.

• While a conflicting lock is held, the request waits. Waiting requests are processed in arrival order.
• When signal is aborted, the request is removed from the queue and rejects with signal.reason.
• By default, reentrancy is not detected. Holding a lock on a key and acquiring it again deadlocks. Enabling preventReentrancy throws ReentrantLockError instead.

See Keyed locks for conflict details.

AsyncmuxOptions

Options passed to the Asyncmux class constructor.

AsyncmuxLockOptions

Options for lock and rLock.

AsyncmuxLock class

Represents an acquired lock. Instances are only obtained as return values of each API; the constructor is internal.

released

Returns whether the lock has been released.

get released(): boolean;

release()

Releases the lock. Calling it twice on the same lock throws LockReleasedError. Even when the release handling throws, the lock is treated as released.

release(): void;

[Symbol.dispose]()

Implements automatic release via the using syntax. Does nothing when already released.

[Symbol.dispose](): void;

{
  using _ = await mux.lock("key");
  // release() is called when leaving the scope.
}

See also

• Keyed locks
• Manual locking
• Aborting