General Utilities

Summary

The General Utilities API allows for mutual exclusion (locking) on a per-resource basis using key strings. Additionally, omitting the key allows for global mutual exclusion across all resources. These lock objects are not limited to class methods and can be used anywhere in your code.

WARNING

While General Utilities offer more flexibility than class-method-based locking, haphazard use can lead to unnecessary overhead or make the code difficult to maintain.

API

Asyncmux

The Asyncmux class creates a lock object used to acquire read/write locks. The scope of mutual exclusion is limited to the specific lock object returned.

Signature

class Asyncmux {
  lock(key?: string): Promise<Disposable & {
    unlock(): void;
  }>;
  lock(
    options: {
      key?: string;
      signal?: AbortSignal;
    }
  ): Promise<Disposable & {
    unlock(): void;
  }>;

  rLock(key?: string): Promise<Disposable & {
    unlock(): void;
  }>;
  rLock(
    options: {
      key?: string;
      signal?: AbortSignal;
    }
  ): Promise<Disposable & {
    unlock(): void;
  }>;
};

Return Value

A lock object used to acquire read/write locks.

Example

import { Asyncmux } from "asyncmux";

const mux = new Asyncmux();

---

mux.lock()

The mux.lock() method acquires a write lock for all resources (global lock).

Signature

function lock(): Promise<Disposable & {
  unlock(): void;
}>;

Return Value

A Promise that resolves to an unlocker object. To release the lock, use the using statement or call the .unlock() method on this object. Note that .unlock() cannot be called again after the lock has been released.

Example

The following example uses the using statement to acquire a write lock.

import { Asyncmux } from "asyncmux";

const mux = new Asyncmux();

{
  using _ = await mux.lock();
}

The following example manually acquires and releases a write lock.

import { Asyncmux } from "asyncmux";

const mux = new Asyncmux();
const lock = await mux.lock();
try {
  // ...
} finally {
  lock.unlock();
}

---

mux.lock(key)

The mux.lock(key) method acquires a write lock for a specific resource.

Signature

function lock(key: string): Promise<Disposable & {
  unlock(): void;
}>;

Arguments

key

• Type: string
• The key string identifying the resource to lock.

Return Value

A Promise that resolves to an unlocker object. Release the lock using the using statement or by calling .unlock().

Example

import { Asyncmux } from "asyncmux";

const mux = new Asyncmux();

{
  using _ = await mux.lock("resource(1)");
}

---

mux.lock(options)

The mux.lock(options) method acquires a write lock for either a specific resource or all resources, with additional control.

Signature

function lock(
  options: {
    key?: string;
    signal?: AbortSignal;
  },
): Promise<Disposable & {
  unlock(): void;
}>;

Arguments

options.key

• Type: string
• The key string identifying the resource to lock.

options.signal

• Type: AbortSignal
• An abort signal used to cancel the lock acquisition.

Return Value

A Promise that resolves to an unlocker object.

Example

import { Asyncmux } from "asyncmux";

const mux = new Asyncmux();
const ac = new AbortController();

{
  using _ = await mux.lock({ key: "resource(1)", signal: ac.signal });
}

---

mux.rLock()

The mux.rLock() method acquires a read lock for all resources.

Signature

function rLock(): Promise<Disposable & {
  unlock(): void;
}>;

Return Value

A Promise that resolves to an unlocker object.

Example

import { Asyncmux } from "asyncmux";

const mux = new Asyncmux();

{
  using _ = await mux.rLock();
}

---

mux.rLock(key)

The mux.rLock(key) method acquires a read lock for a specific resource.

Signature

function rLock(key: string): Promise<Disposable & {
  unlock(): void;
}>;

Arguments

key

• Type: string
• The key string identifying the resource to lock.

Example

import { Asyncmux } from "asyncmux";

const mux = new Asyncmux();
const lock = await mux.rLock("resource(1)");
try {
  // ...
} finally {
  lock.unlock();
}

---

mux.rLock(options)

The mux.rLock(options) method acquires a read lock for either a specific resource or all resources.

Signature

function rLock(
  options: {
    key?: string;
    signal?: AbortSignal;
  },
): Promise<Disposable & {
  unlock(): void;
}>;

Arguments

options.key

• Type: string
• The key string identifying the target resource.

options.signal

• Type: AbortSignal
• An abort signal used to cancel the lock acquisition.

Example

import { Asyncmux } from "asyncmux";

const mux = new Asyncmux();
const ac = new AbortController();

const lock = await mux.rLock({ signal: ac.signal });
try {
  // ...
} finally {
  lock.unlock();
}