IF Commons GitHub

lock

Written to: 1 requirement: 1 proved, 0 partly, 0 failing, 0 with no test recorded. 0001-system FR-015

One run at a time (commons 0001-system FR-015): a lock file made only where none exists (O_EXCL, which every file system and operating system gives atomically, where flock has no node: form), holding who holds it (process id, command, since when). A waiting run polls until it is free, says once who it waits for, and takes over a lock whose holder's process no longer runs. A child of a holder can inherit the lock through an environment variable instead of waiting for its own parent. Taken from Stolos's src/archon/core/lock.ts, which locked through the runtime's own file lock.

import { acquireLock } from "./lock.ts";
const held = await acquireLock("/run/app.lock", { wait: true, command: "update", onWait: (h) => console.log(`waiting for ${h?.command}`) });
try {
  // the work
} finally {
  held?.release();
}

Source: commons/system/src/lock.ts

4 of 14 exports are imported by a test of the run. A test that imports an export may not call it or check what it returns.

locknamespace
namespace lock
lock.Holdertypeno test imports it
type Holder = { readonly pid: number; readonly command: string; readonly since: string; readonly token: string };

Who holds a lock.

lock.LockOptionstypeno test imports it
type LockOptions = { /** Wait until it is free (polling), or give up at once. */ readonly wait: boolean; /** What … (931 characters)
type LockOptions = {
  /** Wait until it is free (polling), or give up at once. */
  readonly wait: boolean;
  /** What the holder runs, said to whoever waits. */
  readonly command?: string;
  /** Called once, with the holder where it can be read, when the lock is not free. */
  readonly onWait?: (holder: Holder | undefined) => void;
  /** How often a waiting run looks again (250 ms by default). */
  readonly pollMs?: number;
  /** The variable that says a parent already holds the lock (no variable by default); it is set while the lock is held. */
  readonly inheritEnv?: string;
  /** How long a waiting run waits before it gives up and returns nothing (no limit by default). */
  readonly timeoutMs?: number;
  /** How old a lock file that cannot be read must be before it counts as abandoned (2 s by default): a file just made by a run that has not finished writing it is not. */
  readonly unreadableGraceMs?: number;
};

How to take a lock.

lock.Heldtypeno test imports it
type Held = {
  /** Who holds it: this process. */
  readonly holder: Holder;
  /** The lock given back (the file removed where it is still this holder's); safe to call twice. */
  release(): void;
};

A lock taken.

lock.processRunsfunctionno test imports it
function processRuns(pid: number): boolean

Whether a process runs: a signal of 0 checks without sending one. A process of another account counts as running.

lock.readHolderfunctionno test imports it
function readHolder(path: string): Promise<Holder | undefined>

Who holds the lock at path, where its file can be read; whether that process still runs is not checked here.

lock.describeHolderfunctionno test imports it
function describeHolder(h: Holder, now?: number): string

A holder as a person reads it: update (pid 4242, for 3m 12s).

lock.acquireLockfunctionno test imports it
function acquireLock(path: string, options: LockOptions): Promise<Held | undefined>

The lock at path taken, or undefined where it is held by a running process and wait is false (or timeoutMs passed). A lock whose holder no longer runs, or whose file cannot be read, is taken over. Where inheritEnv is set in the environment, a parent holds it, and it is given at once (its release does nothing).

Holdertypeno test imports it
type Holder = { readonly pid: number; readonly command: string; readonly since: string; readonly token: string };

Who holds a lock.

LockOptionstypeno test imports it
type LockOptions = { /** Wait until it is free (polling), or give up at once. */ readonly wait: boolean; /** What … (931 characters)
type LockOptions = {
  /** Wait until it is free (polling), or give up at once. */
  readonly wait: boolean;
  /** What the holder runs, said to whoever waits. */
  readonly command?: string;
  /** Called once, with the holder where it can be read, when the lock is not free. */
  readonly onWait?: (holder: Holder | undefined) => void;
  /** How often a waiting run looks again (250 ms by default). */
  readonly pollMs?: number;
  /** The variable that says a parent already holds the lock (no variable by default); it is set while the lock is held. */
  readonly inheritEnv?: string;
  /** How long a waiting run waits before it gives up and returns nothing (no limit by default). */
  readonly timeoutMs?: number;
  /** How old a lock file that cannot be read must be before it counts as abandoned (2 s by default): a file just made by a run that has not finished writing it is not. */
  readonly unreadableGraceMs?: number;
};

How to take a lock.

Heldtypeno test imports it
type Held = {
  /** Who holds it: this process. */
  readonly holder: Holder;
  /** The lock given back (the file removed where it is still this holder's); safe to call twice. */
  release(): void;
};

A lock taken.

processRunsfunction
function processRuns(pid: number): boolean

Whether a process runs: a signal of 0 checks without sending one. A process of another account counts as running.

Imported by 6 tests of the run (6 passed, 0 failed): the library's results

readHolderfunction
function readHolder(path: string): Promise<Holder | undefined>

Who holds the lock at path, where its file can be read; whether that process still runs is not checked here.

Imported by 6 tests of the run (6 passed, 0 failed): the library's results

describeHolderfunction
function describeHolder(h: Holder, now?: number): string

A holder as a person reads it: update (pid 4242, for 3m 12s).

Imported by 6 tests of the run (6 passed, 0 failed): the library's results

acquireLockfunction
function acquireLock(path: string, options: LockOptions): Promise<Held | undefined>

The lock at path taken, or undefined where it is held by a running process and wait is false (or timeoutMs passed). A lock whose holder no longer runs, or whose file cannot be read, is taken over. Where inheritEnv is set in the environment, a parent holds it, and it is given at once (its release does nothing).

Imported by 6 tests of the run (6 passed, 0 failed): the library's results

Titles, headings, exports, tables, columns and requirements. Esc closes.